¿Qué es una API de catálogo en una tienda online?

«API de catálogo» suena a algo que solo toca el equipo técnico, pero la ves cada vez que instalas una app: es lo que hay detrás de la pantalla en la que la app pide permiso para ver o modificar tus productos. No es un archivo de productos que la tienda exporta, ni la API con la que tu web enseña el catálogo al comprador. Es la puerta de administración del catálogo, y lo que una app puede hacer con tus fichas es exactamente lo que le dejas hacer por ella.

Cómo funciona

Una plataforma de comercio tiene dos tipos de API sobre el mismo catálogo. Las de administración leen y escriben: crean productos, cambian precios, rellenan campos. Las de storefront están hechas para el comprador. BigCommerce las describe como pensadas para las acciones de quien compra en la tienda: consultar el catálogo, iniciar sesión, llenar el carrito y pagar. Están limitadas al contexto de un comprador concreto, mientras que las de administración trabajan sin esa limitación.⁠^{[1]BigCommerce Developer Learning. Storefront APIs} Cuando una app tuya necesita cambiar algo, pide la primera.

En BigCommerce, la de administración se llama literalmente Catalog API: gestiona productos, categorías, marcas, reglas de precios por volumen y más, y los productos viven en la ruta /v3/catalog/products. Entre sus campos están los que importan para el SEO: page_title, meta_description, search_keywords y custom_url.⁠^{[2]BigCommerce API Reference. Catalog - Products} Para cambiar varios productos de una vez se usa una petición PUT a esa misma ruta con una lista de productos, cada uno con su id, y cada lote admite como máximo 10 productos.⁠^{[3]BigCommerce API Reference. Update Products (batch)}

En Shopify no hay una «API de catálogo» con ese nombre: los productos se leen y se escriben con la Admin API de GraphQL. La operación productUpdate cambia el título, la descripción, el fabricante o los medios de un producto, y admite también los campos de SEO (seo, con title y description) y los metafields. Lo que no hace es cambiar las variantes, que tienen su propia operación, productVariantsBulkUpdate.⁠^{[4]Shopify Dev Docs. productUpdate (GraphQL Admin API)}

Los permisos

Cada app entra con unos permisos concretos, que en las dos plataformas se llaman scopes. En Shopify, read_products y write_products dan acceso a los productos, sus variantes y las colecciones, entre otros recursos. Dos reglas de su documentación: un permiso de escritura incluye la lectura del mismo recurso, así que el de escritura solo se pide si la app de verdad necesita las dos cosas, y una app debe pedir solo los datos que necesita para funcionar.⁠^{[5]Shopify Dev Docs. Access scopes} productUpdate exige write_products.⁠^{[4]Shopify Dev Docs. productUpdate (GraphQL Admin API)} En BigCommerce, la lectura del catálogo es store_v2_products_read_only y la modificación, store_v2_products.⁠^{[3]BigCommerce API Reference. Update Products (batch)}

Esta tabla es la que conviene tener delante cuando una app te enseña su pantalla de permisos. Una herramienta que solo informa sobre tu catálogo no necesita la segunda fila.

En una tienda

Un ejemplo ficticio: una tienda de trípodes quiere cambiar la meta description de su producto 112. En BigCommerce, la petición iría a la ruta de productos, con un lote de uno:⁠^{[3]BigCommerce API Reference. Update Products (batch)}

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products
Content-Type: application/json

[
  { "id": 112, "meta_description": "Trípode de viaje de carbono para cámaras sin espejo." }
]

En Shopify, la misma tarea es una mutación de GraphQL sobre el producto, con el campo seo:⁠^{[4]Shopify Dev Docs. productUpdate (GraphQL Admin API)}

mutation {
  productUpdate(
    product: {
      id: "gid://shopify/Product/112"
      seo: { description: "Trípode de viaje de carbono para cámaras sin espejo." }
    }
  ) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}

La mutación de Shopify pide de vuelta una lista userErrors, y hay que leerla: una respuesta sin error de red puede traer dentro el cambio rechazado.⁠^{[4]Shopify Dev Docs. productUpdate (GraphQL Admin API)} Clione escribe en las tiendas por este mismo camino: publica sus señales con las API de la propia plataforma, y solo cuando el comerciante pulsa Push.

Cómo comprobarlo

1. Haz la lista de apps con acceso a tus productos y, para cada una, apunta si tiene lectura o escritura. En Shopify, los permisos que pide cada app los declara la propia app.⁠^{[5]Shopify Dev Docs. Access scopes}
2. Compara cada permiso con lo que hace la app, con la tabla de arriba. Si solo informa, no necesita escribir.
3. Si una app escribe en campos que también edita tu equipo o tu PIM, decide quién manda en cada campo, o el último en escribir gana y el otro pierde su cambio: es la sobrescritura de campos.
4. Después de un cambio por API, vuelve a leer el producto con la propia API y abre el código fuente de la ficha: el primer paso confirma que el dato está guardado; el segundo, que se publica.
5. En BigCommerce, divide los cambios masivos en lotes de 10 productos como máximo.⁠^{[3]BigCommerce API Reference. Update Products (batch)}

Concepto cercano: feed de productos

Un feed de productos es lo contrario de una puerta de administración: un archivo con los datos del catálogo, preparado con el formato que pide otro canal para que ese canal lo lea. Google Merchant Center, por ejemplo, admite los datos de producto en feeds de texto o XML, o por su propia API, y tiene su especificación de cómo deben venir.⁠^{[6]Ayuda de Google Merchant Center. Product data specification} La API de catálogo es la fuente; el feed es una copia que sale de ella hacia otro sitio. Y si lo que necesitas no es preguntar por los cambios sino que la plataforma te avise cuando ocurren, eso es un webhook: Shopify lo presenta como la alternativa a consultar la API una y otra vez.⁠^{[7]Shopify Dev Docs. About webhooks}

Para seguir, el estudio del dato guardado al dato publicado mide la distancia entre lo que acepta la API y lo que sale en la ficha, y la ruta de lectura de publicación por plataforma ordena el resto de términos.