Plataforma do Instagram

Marcação de produto

É possível usar a Graph API do Instagram para criar e gerenciar etiquetas de produto da Loja do Instagram em uma mídia do Instagram para Empresas.

Observação: a partir de 10 de agosto de 2023, algumas empresas sem finalização de compra na Loja não poderão mais marcar produtos usando a API de Publicação de Conteúdo. Além de impactar a API e as interfaces nativas, isso removerá as etiquetas de produto de publicações existentes. Os clientes poderão continuar marcando produtos de Lojas com a finalização da compra no Facebook e no Instagram habilitada. Ainda é possível consultar o campo shopping_product_tag_eligibility para verificar se a conta do Instagram está qualificada para marcar os próprios produtos por meio da API de Publicação de Conteúdo.

O fluxo básico para a marcação de produtos é o seguinte:

  1. Verifique se a conta empresarial do Instagram está qualificada para a marcação de produtos.
  2. Se estiver, obtenha os catálogos de produtos dela.
  3. Pesquise em cada catálogo para encontrar produtos qualificados para marcação.
  4. Crie um contêiner de mídia marcada.
  5. Publique o contêiner.

Limitações

  • Todas as limitações para publicação de conteúdo se aplicam à marcação de produtos.
  • A marcação de produtos não é compatível com Stories nem Live.
  • A marcação de produtos não é compatível com contas de criador de conteúdo do Instagram.
  • Em um período de 24 horas, as contas podem fazer no máximo 25 publicações de mídia marcada. Os álbuns em carrossel contam como uma única publicação.

Requisitos

Pontos de extremidade

Verificar a qualificação do usuário

Solicite o campo shopping_product_tag_eligibility no ponto de extremidade de usuário do Instagram para verificar se uma Loja do Instagram foi configurada pela conta empresarial. As contas sem Loja do Instagram configurada não são elegíveis para etiquetas de produto.

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

Retornará true se a conta empresarial estiver associada a uma Loja aprovada do Instagram do Gerenciador de Negócios. Caso contrário, retornará false.

Exemplo de solicitação

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

Exemplo de resposta

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

Obter os catálogos

Use o ponto de extremidade de catálogos disponíveis do usuário do Instagram para obter o catálogo de produtos da conta empresarial do Instagram.

GET /{ig-user-id}/available_catalogs

Retorna uma matriz de catálogos e seus metadados. As respostas podem incluir os seguintes campos:

  • catalog_id: identificação do catálogo.
  • catalog_name: nome do catálogo.
  • shop_name: nome da loja.
  • product_count: total de produtos no catálogo.

Limitações

Não há compatibilidade com catálogos colaborativos, como catálogos de parceiros de compras ou de criadores de conteúdo afiliados.

Exemplo de solicitação

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

Exemplo de resposta

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

Obter os produtos qualificados

Use o ponto de extremidade de pesquisa por produto no catálogo do usuário para receber uma coleção de produtos no catálogo que podem ser usados para marcações de mídia. As variantes de produtos são compatíveis.

Se uma publicação for marcada com um produto não aprovado, a API não retornará um erro. Entretanto, a etiqueta ficará visível apenas quando a aprovação for concedida. Por isso, recomendamos permitir que os usuários do app enviem somente publicações com marcações de produtos com o review_status de approved. Por padrão, esse campo é retornado quando você obtém os produtos qualificados do usuário.

GET /{ig-user-id}/catalog_product_search

Parâmetros

  • catalog_id (obrigatório): identificação do catálogo.
  • q: uma string para buscar em cada nome de produto ou um número de SKU de produto (a coluna Identificação do conteúdo na interface de gerenciamento do catálogo). Se nenhuma string for especificada, todos os produtos qualificados serão retornados.

