Plataforma de Instagram

Etiquetado de productos

La API Graph de Instagram se puede utilizar para crear y administrar etiquetas de productos de compras en Instagram en el contenido multimedia de Instagram de una cuenta de Instagram para empresas.

Nota: A partir del 10 de agosto de 2023, las empresas cuyas tiendas no tengan activada la finalización de compra no podrán etiquetar los productos con la API de publicación de contenido. Este cambio afectará tanto a la API como a las interfaces nativas y las etiquetas de los productos se eliminarán de las publicaciones anteriores. Los clientes podrán seguir etiquetando los productos de las tiendas que tengan activada la finalización de compra en Facebook e Instagram. Puedes seguir consultando el campo shopping_product_tag_eligibility para comprobar si una cuenta de Instagram cumple los requisitos para etiquetar los productos con la API de publicación de contenido.

El proceso general de etiquetado de productos es el siguiente:

  1. Comprueba si la empresa de Instagram cumple los requisitos del etiquetado de productos.
  2. Si la empresa de Instagram los cumple, obtén sus catálogos de productos.
  3. Busca en cada catálogo los productos que cumplan los requisitos del etiquetado.
  4. Crea un contenedor de archivos multimedia etiquetados.
  5. Publica el contenedor de archivos multimedia etiquetados.

Limitaciones

  • Todas las limitaciones de publicación de contenido se aplican al etiquetado de productos.
  • El etiquetado de productos no es compatible con Stories ni Live.
  • El etiquetado de productos no es compatible con las cuentas de creador de Instagram.
  • Las cuentas están limitadas a 25 publicaciones etiquetadas de contenido multimedia por cada periodo de 24 horas. Los álbumes de secuencia se consideran una única publicación.

Requisitos

  • Consulta el documento de referencia de cada extremo a fin de determinar los permisos, las funciones y los identificadores de acceso de usuario necesarios para cada operación.
  • La cuenta de Instagram para empresas (usuario de Instagram) que es propietaria del contenido multimedia de Instagram (que se va a etiquetar) debe tener una Tienda de Instagram aprobada con un catálogo de productos que contenga productos. Se admiten los métodos de finalización de compra de Tiendas de Instagram en la aplicación y externos.
  • El usuario de la aplicación debe tener un rol de administrador en el Business Manager propietario de la tienda de Instagram cuyos productos se usan para etiquetar el contenido multimedia.
  • Para solicitar la aprobación de la revisión de la aplicación para los permisos instagram_shopping_tag_products y catalog_management (que son necesarios para varios extremos de etiquetado de productos), la aplicación debe estar asociada a una empresa verificada.

Extremos

Obtener la idoneidad de un usuario

Solicita el campo shopping_product_tag_eligibility en el extremo de usuario de Instagram para determinar si la cuenta de Instagram de la empresa ha configurado una Tienda de Instagram. Las cuentas que no hayan configurado una Tienda de Instagram no cumplen los requisitos del etiquetado de productos.

GET /{ig-user-id}?fields=shopping_product_tag_eligibility

Devuelve true si la cuenta de Instagram de la empresa se ha asociado a una tienda de Instagram aprobada de Business Manager; en caso contrario, devuelve false.

Ejemplo de solicitud

curl -i -X GET \
 "https://graph.facebook.com/v19.0/90010177253934?fields=shopping_product_tag_eligibility&access_token=EAAOc..."

Ejemplo de respuesta

{
  "shopping_product_tag_eligibility": true,
  "id": "90010177253934"
}

Obtener los catálogos

Usa el extremo de los catálogos disponibles del usuario de Instagram para obtener el catálogo de productos de la cuenta de Instagram de la empresa.

GET /{ig-user-id}/available_catalogs

Devuelve una matriz de catálogos y los metadatos correspondientes. En las respuestas, se pueden incluir los siguientes campos de catálogo:

  • catalog_id: identificador del catálogo.
  • catalog_name: nombre del catálogo.
  • shop_name: nombre de la tienda.
  • product_count: número total de productos del catálogo.

