Plate-forme Instagram

Identification de produits

Vous pouvez utiliser l’API Graph pour Instagram afin de créer et gérer des tags de produit liés à la Boutique Instagram dans les contenus multimédias Instagram d’Instagram Business.

Remarque : à compter du 10 août 2023, certaines entreprises sans boutique avec option de paiement activée ne pourront plus identifier leurs produits à l’aide de l’API Content Publishing. Cela concernera l’API et les interfaces natives, et aura pour conséquence de supprimer les tags sur les produits des publications précédentes. La clientèle pourra toujours identifier les produits des boutiques avec option de paiement activée sur Facebook et Instagram. Vous pouvez toujours vous référer au champ shopping_product_tag_eligibility pour vérifier si un compte Instagram est éligible afin d’identifier ses produits à l’aide de l’API Content Publishing.

La procédure habituelle pour identifier des produits est la suivante :

  1. Vérifiez si Instagram Business a le droit d’identifier des produits.
  2. Si c’est le cas, obtenez ses catalogues produits.
  3. Recherchez dans chaque catalogue les produits qui peuvent être identifiés.
  4. Créez un conteneur de contenus multimédias identifiés.
  5. Publiez le conteneur de contenus multimédias identifiés.

Limites

  • Toutes les limites de publication de contenu s’appliquent lorsqu’il s’agit de l’identification de produits.
  • L’identification de produits n’est pas prise en charge pour les stories et les directs.
  • L’identification de produits n’est pas prise en charge pour les comptes Creator Instagram.
  • Les comptes sont limités à 25 publications de contenus multimédias identifiés par période de 24 heures. Les albums de carrousel comptent pour une seule publication.

Conditions requises

  • Consultez le document de référence de chaque point de terminaison pour déterminer les autorisations, fonctionnalités et tokens d’accès utilisateur nécessaires à chaque opération.
  • Le compte business Instagram (utilisateur·ice Instagram) qui possède le contenu multimédia Instagram (à identifier) doit disposer d’une Boutique Instagram approuvée avec un catalogue contenant des produits. Les méthodes de paiement dans l’application et de Boutique Instagram externe sont prises en charge.
  • L’utilisateur ou l’utilisatrice de l’application doit avoir un rôle d’admin dans le Business Manager qui détient la Boutique Instagram dont les produits sont utilisés pour identifier le contenu multimédia.
  • Pour demander une approbation Contrôle app pour les autorisations instagram_shopping_tag_products et catalog_management, qui sont requises par plusieurs points de terminaison d’identification de produits, votre application doit être associée à une entreprise vérifiée.

Points de terminaison

Vérifier l’éligibilité de l’utilisateur·ice

Au niveau du champ shopping_product_tag_eligibility sur le point de terminaison Utilisateur·ice Instagram, cherchez à déterminer si le compte business Instagram a configuré une Boutique Instagram. Les comptes qui n’ont pas configuré de Boutique Instagram ne peuvent pas identifier de produits.

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

Renvoie true si le compte business Instagram a été associé à une Boutique Instagram approuvée d’un Business Manager. Dans le cas contraire, renvoie false.

Exemple de requête

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

Exemple de réponse

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

Obtenir des catalogues

Utilisez le point de terminaison Catalogues disponibles des utilisateur·ices Instagram pour obtenir le catalogue produits du compte business Instagram.

GET /{ig-user-id}/available_catalogs

Renvoie un tableau de catalogues et leurs métadonnées. Les réponses peuvent inclure les champs de catalogue suivants :

  • catalog_id : ID du catalogue.
  • catalog_name : nom du catalogue.
  • shop_name : nom de la Boutique.
  • product_count : nombre total de produits dans le catalogue.

Limites

Les catalogues collaboratifs tels que les catalogues de partenaires shopping ou de créateurs affiliés ne sont pas pris en charge.

Exemple de requête

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

Exemple de réponse

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

Obtenir les produits éligibles

Utilisez le point de terminaison Recherche de produits dans le catalogue des utilisateur·ices Instagram pour obtenir un ensemble de produits dans ce catalogue pouvant servir à identifier des contenus multimédias. Les variantes de produit sont prises en charge.

Bien que l’API ne renvoie aucune erreur au moment de publier une publication identifiée avec un produit non approuvé, le tag n’apparaît pas dans la publication publiée tant que le produit n’est pas approuvé. Aussi, nous vous recommandons d’autoriser uniquement les utilisateurs et utilisatrices de votre application à publier des publications comportant des tags lorsque les produits renvoient la valeur approved pour le paramètre review_status. Ce champ est renvoyé par défaut pour chaque produit quand vous obtenez les produits éligibles d’un utilisateur ou d’une utilisatrice de l’application.

GET /{ig-user-id}/catalog_product_search