Retorna um objeto com a matriz de produtos qualificados para marcação e os respectivos metadados. Compatível com a paginação com base no cursor. As respostas podem incluir os seguintes campos:

  • image_url: a URL da imagem do produto.
  • is_checkout_flow: se true, o produto pode ser comprado diretamente no app do Instagram; se false, o produto deverá ser comprado no site ou no app do comerciante.
  • merchant_id: a identificação do comerciante.
  • product_id: a identificação do produto.
  • product_name: nome do produto.
  • retailer_id: a identificação do varejista.
  • review_status: status da análise. Os valores podem ser approved, outdated, pending ou rejected. Um produto aprovado pode aparecer na Loja do Instagram do usuário, mas o status de aprovação não indica a disponibilidade do produto (que pode estar fora de estoque, por exemplo). Apenas etiquetas associadas a produtos com review_status de approved aparecerão em publicações.
  • product_variants: identificações (product_id) e nomes (variant_name) das variantes do produto.

Exemplo de solicitação

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

Exemplo de resposta

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

Criar um contêiner marcado para imagens e vídeos

Use o ponto de extremidade mídia do usuário do Instagram para criar o contêiner de mídia com uma imagem ou um vídeo. Como alternativa, consulte Criar um contêiner de mídia marcada para o Reels ou Carrosséis.

POST /{ig-user-id}/media

Parâmetros

  • image_url (obrigatório apenas em imagens): o caminho até a imagem. A imagem precisa estar em um servidor público.
  • user_tags (apenas em imagens): uma matriz de nomes de usuário públicos e coordenadas x/y dos usuários públicos do Instagram que você queira marcar na imagem. A matriz precisa estar no formato JSON e conter as propriedades username, x e y. Por exemplo, [{username:'natgeo',x:0.5,y:1.0}], x e y precisam ser floats originados no canto superior esquerdo da imagem, com uma faixa de 0.0 a 1.0. Os usuários marcados receberão uma notificação quando a mídia for publicada.
  • video_url (obrigatório apenas em vídeos): o caminho até o vídeo. O vídeo precisa estar em um servidor público.
  • thumb_offset (apenas em vídeos): a localização em milissegundos do quadro para a imagem de miniatura da capa do vídeo. O valor padrão é 0, que é o primeiro quadro do vídeo.
  • product_tags (obrigatório): uma matriz de objetos que especifica as etiquetas de produto a serem adicionadas à imagem ou ao vídeo. É possível especificar até 20 marcações para publicações no feed de fotos e vídeos e até 20 marcações no total em carrosséis (até 5 por slide).
    • As etiquetas e identificações dos produtos devem ser únicas.
    • Há compatibilidade com etiquetas de produtos esgotados.
    • Cada objeto deve ter as seguintes informações:
      • product_id (obrigatório): a identificação do produto.
      • x (apenas em imagens): um float que indica a distância percentual da borda esquerda da imagem na mídia publicada. O valor precisa ser entre 0.0 e 1.0.
    • y (apenas em imagens): um float que indica a distância percentual da borda superior da imagem na mídia publicada. O valor precisa ser entre 0.0 e 1.0.

Se a operação for bem-sucedida, a API retornará uma identificação que pode ser usada para publicar o contêiner.

Exemplo de solicitação

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

Como referência, esta é a string da carga POST decodificada em 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...

Exemplo de resposta

{
  "id": "17969578066508312"
}

Criar um contêiner marcado para o Reels

Use o ponto de extremidade mídia do usuário do Instagram para criar um contêiner de mídia para o Reels. Como alternativa, consulte Criar um contêiner de mídia marcada ou Carrosséis.

POST /{ig-user-id}/media