Limitaciones

No se admiten los catálogos colaborativos, como los catálogos de socios de compras o los catálogos de creadores afiliados.

Ejemplo de solicitud

curl -i -X GET \
 "https://graph.facebook.com/v19.0/90010177253934?fields=available_catalogs&access_token=EAAOc..."

Ejemplo de respuesta

{
  "available_catalogs": {
    "data": [
      {
        "catalog_id": "960179311066902",
        "catalog_name": "Jay's Favorite Snacks",
        "shop_name": "Jay's Bespoke",
        "product_count": 11
      }
    ]
  },
  "id": "90010177253934"
}

Obtener los productos que cumplen los requisitos

Utiliza el extremo de búsqueda de productos en el catálogo de un usuario de Instagram para obtener una colección de productos del catálogo que se pueden usar para etiquetar contenido multimedia. Se admiten las variantes de productos.

Aunque la API no devolverá ningún error al realizar una publicación etiquetada con un producto no aprobado, la etiqueta no aparecerá en la publicación hasta que el producto se haya aprobado. Por lo tanto, te recomendamos que solo permitas a los usuarios de la aplicación realizar publicaciones con etiquetas cuyos productos tengan el valor approved en la propiedad review_status. Este campo se devuelve para cada producto de forma predeterminada al obtener los productos de un usuario de la aplicación que cumplen los requisitos.

GET /{ig-user-id}/catalog_product_search

Parámetros

  • catalog_id: (obligatorio) identificador del catálogo.
  • q: cadena que se va a buscar en el nombre de cada producto o número de SKU de un producto (la columna Identificador de contenido de la interfaz de administración de catálogos). Si no se especifica ninguna cadena, se devolverán todos los productos que cumplan los requisitos de las etiquetas.

Devuelve un objeto que contiene una matriz de productos que cumplen los requisitos de las etiquetas y los metadatos correspondientes. Admite la paginación basada en cursores. En las respuestas, se pueden incluir los siguientes campos de producto:

  • image_url: URL de la imagen del producto.
  • is_checkout_flow: si el valor es true, el producto se puede comprar directamente en la aplicación de Instagram. Si el valor es false, el producto se debe comprar en la aplicación o el sitio web del usuario de la aplicación.
  • merchant_id: identificador del comerciante.
  • product_id: identificador del producto.
  • product_name: nombre del producto.
  • retailer_id: identificador del minorista.
  • review_status: estado de la revisión. Los valores pueden ser approved, outdated, pending y rejected. Un producto aprobado puede aparecer en la Tienda de Instagram de un usuario de la aplicación, pero un estado aprobado no indica su disponibilidad (es decir, el producto podría estar agotado). En las publicaciones, solo pueden aparecer etiquetas asociadas a productos que tengan el valor approved en la propiedad review_status.
  • product_variants: identificadores de productos (product_id) y nombres (variant_name) de variantes de productos.

Ejemplo de solicitud

curl -i -X GET \
 "https://graph.facebook.com/v19.0/90010177253934/catalog_product_search?catalog_id=960179311066902&q=gummy&access_token=EAAOc..."

Ejemplo de respuesta

{
  "data": [
    {
      "product_id": 3231775643511089,
      "merchant_id": 90010177253934,
      "product_name": "Gummy Wombats",
      "image_url": "https://scont...",
      "retailer_id": "oh59p9vzei",
      "review_status": "approved",
      "is_checkout_flow": true,
      "product_variants": [
            {
              "product_id": 5209223099160494
            },
            {
              "product_id": 7478222675582505,
              "variant_name": "Green Gummy Wombats"
            }
          ]
    }
  ]
}

Crear un contenedor etiquetado para imágenes o vídeos

