# Qué es una API de catálogo en Shopify y BigCommerce

> Qué es la API de catálogo de una tienda online, cómo separa leer de escribir en Shopify y BigCommerce, y qué permisos mínimos dar a cada app.

URL: https://clione.ai/es/glosario/api-de-catalogo/
Lang: es

«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.[^bc-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`.[^bc-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**.[^bc-update-products]

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](/es/glosario/metafields/). Lo que no hace es cambiar las variantes, que tienen su propia operación, `productVariantsBulkUpdate`.[^shopify-productupdate]

## 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.[^shopify-scopes] `productUpdate` exige `write_products`.[^shopify-productupdate] En BigCommerce, la lectura del catálogo es `store_v2_products_read_only` y la modificación, `store_v2_products`.[^bc-update-products]

| Lo que hace la app                                                               | BigCommerce                   | Shopify          |
| -------------------------------------------------------------------------------- | ----------------------------- | ---------------- |
| Leer títulos, descripciones y campos de SEO                                      | `store_v2_products_read_only` | `read_products`  |
| Cambiar la descripción o la [_meta description_](/es/glosario/meta-description/) | `store_v2_products`           | `write_products` |

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:[^bc-update-products]

```http
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`:[^shopify-productupdate]

```graphql
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.[^shopify-productupdate] 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.


**Una respuesta correcta de la API dice que el dato está guardado, no que la ficha lo enseñe.** La API escribe en la plataforma; lo que sale en la página lo decide el tema o el frontend que lee ese dato. Y dos confusiones de permisos que se repiten: dar escritura a una app que solo necesita leer, cuando Shopify recomienda pedir solo lo necesario,[^shopify-scopes] y esperar que `productUpdate` cambie también las variantes, que tienen su propia operación.[^shopify-productupdate]


## 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.[^shopify-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](/es/glosario/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](/es/glosario/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.[^bc-update-products]

## Concepto cercano: feed de productos

Un [feed de productos](/es/glosario/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](/es/glosario/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.[^gmc-spec] **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](/es/glosario/webhook/): Shopify lo presenta como la alternativa a consultar la API una y otra vez.[^shopify-webhooks]

Para seguir, el estudio [del dato guardado al dato publicado](/es/estudios/dato-guardado-vs-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](/es/aprender/publicacion-por-plataforma/) ordena el resto de términos.