O primeiro passo é a sincronização, que ocorre em duas frentes:
Nota para lojas VTEX: Para lojas na plataforma VTEX, a sincronização do catálogo ocorre de forma transparente, não sendo necessária nenhuma integração adicional para este fim.
Envio das informações cadastrais dos produtos. Requer autenticação.
POST https://api-retail-media.newtail.com.br/product/bulk/products| Campo | Descrição | Tipo | Obrigatório? |
|---|---|---|---|
product_sku |
ID/SKU único do produto. | String | Sim |
parent_sku |
SKU do produto pai (para variações). | String | Não |
name |
Nome do produto. | String | Sim |
url |
URL canônica da página do produto. | String | Sim |
image_url |
URL da imagem principal do produto. | String | Não |
categories |
Lista de categorias. | Array[String] | Sim |
brand |
Marca do produto. | String | Não |
gtins |
Códigos de barras (EAN). Obrigatório para campanhas na VTEX Ads Network. | Array[String] | Não/Sim |
tags |
“Etiquetas” para contextualizar buscas. Máx. 10 por SKU, 64 chars por tag. Apenas para campanhas de product. |
Array[String] | Não |
sellers |
Lista de sellers que vendem o produto (em um marketplace). | Array[String] | Não |
metadata |
Objeto para informações adicionais (chave-valor). | Object | Não |
Importante: O campo
categoriesé crucial para a segmentação de campanhas e a organização de produtos. Ele deve ser estruturado de forma hierárquica, representando o caminho completo desde a categoria raiz até a categoria específica do produto.
O campo categories deve ser um array de strings, onde cada string é um nível da árvore de categorias. A hierarquia é construída enviando todas as categorias pai até a mais específica.
Exemplo Correto:
Para um produto na categoria de perfumes “Para Mulher”, o array categories deveria ser:
"categories": [
"Beleza",
"Fragrâncias",
"Perfume",
"Para Mulher"
]
Essa estrutura permite que a plataforma entenda o contexto do produto em todos os níveis, do mais amplo (“Beleza”) ao mais específico (“Para Mulher”).
Exemplo de Requisição:
curl --location 'https://api-retail-media.newtail.com.br/product/bulk/products' \
--header 'x-app-id: XXXX' \
--header 'x-api-key: YYYY' \
--header 'Content-Type: application/json' \
--data '[
{
"product_sku": "allan",
"name": "allan",
"url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616",
"image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629",
"categories": [
"Beleza",
"Fragrâncias",
"Perfume",
"Para Mulher"
],
"brand": "SALVADOR DALÍ",
"profit_margin": null,
"gtins": [
"3331438450103"
],
"sellers": [],
"skus": []
},
{
"product_sku": "allan2",
"name": "allan2",
"url": "https://www.panvel.com/panvel/eau-de-dali-salvador-dali-eau-de-toilette-perfume-feminino-30ml/p-10007616",
"image_url": "https://panvelprd.vteximg.com.br/arquivos/ids/177629",
"categories": [
"Beleza",
"Fragrâncias",
"Perfume",
"Para Mulher"
],
"brand": "SALVADOR DALÍ",
"profit_margin": null,
"gtins": [
"3331438450103"
],
"sellers": [],
"skus": [],
"tags": ["Abart", "Mega Maio"]
}
]'
Exemplo de Resposta com Sucesso:
Status: 202 Accepted
Content-Type: application/json
{
"messages": [
"products will be processed soon"
]
}
Envio das informações de preço e estoque dos produtos. Requer autenticação.
POST https://api-retail-media.newtail.com.br/product/bulk/inventories| Campo | Descrição | Tipo | Obrigatório? |
|---|---|---|---|
product_sku |
ID/SKU único do produto. | String | Sim |
price |
Preço atual do produto. | Float | Sim |
promotional_price |
Preço “de” (tabelado/original). | Float | Sim |
is_available |
Produto disponível (em estoque). | Boolean | Sim |
store_id |
Identificação da loja. Caso não seja enviado o store_id, será interpretado que essa informação de inventário será utilizado para todas as lojas. | String | Não |
metadata |
Objeto para informações adicionais (chave-valor). | Object | Não |
Exemplo de Requisição:
curl --location 'https://api-retail-media.newtail.com.br/product/bulk/inventories' \
--header 'x-app-id: XXXX' \
--header 'x-api-key: YYYY' \
--header 'Content-Type: application/json' \
--data '[
{
"product_sku": "120210",
"store_id": "1",
"price": 18.20,
"promotional_price": 16.32,
"is_available": true
},
{
"product_sku": "120212",
"price": 18.20,
"promotional_price": 0, // Remove o preço promocional
"is_available": true
}
]'
Exemplo de Resposta com Sucesso:
Status: 202 Accepted
Content-Type: application/json
{
"messages": [
"inventory will be processed soon"
]
}