Utiliza el extremo de contenido multimedia de usuario de Instagram a fin de crear un contenedor de archivos multimedia para una imagen o un vídeo. Como alternativa, puedes consultar Crear un contenedor de archivos multimedia etiquetados para Reels o Secuencias.

POST /{ig-user-id}/media

Parámetros

  • image_url: (obligatorio solo para imágenes) ruta de la imagen. La imagen debe estar en un servidor público.
  • user_tags: (solo imágenes) matriz de nombres de usuario públicos y coordenadas x/y para cualquier usuario de Instagram público que quieras etiquetar en la imagen. La matriz debe estar en formato JSON e incluir las propiedades username, x e y. Por ejemplo, [{username:'natgeo',x:0.5,y:1.0}]. Los valores de x e y deben ser flotantes y originarse en la esquina superior izquierda de la imagen, con un intervalo entre 0.0 y 1.0. Los usuarios etiquetados recibirán una notificación cuando se publique el contenido multimedia.
  • video_url: (obligatorio solo para vídeos) ruta del vídeo. El vídeo debe estar en un servidor público.
  • thumb_offset: (solo vídeos) ubicación, en milisegundos, del fotograma para la imagen en miniatura de la portada del vídeo. El valor predeterminado es 0, que es el primer fotograma del vídeo.
  • product_tags: (obligatorio) matriz de objetos que especifican las etiquetas de producto que se van a añadir a la imagen o el vídeo. Puedes especificar hasta 20 etiquetas para publicaciones con foto o vídeo en el feed y hasta 20 etiquetas en total por cada publicación de secuencia (hasta cinco por diapositiva).
    • Las etiquetas y los identificadores de producto deben ser únicos.
    • Se admiten las etiquetas para productos agotados.
    • Cada objeto debe tener la información siguiente:
      • product_id: (obligatorio) identificador del producto.
      • x: (solo imágenes) valor flotante que indica la distancia en porcentaje desde el borde izquierdo de la imagen del contenido multimedia publicado. El valor debe estar comprendido en el intervalo entre 0.0 y 1.0.
    • y: (solo imágenes) valor flotante que indica la distancia en porcentaje desde el borde superior de la imagen del contenido multimedia publicado. El valor debe estar comprendido en el intervalo entre 0.0 y 1.0.

Si la operación se realiza correctamente, la API devuelve un identificador de contenedor que se puede usar para publicar el contenedor.

Ejemplo de solicitud

curl -i -X POST \
 "https://graph.facebook.com/v19.0/90010177253934/media?image_url=https%3A%2F%2Fupl...&location_id=7640348500&product_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3231775643511089'%2C%0A%20%20%20%20x%3A%200.5%2C%0A%20%20%20%20y%3A%200.8%0A%20%20%7D%0A%5D&access_token=EAAOc..."

A modo de referencia, a continuación se incluye la cadena de la carga útil de la solicitud POST en código HTML descodificado:

https://graph.facebook.com/v12.0/90010177253934/media?image_url=https://upl...&location_id=7640348500 &product_tags=[ { product_id:'3231775643511089', x: 0.5, y: 0.8 } ]&access_token=EAAOc...

Ejemplo de respuesta

{
  "id": "17969578066508312"
}

Crear un contenedor etiquetado para Reels

Utiliza el extremo de contenido multimedia de usuario de Instagram a fin de crear un contenedor de archivos multimedia para Reels. Como alternativa, puedes consultar Crear un contenedor de archivos multimedia etiquetados o Secuencias.

POST /{ig-user-id}/media

