Skip to main content
Esta receita cobre o caso real: você tem 100.000 produtos com 300.000 imagens no seu sistema e precisa carregar tudo na Voop pela primeira vez.

Estimativas

  • Metadados: ~5-10 minutos para 100k items (depende de DB load)
  • Imagens: ~30-60 minutos para 300k imagens (limitado por per-domain semaphore)
  • Total: ~1 hora; produtos ficam consultáveis em ~10min, imagens chegam após

Pré-requisitos

  • API key com escopos catalog:write, bulk_import:manage
  • Suas imagens hospedadas em URL pública (CDN, S3 público, etc.)
  • Espaço em disco para gerar o JSONL

Passo 1: gere o JSONL

Idealmente, declare suas categorias e brands antecipadamente no dashboard. Caso contrário, a Voop cria automaticamente conforme aparecem.
Para 100k items, o arquivo gera em ~30s e fica entre 30-80 MB (bem abaixo do limite de 100 MB). Se passar, divida em 2-3 jobs.

Passo 2: inicie o job

Passo 3: faça upload do JSONL

Passo 4: dispare o processamento

Passo 5: poll de status

Ou configure um webhook import.completed antes de chamar start.

Passo 6: revise os erros

Se status === "completed_with_errors":
Para cada erro, você verá:
  • lineNumber — qual linha do seu JSONL
  • externalId — qual produto (se extraído antes do erro)
  • errorTypevalidation (campo inválido), conflict (SKU duplicado), database
  • errorMessage — descrição
  • rawLine — primeiras 4kb do JSON original (para debug)
Corrija seu gerador, gere um JSONL só com os items que falharam, e re-importe — itens que já entraram retornarão unchanged (zero impacto).

Passo 7: monitore a ingest de imagens

Os items ficam consultáveis na API e na IA imediatamente após o import dos metadados — antes mesmo das imagens chegarem. Para monitorar imagens, configure um webhook subscrito a media.ingested e media.ingestion_failed. Em ~30-60 minutos a fila normalmente esgota. Se uma imagem falha (CDN cliente offline, URL quebrada), o evento media.ingestion_failed te avisa com o motivo.

Passo 8 (opcional): re-sync periódico

Configure um cron diário para re-importar o catálogo inteiro. Graças ao contentHash, apenas itens que mudaram serão tocados — o resto retorna unchanged em milissegundos.
Não precisa fazer diff manual — o backend faz por você.