Tag dei prodotti

Puoi utilizzare l'API Instagram Graph per la creazione e la gestione di tag dei prodotti di Shopping su Instagram sui contenuti multimediali di IG di un account business di Instagram.

Nota: a partire dal 10 agosto 2023, alcune aziende senza Shop con la procedura di acquisto abilitata non potranno più taggare i loro prodotti usando l'API Content Publishing. Questo avrà conseguenze sia sull'API che sulle interfacce native e rimuoverà i tag dei prodotti dai post precedenti. I clienti potranno ancora taggare i prodotti dagli Shop con la procedura di acquisto abilitata su Facebook e Instagram. Puoi comunque fare riferimento al campo shopping_product_tag_eligibility per controllare se un account Instagram è idoneo per il tag dei prodotti usando l'API Content Publishing.

Il flusso generale per l'aggiunta di tag dei prodotti è il seguente:

Controllo dell'idoneità dell'account business di Instagram per il tag dei prodotti
Se l'account business di Instagram è idoneo, acquisizione dei cataloghi prodotti
Ricerca in ogni catalogo dei prodotti idonei per l'aggiunta di tag
Creazione di un contenitore multimediale taggato
Pubblicazione del contenitore multimediale taggato

Limitazioni

Tutte le limitazioni di pubblicazione dei contenuti si applicano al tag dei prodotti.
Il tag dei prodotti non è supportato per storie e Live.
Il tag dei prodotti non è supportato per gli account creator di Instagram.
Gli account hanno un limite di aggiunta di tag a 25 post con contenuti multimediali in una finestra di 24 ore. Gli album carosello vengono considerati come un singolo post.

Requisiti

Consulta il documento di riferimento di ciascun endpoint per determinare quali autorizzazioni, funzioni e token d'accesso dell'utente sono necessari per ciascuna operazione.
L'account business di Instagram (utente Instagram) che possiede il contenuto multimediale di IG (da taggare) deve disporre di uno Shop di Instagram approvato con un catalogo prodotti contenente dei prodotti. Sono supportati i metodi di acquisto in-app ed esterni dello Shop di Instagram.
L'utente dell'app deve disporre di un ruolo di amministratore su Business Manager che possieda lo Shop di Instagram i cui prodotti vengano utilizzati per taggare i contenuti multimediali.
Per richiedere l'approvazione dell'Analisi dell'app per le autorizzazioni instagram_shopping_tag_products e catalog_management richieste da diversi endpoint di aggiunta di tag di prodotto, l'app deve essere associata a un'azienda verificata.

Endpoint

GET /{ig-user-id}: controlla l'idoneità dei tag dell'utente dell'app.
GET /{ig-user-id}/available_catalogs: ottiene una lista dei cataloghi prodotti dell'utente dell'app.
GET /{ig-user-id}/catalog_product_search: ottiene una lista di prodotti idonei per il tag nel catalogo dell'utente dell'app.
POST /{ig-user-id}/media: crea un contenitore multimediale taggato (passaggio 1 della procedura di pubblicazione).
POST /{ig-user-id}/media_publish: pubblica un contenitore multimediale taggato (passaggio 2 della procedura di pubblicazione).
GET /{ig-media-id}/product_tags: ottiene tag sui contenuti multimediali di IG pubblicati.
DELETE /{ig-media-id}/product_tags: elimina tag sui contenuti multimediali di IG pubblicati.
POST /{ig-media-id}/product_tags: crea o aggiorna tag sui contenuti multimediali di IG pubblicati.
GET /{ig-user-id}/product_appeal: ottiene informazioni sul ricorso per il prodotto.
POST /{ig-user-id}/product_appeal: invia un ricorso contro il rifiuto di un prodotto.
GET /{ig-media-id}/children: ottiene una lista di contenuti multimediali di IG secondari nei contenuti multimediali di IG del carosello.

Acquisizione dell'idoneità dell'utente

Richiedi il campo shopping_product_tag_eligibility sull'endpoint IG User per determinare se l'account business di Instagram abbia configurato uno Shop di Instagram. Gli account che non hanno configurato uno Shop di Instagram non sono idonei per i tag dei prodotti.

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

Restituisce true se l'account business di Instagram è stato associato a uno Shop di Instagram approvato di Business Manager, altrimenti restituisce false.

Esempio di richiesta

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

Esempio di risposta

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

Acquisizione dei cataloghi

Usa l'endpoint IG User Available Catalogs per l'acquisizione del catalogo prodotti dell'account business di Instagram.

GET /{ig-user-id}/available_catalogs

Restituisce un array di cataloghi e relativi metadati. Nelle risposte possono essere inclusi i seguenti campi del catalogo:

catalog_id: ID catalogo.
catalog_name: nome del catalogo.
shop_name: nome dello shop.
product_count: numero totale di prodotti presenti nel catalogo.

Limitazioni

I cataloghi collaborativi come i cataloghi dei partner di shopping o i cataloghi dei creator affiliati non sono supportati.

Esempio di richiesta

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

Esempio di risposta

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

Acquisizione di prodotti idonei

Usa l'endpoint IG User Catalog Product Search per ottenere una raccolta di prodotti presenti nel catalogo che possono essere utilizzati per taggare contenuti multimediali. Le varianti del prodotto sono supportate.

Sebbene l'API non restituisca un errore durante la pubblicazione di un post taggato con un prodotto non approvato, il tag non sarà visibile sul post pubblicato fino a quando il prodotto non verrà approvato. Pertanto, ti consigliamo di consentire solo agli utenti della tua app di pubblicare post con tag i cui prodotti abbiano review_status su approved. Questo campo viene restituito per ogni prodotto per impostazione predefinita quando si ottengono prodotti idonei di un utente dell'app.

GET /{ig-user-id}/catalog_product_search

Parametri

catalog_id: (obbligatorio) ID catalogo.
q: una stringa da cercare nel nome di ogni prodotto o nel numero SKU di un prodotto (la colonna ID del contenuto nell'interfaccia di gestione del catalogo). Se non viene specificata alcuna stringa, verranno restituiti tutti i prodotti idonei per il tag.

Restituisce un oggetto contenente un array di prodotti idonei per il tag e relativi metadati. Supporta la paginazione basata sul cursore. Nelle risposte possono essere inclusi i seguenti campi del prodotto:

image_url: URL dell'immagine del prodotto.
is_checkout_flow: se true, il prodotto può essere acquistato direttamente nell'app Instagram. Se false, il prodotto deve essere acquistato nell'app/nel sito web dell'utente dell'app.
merchant_id: ID venditore.
product_id: ID prodotto.
product_name: nome del prodotto.
retailer_id: ID rivenditore.
review_status: stato del controllo. I valori possono essere approved, outdated, pending, rejected. Un prodotto approvato può essere visibile nello Shop di Instagram dell'utente dell'app, ma uno stato approvato non indica la disponibilità del prodotto (ad esempio, il prodotto potrebbe essere esaurito). Solo i tag associati ai prodotti che hanno un review_status corrispondente ad approved possono essere visibili sui post pubblicati.
product_variants: ID prodotto (product_id) e nomi delle varianti (variant_name) delle varianti dei prodotti.

Esempio di richiesta

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

Esempio di risposta

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

Creazione di un contenitore taggato per immagini e video

Utilizza l'endpoint IG User Media per la creazione di un contenitore multimediale per un'immagine o un video. In alternativa, consulta Creazione di contenitori multimediali taggati per Reels o Caroselli.

POST /{ig-user-id}/media

Parametri

image_url: (obbligatorio solo per immagini) il percorso all'immagine. L'immagine deve trovarsi su un server pubblico.
user_tags: (solo immagini) un array di nomi utente e coordinate x/y pubblici per tutti gli utenti Instagram pubblici che desideri taggare nell'immagine. L'array deve essere in formato JSON e contenere una proprietà username, x e y. Ad esempio, i valori [{username:'natgeo',x:0.5,y:1.0}], x e y devono essere float che si originano dalla parte in alto a sinistra dell'immagine, con intervallo 0.0-1.0. Gli utenti taggati riceveranno una notifica quando viene pubblicato il contenuto multimediale.
video_url: (obbligatorio solo per video) il percorso al video. Il video deve trovarsi su un server pubblico.
thumb_offset: (solo video) la posizione, in millisecondi, del fotogramma per l'immagine di anteprima della copertina del video. Il valore predefinito è 0, che è il primo fotogramma del video.
product_tags: (obbligatorio) un array di oggetti che specifica i tag del prodotto da aggiungere all'immagine o al video. Puoi specificare fino a 20 tag per i post del feed delle foto e dei video e fino a 20 tag totali per post carosello (fino a 5 per immagine del carosello).
- I tag e gli ID dei prodotti devono essere unici.
- Sono supportati i tag per i prodotti esauriti.
- Ogni oggetto deve avere le seguenti informazioni:
  - product_id: (obbligatorio) ID prodotto.
  - x: (solo immagini) un float che indica la distanza in percentuale dal bordo sinistro dell'immagine multimediale pubblicata. Il valore deve essere compreso nell'intervallo 0.0-1.0.
- y: (solo immagini) un float che indica la distanza in percentuale dal bordo superiore dell'immagine multimediale pubblicata. Il valore deve essere compreso nell'intervallo 0.0-1.0.

Se l'operazione viene eseguita correttamente, l'API restituisce un ID contenitore che puoi utilizzare per la pubblicazione del contenitore.

Esempio di richiesta

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

Come riferimento, ecco la stringa del payload POST decodificata in 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...

Esempio di risposta

{
  "id": "17969578066508312"
}

Creazione di un contenitore taggato per Reels

Utilizza l'endpoint IG User Media per la creazione di un contenitore multimediale per Reels. In alternativa, consulta Creazione di un contenitore multimediale taggato o Caroselli.

POST /{ig-user-id}/media

Parametri

media_type: devi specificare il tipo di contenuto multimediale REELS.
video_url: il percorso al video per il reel. Il video deve trovarsi su un server pubblico. Il tuo video deve soddisfare le specifiche di Reels.
thumb_offset: la posizione, in millisecondi, del fotogramma per l'immagine di anteprima della copertina del video. Il valore predefinito è 0, che è il primo fotogramma del video.
caption: la didascalia per il reel.
product_tags: (obbligatorio) un array di oggetti che specifica i tag del prodotto da aggiungere al reel. Puoi specificare fino a 30 tag e i tag e gli ID del prodotto devono essere unici. Sono supportati i tag per i prodotti esauriti. Ogni oggetto deve avere le seguenti informazioni:
- product_id: (obbligatorio) ID prodotto.
location_id: l'ID di una Pagina associata a una posizione con cui desideri taggare il video. Per i dettagli, consulta i Parametri della stringa della query del contenuto multimediale dell'utente Instagram.
share_to_feed: true per richiedere che il video compaia nelle tab Feed e Reels. false per richiedere che il video compaia solo nella tab Reels.
access_token: il token d'accesso dell'utente.

Se l'operazione viene eseguita correttamente, l'API restituisce un ID contenitore che puoi utilizzare per la pubblicazione del contenitore.

Esempio di richiesta

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

Come riferimento, ecco la stringa del payload POST decodificata in HTML:

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

Esempio di risposta

{
  "id": "17969578066508312"
}

Pubblicazione di un contenitore multimediale taggato

Utilizza l'endpoint IG User Media Publish per la pubblicazione del contenitore multimediale taggato. Puoi pubblicare fino a 25 contenitori multimediali taggati per conto di un utente dell'app entro un periodo mobile di 24 ore. Se stai pubblicando un carosello, consulta Caroselli. Solo i prodotti che dispongono di review_status corrispondente ad approved saranno visibili sui post pubblicati. Se uno di questi prodotti è esaurito, i relativi tag saranno comunque visibili nel post pubblicato.

POST /{ig-user-id}/media_publish

Parametri

creation_id: (obbligatorio) l'ID del contenitore carosello.

Se l'operazione è stata eseguita correttamente, l'API restituirà un ID del contenuto multimediale di Instagram.

Esempio di richiesta

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

Esempio di risposta

{
  "id": "90010778325754"
}

Acquisizione dei tag sui contenuti multimediali

Usa l'endpoint IG Media Product Tags per l'acquisizione dei tag sui contenuti multimediali pubblicati.

GET /{ig-media-id}/product_tags

Restituisce un array di tag del prodotto e relativi metadati su un contenuto multimediale di IG. Nelle risposte possono essere inclusi i seguenti campi del tag del prodotto:

product_id: ID prodotto.
merchant_id: ID venditore.
name: nome del prodotto.
price_string: prezzo del prodotto.
image_url: URL dell'immagine del prodotto.
review_status: indica lo stato di idoneità del tag del prodotto. I valori possono essere:
approved: il prodotto è stato approvato.
rejected: il prodotto è stato rifiutato.
pending: ancora in fase di controllo.
outdated: il prodotto è stato approvato, ma è stato modificato e richiede una nuova approvazione.
"": nessuno stato del controllo.
no_review: nessuno stato del controllo.
is_checkout: se true, il prodotto può essere acquistato direttamente attraverso l'app Instagram. Se false, il prodotto può essere acquistato solo sul sito web del venditore.
stripped_price_string: stringa del prezzo abbreviata del prodotto (prezzo visualizzato negli spazi limitati, come $100 invece di 100 USD).
string_sale_price_string: prezzo promozionale del prodotto.
x: un float che indica la distanza in percentuale dal bordo sinistro dell'immagine multimediale. Il valore è compreso nell'intervallo 0.0-1.0.
y: un float che indica la distanza in percentuale dal bordo superiore dell'immagine multimediale. Il valore è compreso nell'intervallo 0.0-1.0.

Esempio di richiesta

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

Esempio di risposta

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

Tag sui contenuti multimediali esistenti

Usa l'endpoint IG Media Product Tags per la creazione o l'aggiornamento dei tag sul contenuto multimediale di IG esistente.

POST /{ig-media-id}/product_tags

Parametri

updated_tags: (obbligatorio) un array di oggetti che specifica con quali tag del prodotto taggare l'immagine o il video (massimo 5; tag e ID prodotto devono essere unici). Ogni oggetto deve avere le seguenti informazioni:
product_id: (obbligatorio) ID prodotto. Se il contenuto multimediale di IG non è stato taggato con questo ID, il tag verrà aggiunto a tale contenuto. Se il contenuto multimediale è già stato taggato con questo ID, le coordinate di visualizzazione del tag verranno aggiornate.
x: (solo immagini, obbligatorio) un float che indica la distanza in percentuale dal bordo sinistro dell'immagine multimediale pubblicata. Il valore deve essere compreso nell'intervallo 0.0-1.0.
y: (solo immagini, obbligatorio) un float che indica la distanza in percentuale dal bordo superiore dell'immagine multimediale pubblicata. Il valore deve essere compreso nell'intervallo 0.0-1.0.

L'aggiunta di tag al contenuto multimediale è additiva fino al raggiungimento del limite di 5 tag. Se il contenuto multimediale targetizzato è già stato taggato da un prodotto nella richiesta, i valori x e y del tag precedente verranno aggiornati con i nuovi valori (non verrà aggiunto un nuovo tag).

Restituisce true se in grado di aggiornare il prodotto, altrimenti restituisce false.

Esempio di richiesta

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

Come riferimento, ecco la stringa del payload POST decodificata in HTML:

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

Esempio di risposta

{
  "success": true
}

Eliminazione dei tag

Utilizza l'endpoint IG Media Product Tags per eliminare i tag su un contenuto multimediale di IG pubblicato, tra cui Reels.

DELETE /{ig-media-id}/product_tags

Parametri

deleted_tags: (obbligatorio) un array contenente le seguenti informazioni per ogni tag del prodotto da eliminare:
merchant_id: (obbligatorio) ID venditore.
product_id: (obbligatorio) ID prodotto.

Restituisce true se l'eliminazione del tag è stata eseguita correttamente, altrimenti restituisce false.

Esempio di richiesta

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

Come riferimento, ecco la stringa del payload POST decodificata in HTML:

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

Esempio di risposta

{
  "success": true
}

Invio di un ricorso per il rifiuto dei prodotti

Usa l'endpoint IG User Product Appeal se desideri offrire una modalità agli utenti della tua app per l'invio di un ricorso per i rifiuti dei prodotti (i tag dei prodotti rifiutati non saranno visibili sui post pubblicati). Sebbene non sia obbligatorio, ti consigliamo di offrire agli utenti dell'app un modo per inviare un ricorso contro i rifiuti oppure indicare loro di effettuare tale operazione utilizzando il Business Manager.

POST /{ig-user-id}/product_appeal

Parametri

appeal_reason: (obbligatorio) spiegazione del motivo per cui il prodotto dovrebbe essere approvato.
product_id: (obbligatorio) ID prodotto.

Restituisce true se in grado di ricevere la richiesta, altrimenti restituisce false. La risposta non indica l'esito del ricorso.

Esempio di richiesta

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

Esempio di risposta

{
  "success": true
}

Acquisizione dello stato del ricorso

Usa l'endpoint IG User Product Appeal per l'acquisizione dello stato di un ricorso per un determinato prodotto rifiutato:

GET /{ig-user-id}/product_appeal

Parametri

product_id: (obbligatorio) ID prodotto.

Restituisce i metadati dello stato del ricorso. Nelle risposte possono essere inclusi i seguenti campi del ricorso:

eligible_for_appeal: indica se è possibile inviare un ricorso per la decisione (sì se true, no se false).
product_id: ID prodotto.
review_status: stato del controllo. Il valore può essere:
approved: il prodotto è stato approvato.
rejected: il prodotto è stato rifiutato.
pending: ancora in fase di controllo.
outdated: il prodotto è stato approvato, ma è stato modificato e richiede una nuova approvazione.
"": nessuno stato del controllo.
no_review: nessuno stato del controllo.

Esempio di richiesta

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

Esempio di risposta

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

Caroselli

Puoi pubblicare caroselli (album) contenenti in totale al massimo 10 immagini, video taggati o un mix di immagini e video. Per eseguire questa azione, durante l'esecuzione del passaggio 1 di 3 della procedura di pubblicazione dei post carosello, crea semplicemente i contenitori multimediali taggati per ogni immagine o video taggati che desideri includere nel carosello degli album e continua con la procedura di pubblicazione del carosello come faresti normalmente.

Acquisizione di contenuti multimediali secondari in un carosello

Per l'acquisizione degli ID del contenuto multimediale di IG in un carosello di album, utilizza l'endpoint IG Media Children.