Parâmetros

  • media_type: é preciso especificar o tipo de mídia REELS.
  • video_url: o caminho até o vídeo do Reels. O vídeo precisa estar em um servidor público. O vídeo deve atender às especificações do Reels.
  • thumb_offset: a localização em milissegundos do quadro para a imagem de miniatura da capa do vídeo. O valor padrão é 0, que é o primeiro quadro do vídeo.
  • caption: a legenda do reel.
  • product_tags (obrigatório): uma matriz de objetos que especifica as etiquetas de produto a serem adicionadas ao reel. É possível especificar 30 etiquetas. As etiquetas e identificações de produto precisam ser únicas. Há compatibilidade com etiquetas de produtos esgotados. Cada objeto deve ter as seguintes informações:
    • product_id (obrigatório): a identificação do produto.
  • location_id: a identificação de uma Página associada a uma localização a ser marcada no vídeo. Para saber mais, consulte os parâmetros da string de consulta de mídia do usuário do Instagram.
  • share_to_feed: true para solicitar que o vídeo apareça nas abas Feed e Reels. false: para solicitar que o vídeo apareça apenas na aba Reels.
  • access_token: o seu token de acesso do usuário.

Se a operação for bem-sucedida, a API retornará uma identificação que pode ser usada para publicar o contêiner.

Exemplo de solicitação

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

Como referência, esta é a string da carga POST decodificada em HTML:

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

Exemplo de resposta

{
  "id": "17969578066508312"
}

Publicar um contêiner de mídia marcada

Use o ponto de extremidade publicação de mídia do usuário do Instagram para publicar o contêiner de mídia marcada. Em um período de 24 horas, é possível publicar até 25 contêineres de mídia marcada em nome de um usuário. Se você estiver publicando um carrossel, consulte esta seção. Apenas produtos que têm o review_status definido como approved aparecerão nas publicações. Caso algum dos produtos esteja esgotado, as marcações ainda aparecerão na publicação.

POST /{ig-user-id}/media_publish

Parâmetros

  • creation_id (obrigatório): a identificação do contêiner de carrossel.

Se a operação for bem-sucedida, a API retornará a identificação da mídia do Instagram.

Exemplo de solicitação

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

Exemplo de resposta

{
  "id": "90010778325754"
}

Obter as marcações de uma mídia

Use o ponto de extremidade de marcações de produto de mídia do Instagram para obter marcações em publicações.

GET /{ig-media-id}/product_tags

Retorna uma matriz de etiquetas de produto na mídia do Instagram e os metadados correspondentes. As respostas podem incluir os seguintes campos:

  • product_id: a identificação do produto.
  • merchant_id: a identificação do comerciante.
  • name: nome do produto.
  • price_string: preço do produto.
  • image_url: a URL da imagem do produto.
  • review_status: status da qualificação da marcação de produto. Os valores podem ser os seguintes:
  • approved: produto aprovado.
  • rejected: produto rejeitado.
  • pending: ainda em análise.
  • outdated: produto aprovado, mas precisa de reaprovação devido a edições.
  • "": sem status de análise.
  • no_review: sem status de análise.
  • is_checkout: se true, o produto pode ser comprado diretamente no app do Instagram; se false, o produto deve ser comprado no site do comerciante.
  • stripped_price_string: string com a forma curta do preço do produto (exibido em espaços limitados, como $100 em vez de 100 USD).
  • string_sale_price_string: preço do produto em promoção.
  • x: um float que indica a distância percentual da borda esquerda da imagem na mídia. Valor entre 0.0 e 1.0.
  • y: um float que indica a distância percentual da borda superior da imagem na mídia. Valor entre 0.0 e 1.0.

Exemplo de solicitação

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

Exemplo de resposta

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

Marcar mídias existentes

Use o ponto de extremidade de marcações de produto de mídia do Instagram para criar ou atualizar etiquetas em mídias existentes.

POST /{ig-media-id}/product_tags

