Feeds de dados

Um feed de dados é um arquivo (XML, CSV ou JSON) com os produtos da loja, no formato que um canal externo espera: o Google Merchant Center para o Google Shopping, o catálogo do Meta (Facebook e Instagram), o Mercado Livre, ou um formato livre para um ERP e para análises. Você cadastra o feed uma vez (tipo, formato, filtros), a plataforma gera o arquivo e entrega um link público que o canal consulta de tempos em tempos.

Como funciona

Ciclo de uso

1. Escolher o tipo e os campos

   GET /data-feeds/fields/{feed_type} lista os campos que o tipo suporta. Para google_shopping, facebook e mercado_livre, a lista é a exigida pelo canal.

2. Criar o feed

   POST /data-feeds com nome, tipo, formato, filtros e, se quiser, o agendamento. A resposta já traz o public_url.

3. Gerar

   POST /data-feeds/{id}/generate monta o arquivo, grava no servidor e devolve o conteúdo.

4. Entregar o link ao canal

   Cadastre o public_url no Google Merchant Center, no Meta ou onde for. Daí em diante a plataforma atualiza o arquivo no ritmo do agendamento.

Tipos de feed

Os três primeiros tipos têm o formato imposto pelo canal: o file_format é gravado, mas o conteúdo gerado segue a tabela. Só o custom obedece ao file_format.

Status

O feed é A (ativo) ou D (desativado). Ao gravar você pode mandar a letra ou active e disabled; a resposta devolve sempre a letra. Apenas feeds ativos com schedule_interval maior que zero são regerados pelo agendador.

Conceitos-chave

Filtros

O objeto filters escolhe quais produtos entram. Todos os campos são opcionais:

Produtos excluídos nunca entram.

Mapeamento de campos

field_mapping guarda os campos escolhidos. Nos feeds do Google, do Meta e do Mercado Livre, desmarcar um campo opcional o tira do arquivo. Um feed sem mapeamento ({}) gera todos os campos opcionais. No feed do Google, a entrada g:google_product_category com default_value define a categoria do Google para o feed inteiro.

O link público

https://<domínio da loja>/api/v1/feeds/<token>.<xml|csv|json>. O link serve o último arquivo gerado, não regera na hora, e fica em cache por uma hora. Gerar um novo token invalida o link antigo.

Feeds de seller

Cada feed pode pertencer à loja (marketplace) ou a um seller (vendor_id). A lista aceita vendor_id e marketplace_only=true para separar.

Endpoints

Erros comuns

• Entregar o link ao Google antes de gerar: o link responde 404 ("Feed has not been generated yet") até a primeira geração.
• Esperar que file_format: "json" mude um feed google_shopping: o formato do Google é sempre XML.
• Filtrar preço em reais: min_price e max_price são em centavos.
• Colar o link público em um lugar visível: ele não tem senha. Se vazou, gere um novo token.
• Esperar que o link atualize sozinho com a loja: ele serve o último arquivo gerado. Use schedule_interval ou chame generate.
• Confundir 403 module_disabled com falta de privilégio: é o módulo data-feeds que está desligado na loja.
• Enviar schedule_interval pequeno demais: o agendador acorda a cada 15 minutos, então valores menores que isso não adiantam.

Próximos passos