Paramètres

  • catalog_id : (obligatoire) ID du catalogue.
  • q : chaîne à rechercher dans chaque nom ou SKU de produit (colonne ID de contenu dans l’interface de gestion de catalogues). Si aucune chaîne n’est indiquée, tous les produits acceptant des tags seront renvoyés.

Renvoie un objet contenant un tableau de produits acceptant les tags et leurs métadonnées. Prend en charge la pagination en fonction de curseurs. Les réponses peuvent inclure les champs de produit suivants :

  • image_url : URL de l’image du produit.
  • is_checkout_flow : si ce champ est défini sur true, il est possible d’acheter le produit directement dans l’application Instagram. S’il est défini sur false, le produit doit être acheté dans l’application dont se sert l’utilisateur ou l’utilisatrice ou encore sur le site web.
  • merchant_id : ID du commerçant.
  • product_id : ID du produit.
  • product_name : nom du produit.
  • retailer_id : ID du retailer.
  • review_status : statut de l’examen. Les valeurs peuvent être approved, outdated, pending et rejected. Un produit approuvé peut apparaître dans la Boutique Instagram de l’utilisateur·ice de l’application, mais un statut approuvé n’indique pas qu’il est disponible (par exemple, le produit pourrait très bien être en rupture de stock). Seuls les tags associés aux produits dont le paramètre review_status a pour valeur approved peuvent apparaître dans les publications publiées.
  • product_variants : ID de produit (product_id) et noms de variante (variant_name) des variantes de produit.

Exemple de requête

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

Exemple de réponse

{
  "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"
            }
          ]
    }
  ]
}

Créer un conteneur identifié pour des images ou des vidéos

Utilisez le point de terminaison Contenu multimédia d’un utilisateur ou d’une utilisatrice Instagram afin de créer un conteneur de contenus multimédias pour une image ou une vidéo. De même, consultez les sections Créer un conteneur de contenus multimédias identifiés pour les Reels ou Carrousels.

POST /{ig-user-id}/media

Paramètres

  • image_url : (obligatoire pour les images uniquement) chemin de l’image. Votre image doit se trouver sur un serveur public.
  • user_tags : (images uniquement) tableau de noms d’utilisateur publics et de coordonnées x/y pour l’ensemble des utilisateurs et utilisatrices Instagram publics que vous souhaitez identifier dans l’image. Ce tableau doit être au format JSON et contenir des propriétés username, x et y. Exemple : [{username:'natgeo',x:0.5,y:1.0}]. Les valeurs x et y doivent être des nombres à virgule flottante calculés en partant de la partie supérieure gauche de l’image, dans une plage allant de 0.0 à 1.0. Les utilisateur·ices identifié·es recevront une notification à la publication du contenu multimédia.
  • video_url : (obligatoire pour les vidéos uniquement) chemin de la vidéo. Votre vidéo doit se trouver sur un serveur public.
  • thumb_offset : (vidéos uniquement) emplacement en millisecondes, dans la vidéo, de l’image à utiliser comme miniature de couverture pour la vidéo. La valeur par défaut est 0, ce qui correspond à la première image de la vidéo.
  • product_tags : (obligatoire) ensemble d’objets indiquant les tags de produit à ajouter à l’image ou à la vidéo. Chaque publication de photo ou de vidéo peut contenir jusqu’à 20 tags, et chaque carrousel peut contenir 20 tags (dans la limite de 5 tags par page du carrousel).
    • Les ID de produit et tags doivent être uniques.
    • Les tags pour les produits en rupture de stock sont pris en charge.
    • Chaque objet doit contenir les informations suivantes :
      • product_id : (obligatoire) ID du produit.
      • x : (images uniquement) nombre à virgule flottante indiquant la distance en pourcentage à partir du bord gauche de l’image du contenu multimédia publié. La valeur doit être comprise entre 0.0 et 1.0.
    • y : (images uniquement) nombre à virgule flottante indiquant la distance en pourcentage à partir du bord supérieur de l’image du contenu multimédia publié. La valeur doit être comprise entre 0.0 et 1.0.

Si l’opération aboutit, l’API renvoie un ID de conteneur qui peut être utilisé pour la publication du conteneur.

Exemple de requête

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..."

À titre de référence, voici la chaîne de charge utile POST décodée au moyen d’un formulaire HTML :

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...

Exemple de réponse

{
  "id": "17969578066508312"
}

Créer un conteneur identifié pour les Reels

Utilisez le point de terminaison Contenu multimédia d’utilisateur·ice Instagram afin de créer un conteneur de contenus multimédias pour les Reels. De même, consultez les sections Créer un conteneur de contenus multimédias identifiés ou Carrousels.

POST /{ig-user-id}/media