Parámetros

  • media_type: debes especificar el tipo de contenido multimedia REELS.
  • video_url: ruta del vídeo para el reel. El vídeo debe estar en un servidor público. El vídeo debe cumplir las especificaciones de los reels.
  • thumb_offset: ubicación, en milisegundos, del fotograma para la imagen en miniatura de la portada del vídeo. El valor predeterminado es 0, que es el primer fotograma del vídeo.
  • caption: texto para el reel.
  • product_tags: (obligatorio) matriz de objetos que especifican las etiquetas de producto que se van a añadir al reel. Puedes especificar hasta 30 etiquetas; las etiquetas y los identificadores de producto deben ser únicos. Se admiten las etiquetas para productos agotados. Cada objeto debe tener la información siguiente:
    • product_id: (obligatorio) identificador del producto.
  • location_id: identificador de una página asociado a una ubicación con la que quieres etiquetar el vídeo. Para obtener información detallada, consulta Parámetros de la cadena de consulta de contenido multimedia de usuario de Instagram.
  • share_to_feed: se establece en true para solicitar que el vídeo aparezca en las pestañas “Sección de noticias” y “Reels”, y en false para solicitar que aparezca solo en la pestaña “Reels”.
  • access_token: tu identificador de acceso de usuario.

Si la operación se realiza correctamente, la API devuelve un identificador de contenedor que se puede usar para publicar el contenedor.

Ejemplo de solicitud

curl -i -X POST \
 "https://graph.facebook.com/v19.0/90010177253934/media?media_type=REELS&video_url=https://upl...&product_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3231775643511089'%0A%20%20%7D%0A%5D&access_token=EAAOc..."

A modo de referencia, a continuación se incluye la cadena de la carga útil de la solicitud POST en código HTML descodificado:

https://graph.facebook.com/v12.0/90010177253934/media?media_type=REELS&video_url=https://upl... &product_tags=[ { product_id:'3231775643511089' } ]&access_token=EAAOc...

Ejemplo de respuesta

{
  "id": "17969578066508312"
}

Publicar un contenedor de archivos multimedia etiquetados

Utiliza el extremo de publicación de contenido multimedia de usuario de Instagram para publicar el contenedor de archivos multimedia etiquetados. Puedes publicar un máximo de 25 contenedores de archivos multimedia etiquetados en nombre de un usuario de la aplicación por cada periodo dinámico de 24 horas. Si vas a publicar una secuencia, consulta Secuencias. En las publicaciones, solo aparecerán productos que tengan el valor approved en la propiedad review_status. Si alguno de estos productos está agotado, sus etiquetas seguirán apareciendo en la publicación.

POST /{ig-user-id}/media_publish

Parámetros

  • creation_id: (obligatorio) identificador del contenedor de la secuencia.

Si la operación se realiza correctamente, la API devolverá un identificador de contenido multimedia de Instagram.

Ejemplo de solicitud

curl -i -X POST \
 "https://graph.facebook.com/v19.0/90010177253934/media_publish?creation_id=17969578066508312&access_token=EAAOc"

Ejemplo de respuesta

{
  "id": "90010778325754"
}

Obtener las etiquetas del contenido multimedia

Utiliza el extremo de etiquetas de productos de contenido multimedia de Instagram para obtener las etiquetas de un contenido multimedia publicado.

GET /{ig-media-id}/product_tags

Devuelve una matriz de etiquetas de productos y los metadatos correspondientes de un contenido multimedia de Instagram. En las respuestas, se pueden incluir los siguientes campos de etiquetas de productos:

  • product_id: identificador del producto.
  • merchant_id: identificador del comerciante.
  • name: nombre del producto.
  • price_string: precio del producto.
  • image_url: URL de la imagen del producto.
  • review_status: indica el estado de idoneidad de la etiqueta de producto. Los valores pueden ser los siguientes:
  • approved: el producto se ha aprobado.
  • rejected: el producto se ha rechazado.
  • pending: todavía se está revisando.
  • outdated: el producto se ha aprobado, pero se ha editado y es necesario volver a aprobarlo.
  • "": sin estado de revisión.
  • no_review: sin estado de revisión.
  • is_checkout: si el valor es true, el producto se puede comprar directamente a través de la aplicación Instagram. Si el valor es false, el producto solo se puede comprar en el sitio web del comerciante.
  • stripped_price_string: cadena corta del precio del producto (precio mostrado en espacios limitados, como $100 en lugar de 100 USD).
  • string_sale_price_string: precio de oferta del producto.
  • x: valor flotante que indica la distancia en porcentaje desde el borde izquierdo de la imagen del contenido multimedia. Valor comprendido en el intervalo entre 0.0 y 1.0.
  • y: valor flotante que indica la distancia en porcentaje desde el borde superior de la imagen del contenido multimedia. Valor comprendido en el intervalo entre 0.0 y 1.0.