Parâmetros

  • updated_tags (obrigatório): uma matriz de objetos especificando as etiquetas de produto a serem incluídas na imagem ou no vídeo (no máximo 5 itens; etiquetas e identificações de produto devem ser únicas). Cada objeto deve ter as seguintes informações:
  • product_id (obrigatório): a identificação do produto. Se a mídia não tiver sido marcada com essa identificação, a marcação será adicionada. Se a mídia já tiver sido marcada com essa identificação, as coordenadas de exibição da marcação serão atualizadas.
  • x (apenas em imagens, obrigatório): um float que indica a distância percentual da borda esquerda da imagem na mídia publicada. O valor precisa ser entre 0.0 e 1.0.
  • y (apenas em imagens, obrigatório): um float que indica a distância percentual da borda superior da imagem na mídia publicada. O valor precisa ser entre 0.0 e 1.0.

As marcações de mídia são aditivas até que o máximo de 5 seja atingido. Se a mídia em questão já foi marcada com um produto na solicitação, os valores x e y da marcação antiga serão atualizados para os novos, e não será adicionada uma nova marcação.

Retorna true se a atualização do produto tiver sido concluída; se não, retorna false.

Exemplo de solicitação

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

Como referência, esta é a string da carga POST decodificada em HTML:

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

Exemplo de resposta

{
  "success": true
}

Excluir etiquetas

Use o ponto de extremidade de etiquetas de produto de mídia do Instagram para excluir etiquetas em uma mídia publicada, incluindo o Reels.

DELETE /{ig-media-id}/product_tags

Parâmetros

  • deleted_tags (obrigatório): uma matriz com as seguintes informações sobre cada etiqueta a ser excluída:
  • merchant_id (obrigatório): a identificação do comerciante.
  • product_id (obrigatório): a identificação do produto.

Retorna true se a marcação tiver sido excluída; se não, retorna false.

Exemplo de solicitação

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

Como referência, esta é a string da carga POST decodificada em HTML:

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

Exemplo de resposta

{
  "success": true
}

Fazer uma apelação da rejeição de um produto

Use o ponto de extremidade de apelação de produto do usuário do Instagram caso você queira permitir que os usuários do app façam uma apelação da rejeição de um produto (as marcações de produtos rejeitados não aparecerão nas publicações). Embora não seja obrigatório, recomendamos que você forneça uma maneira de os usuários fazerem uma apelação de uma rejeição. Também é possível disponibilizar instruções sobre como fazer isso usando o Gerenciador de Negócios.

POST /{ig-user-id}/product_appeal

Parâmetros

  • appeal_reason (obrigatório): explicação do porquê o produto deve ser aprovado.
  • product_id (obrigatório): a identificação do produto.

Retorna true se a solicitação tiver sido recebida; se não, retorna false. A resposta não indica o resultado da apelação.

Exemplo de solicitação

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

Exemplo de resposta

{
  "success": true
}

Obter o status da apelação

Use o ponto de extremidade de apelação de produto do usuário do Instagram para obter o status da apelação de um produto rejeitado:

GET /{ig-user-id}/product_appeal

Parâmetros

  • product_id (obrigatório): a identificação do produto.

Retorna os metadados do status da apelação. As respostas podem incluir os seguintes campos:

  • eligible_for_appeal: indica se pode ser feita uma apelação da decisão (sim se true, não se false).
  • product_id: a identificação do produto.
  • review_status: status da análise. Os valores podem ser os seguintes:
  • approved: produto aprovado.
  • rejected: produto rejeitado.
  • pending: ainda em análise.
  • outdated: produto aprovado, mas precisa de reaprovação devido a edições.
  • "": sem status de análise.
  • no_review: sem status de análise.

Exemplo de solicitação

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

Exemplo de resposta

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

Carrosséis

É possível publicar carrosséis (álbuns) com até 10 itens marcados no total, entre imagens, vídeos ou uma combinação das duas mídias. Para isso, ao realizar as etapas de 1 a 3 da publicação de carrossel, crie contêineres de marcação de mídia para cada imagem ou vídeo marcado que você quer que apareça no álbum. Depois, siga com o processo normalmente.

Colocar mídias subordinadas em um carrossel

Para obter as identificações de mídias em um carrossel de álbum, use o ponto de extremidade de mídia subordinada do Instagram.