Paramètres

  • media_type : vous devez indiquer le type de contenu multimédia REELS.
  • video_url : chemin de la vidéo du Reel. Votre vidéo doit se trouver sur un serveur public. Votre vidéo doit répondre aux spécifications des Reels.
  • thumb_offset : emplacement en millisecondes, dans la vidéo, de l’image à utiliser comme miniature de couverture pour la vidéo. La valeur par défaut est 0, ce qui correspond à la première image de la vidéo.
  • caption : sous-titres du Reel.
  • product_tags : (obligatoire) ensemble d’objets indiquant les tags de produit à ajouter au Reel. Vous pouvez spécifier jusqu’à 30 tags, et les tags et les identifiants de produits doivent être uniques. Les tags pour les produits en rupture de stock sont pris en charge. Chaque objet doit contenir les informations suivantes :
    • product_id : (obligatoire) ID du produit.
  • location_id : ID d’une Page associée à un lieu avec lequel vous souhaitez identifier la vidéo. Pour plus d’informations, consultez la section Paramètres de chaîne de recherche de contenu multimédia d’utilisateur·ice Instagram.
  • share_to_feed : true pour demander que la vidéo apparaisse sur les onglets Fil et Reels. false pour demander que la vidéo apparaisse uniquement dans l’onglet Reels.
  • access_token : votre token d’accès utilisateur.

Si l’opération aboutit, l’API renvoie un ID de conteneur qui peut être utilisé pour la publication du conteneur.

Exemple de requête

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..."

À titre de référence, voici la chaîne de charge utile POST décodée au moyen d’un formulaire HTML :

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

Exemple de réponse

{
  "id": "17969578066508312"
}

Publier un conteneur multimédia identifié

Utilisez le point de terminaison Publication de contenu multimédia d’utilisateur·ice Instagram afin de publier le conteneur de contenus multimédias identifiés. Vous pouvez publier jusqu’à 25 conteneurs de contenus multimédias identifiés pour le compte d’un utilisateur ou d’une utilisatrice de l’application par période glissante de 24 heures. Si vous publiez un carrousel, consultez la section Carrousels. Seuls les produits dont le paramètre review_status présente la valeur approved apparaîtront dans les publications publiées. Si l’un de ces produits est en rupture de stock, ses tags resteront visibles sur la publication publiée.

POST /{ig-user-id}/media_publish

Paramètres

  • creation_id : (obligatoire) ID du conteneur pour carrousel.

Si l’opération aboutit, l’API renvoie un ID de contenu multimédia Instagram.

Exemple de requête

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

Exemple de réponse

{
  "id": "90010778325754"
}

Obtenir les tags des contenus multimédias

Utilisez le point de terminaison Tags de produit de contenu multimédia Instagram pour obtenir les tags sur un contenu multimédia publié.

GET /{ig-media-id}/product_tags

Renvoie un tableau de tags de produit ainsi que leurs métadonnées correspondant à un contenu multimédia Instagram. Les réponses peuvent inclure les champs de tag de produit suivants :

  • product_id : ID du produit.
  • merchant_id : ID du commerçant ou de la commerçante.
  • name : nom du produit.
  • price_string : prix du produit.
  • image_url : URL de l’image du produit.
  • review_status : indique le statut d’éligibilité des tags de produit. Les valeurs possibles sont les suivantes :
  • approved : le produit est approuvé.
  • rejected : le produit a été rejeté.
  • pending : l’analyse est toujours en cours.
  • outdated : le produit a été approuvé, mais il a été modifié et nécessite alors une nouvelle approbation.
  • "" : aucun statut d’examen.
  • no_review : aucun statut d’examen.
  • is_checkout : si ce champ est défini sur true, il est possible d’acheter le produit directement par l’intermédiaire de l’application Instagram. Si false, il est uniquement possible d’acheter le produit sur le site web du commerçant.
  • stripped_price_string : chaîne correspondant au prix du produit et écrite dans un format réduit (le prix est affiché dans un endroit où l’espace est limité, par exemple $100 au lieu de 100 USD).
  • string_sale_price_string : prix de vente du produit.
  • x : nombre à virgule flottante indiquant la distance en pourcentage à partir du bord gauche de l’image du contenu multimédia. La valeur est comprise entre 0.0 et 1.0.
  • y : nombre à virgule flottante indiquant la distance en pourcentage à partir du bord supérieur de l’image du contenu multimédia. La valeur est comprise entre 0.0 et 1.0.

Exemple de requête

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

Exemple de réponse

{
  "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
    }
  ]
}

Identifier les contenus multimédias existants

Utilisez le point de terminaison Tags de produit de contenu multimédia Instagram pour créer ou mettre à jour des tags sur les contenus multimédias Instagram existants.

POST /{ig-media-id}/product_tags