Ejemplo de solicitud

curl -i -X GET \
 "https://graph.facebook.com/v19.0/90010778325754/product_tags?access_token=EAAOc..."

Ejemplo de respuesta

{
  "data": [
    {
      "product_id": 3231775643511089,
      "merchant_id": 90010177253934,
      "name": "Gummy Wombats",
      "price_string": "$3.50",
      "image_url": "https://scont...",
      "review_status": "approved",
      "is_checkout": true,
      "stripped_price_string": "$3.50",
      "x": 0.5,
      "y": 0.80000001192093
    }
  ]
}

Etiquetar el contenido multimedia existente

Utiliza el extremo de etiquetas de productos de contenido multimedia de Instagram para crear o actualizar las etiquetas del contenido multimedia de Instagram existente.

POST /{ig-media-id}/product_tags

Parámetros

  • updated_tags: (obligatorio) matriz de objetos que especifica las etiquetas de productos con las que etiquetar la imagen o el vídeo (máximo cinco; las etiquetas y los identificadores de productos deben ser únicos). Cada objeto debe tener la información siguiente:
  • product_id: (obligatorio) identificador del producto. Si el contenido multimedia de Instagram no se ha etiquetado con este identificador, la etiqueta se añadirá al contenido multimedia de Instagram. Si el contenido multimedia ya se ha etiquetado con este identificador, se actualizarán las coordenadas de visualización de la etiqueta.
  • x: (solo imágenes, obligatorio) valor flotante que indica la distancia en porcentaje desde el borde izquierdo de la imagen del contenido multimedia publicado. El valor debe estar comprendido en el intervalo entre 0.0 y 1.0.
  • y: (solo imágenes, obligatorio) valor flotante que indica la distancia en porcentaje desde el borde superior de la imagen del contenido multimedia publicado. El valor debe estar comprendido en el intervalo entre 0.0 y 1.0.

El etiquetado de contenido multimedia se suma hasta alcanzar el límite de cinco etiquetas. Si el contenido multimedia de destino ya se ha etiquetado mediante un producto de la solicitud, los valores antiguos de x e y de la etiqueta se actualizarán con los nuevos valores (no se añadirá una nueva etiqueta).

Devuelve true si el producto se puede actualizar; de lo contrario, devuelve false.

Ejemplo de solicitud

curl -i -X POST \
 "https://graph.facebook.com/v19.0/90010778325754/product_tags?updated_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3859448974125379'%2C%0A%20%20%20%20x%3A%200.5%2C%0A%20%20%20%20y%3A%200.8%0A%20%20%7D%0A%5D&access_token=EAAOc..."

A modo de referencia, a continuación se incluye la cadena de la carga útil de la solicitud POST en código HTML descodificado:

https://graph.facebook.com/v12.0/90010778325754/product_tags?updated_tags=[ { product_id:'3859448974125379', x: 0.5, y: 0.8 } ]&access_token=EAAOc...

Ejemplo de respuesta

{
  "success": true
}

Eliminar las etiquetas

Utiliza el extremo de etiquetas de productos de contenido multimedia de Instagram para eliminar las etiquetas de un contenido multimedia de Instagram publicado (reels incluidos).

DELETE /{ig-media-id}/product_tags

Parámetros

  • deleted_tags: (obligatorio) matriz que contiene la siguiente información para cada etiqueta de producto que se va a eliminar:
  • merchant_id: (obligatorio) identificador del comerciante.
  • product_id: (obligatorio) identificador del producto.

Devuelve true si la etiqueta se elimina correctamente; de lo contrario, devuelve false.

Ejemplo de solicitud

curl -i -X DELETE \
 "https://graph.facebook.com/v19.0/90010778325754/product_tags?deleted_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3859448974125379'%2C%0A%20%20%20%20merchant_id%3A'90010177253934'%0A%20%20%7D%0A%5D&access_token=EAAOc..."

A modo de referencia, a continuación se incluye la cadena de la carga útil de la solicitud POST en código HTML descodificado:

https://graph.facebook.com/v12.0/90010778325754/product_tags?deleted_tags=[ { product_id:'3859448974125379', merchant_id:'90010177253934' } ]&access_token=EAAOc...

Ejemplo de respuesta

{
  "success": true
}

Apelar el rechazo de un producto

Utiliza el extremo de apelación de un producto de usuario de Instagram si quieres proporcionar una forma para que los usuarios de la aplicación apelen los rechazos de productos (las etiquetas de los productos rechazados no aparecerán en las publicaciones). Aunque no es obligatorio, te sugerimos que proporciones una forma para que los usuarios de la aplicación apelen los rechazos o que les recomiendes apelar los rechazos mediante Business Manager.

POST /{ig-user-id}/product_appeal

Parámetros

  • appeal_reason: (obligatorio) explicación de por qué se debería aprobar el producto.
  • product_id: (obligatorio) identificador del producto.

Devuelve true si pudimos recibir tu solicitud; de lo contrario, devuelve false. El resultado de la apelación no se indica en la respuesta.

Ejemplo de solicitud

curl -i -X POST \

"https://graph.facebook.com/v19.0/90010177253934/product_appeal?appeal_reason=product%20is%20a%20toy%20and%20not%20a%20real%20weapon&product_id=4382881195057752&access_token=EAAOc..."

Ejemplo de respuesta

{
  "success": true
}

Obtener el estado de una apelación

Utiliza el extremo de apelación de productos de un usuario de Instagram para obtener el estado de la apelación de un producto rechazado determinado:

GET /{ig-user-id}/product_appeal

Parámetros

  • product_id: (obligatorio) identificador del producto.

Devuelve los metadatos del estado de una apelación. En las respuestas, se pueden incluir los siguientes campos de apelación:

  • eligible_for_appeal: indica si la decisión se puede apelar (si el valor es true, se puede apelar, pero si el valor es false, no).
  • product_id: identificador del producto.
  • review_status: estado de la revisión. El valor puede ser uno de los siguientes:
  • approved: el producto se ha aprobado.
  • rejected: el producto se ha rechazado.
  • pending: todavía se está revisando.
  • outdated: el producto se ha aprobado, pero se ha editado y es necesario volver a aprobarlo.
  • "": sin estado de revisión.
  • no_review: sin estado de revisión.

Ejemplo de solicitud

curl -i -X GET \
 "https://graph.facebook.com/v19.0/90010177253934/product_appeal?product_id=4029274203846188&access_token=EAAOc..."

Ejemplo de respuesta

{
  "data": [
    {
      "product_id": 4029274203846188,
      "review_status": "approved",
      "eligible_for_appeal": false
    }
  ]
}

Secuencias

Puedes publicar secuencias (álbumes) que incluyan un máximo de diez archivos multimedia etiquetados (imágenes, vídeos o una combinación de ambos). Para ello, en el paso 1 de 3 del proceso de publicación de una secuencia, crea contenedores de contenido multimedia etiquetado para cada imagen o vídeo etiquetado que quieras que aparezca en la secuencia del álbum y sigue con el proceso de publicación de la secuencia como lo harías normalmente.

Obtener los objetos multimedia dependientes de una secuencia

Para obtener los identificadores del contenido multimedia de Instagram de una secuencia de álbum, utiliza el extremo de objetos multimedia dependientes de Instagram.