Paramètres

  • updated_tags : (obligatoire) tableau d’objets indiquant quels tags de produit doivent être associés à l’image ou à la vidéo (5 maximum, les tags et ID de produit doivent être uniques). Chaque objet doit contenir les informations suivantes :
  • product_id : (obligatoire) ID du produit. Si le contenu multimédia Instagram n’a pas été identifié avec cet ID, le tag sera ajouté au contenu. Si le contenu multimédia a déjà été identifié avec cet ID, les coordonnées d’affichage du tag seront mises à jour.
  • x : (images uniquement, obligatoire) nombre à virgule flottante indiquant la distance en pourcentage à partir du bord gauche de l’image du contenu multimédia publié. La valeur doit être comprise entre 0.0 et 1.0.
  • y : (images uniquement, obligatoire) nombre à virgule flottante indiquant la distance en pourcentage à partir du bord supérieur de l’image du contenu multimédia publié. La valeur doit être comprise entre 0.0 et 1.0.

Il est possible d’ajouter jusqu’à cinq tags aux contenus multimédias. Telle est la limite fixée. Si un tag de produit a déjà été ajouté aux contenus multimédias cibles dans la demande, les valeurs x et y de l’ancien tag seront mises à jour en utilisant les nouvelles valeurs (aucun nouveau tag ne sera ajouté).

Renvoie true si le produit a pu être mis à jour. Dans le cas contraire, renvoie false.

Exemple de requête

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..."

À titre de référence, voici la chaîne de charge utile POST décodée au moyen d’un formulaire HTML :

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

Exemple de réponse

{
  "success": true
}

Supprimer des tags

Utilisez le point de terminaison Tags de produit de contenu multimédia Instagram pour supprimer des tags sur un contenu multimédia Instagram publié incluant des Reels.

DELETE /{ig-media-id}/product_tags

Paramètres

  • deleted_tags : (obligatoire) tableau contenant les informations suivantes pour chaque tag de produit à supprimer :
  • merchant_id : (obligatoire) ID du commerçant ou de la commerçante.
  • product_id : (obligatoire) ID du produit.

Renvoie true si le tag a bien été supprimé. Dans le cas contraire, renvoie false.

Exemple de requête

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..."

À titre de référence, voici la chaîne de charge utile POST décodée au moyen d’un formulaire HTML :

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

Exemple de réponse

{
  "success": true
}

Effectuer une réclamation sur un produit rejeté

Utilisez le point de terminaison Réclamation d’utilisateur·ice Instagram sur les produits si vous souhaitez permettre aux utilisateurs et utilisatrices de votre application d’effectuer une réclamation concernant les rejets de produits (les tags des produits rejetés n’apparaîtront pas sur les publications publiées). Bien que cela ne soit pas obligatoire, nous vous recommandons vivement d’offrir aux utilisateur·ices de votre application un moyen d’effectuer une réclamation sur les rejets de produits, ou de leur conseiller de le faire par le biais du Business Manager.

POST /{ig-user-id}/product_appeal

Paramètres

  • appeal_reason : (obligatoire) chaîne expliquant pourquoi le produit doit être approuvé.
  • product_id : (obligatoire) ID du produit.

Renvoie true si votre demande est recevable. Dans le cas contraire, renvoie false. La réponse n’indique en rien l’issue de la réclamation.

Exemple de requête

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..."

Exemple de réponse

{
  "success": true
}

Obtenir le statut de la réclamation

Utilisez le point de terminaison Réclamation d’utilisateur·ice Instagram sur les produits pour obtenir le statut d’une réclamation concernant un produit rejeté donné :

GET /{ig-user-id}/product_appeal

Paramètres

  • product_id : (obligatoire) ID du produit.

Renvoie les métadonnées du statut de la réclamation. Les réponses peuvent inclure les champs de réclamation suivants :

  • eligible_for_appeal : indique s’il est possible de faire appel de la décision (si oui true, si non false).
  • product_id : ID du produit.
  • review_status : statut de l’examen. La valeur peut être :
  • approved : le produit est approuvé.
  • rejected : le produit a été rejeté.
  • pending : l’analyse est toujours en cours.
  • outdated : le produit a été approuvé, mais il a été modifié et nécessite alors une nouvelle approbation.
  • "" : aucun statut d’examen.
  • no_review : aucun statut d’examen.

Exemple de requête

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

Exemple de réponse

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

Carrousels

Vous pouvez publier des carrousels (albums) contenant jusqu’à 10 images et/ou vidéos identifiées. Pour ce faire, lorsque vous exécutez l’étape 1 sur 3 du processus de publication des publications de carrousel, il vous suffit de créer des conteneurs de contenus multimédias identifiés pour chaque image ou vidéo identifiée que vous souhaitez inclure dans l’album de carrousel et de poursuivre par le processus de publication de carrousel comme vous le feriez normalement.

Obtenir le contenu multimédia enfant dans un carrousel

Pour obtenir les ID des contenus multimédias Instagram dans un album de carrousel, utilisez le point de terminaison Enfants de contenu multimédia Instagram.