Ingestão em lote

A ingestão separa recebimento, validação e aplicação. Nenhum lote altera o catálogo antes de aplicar. Até lá, você pode enviar, repetir e validar quantas vezes precisar.

recebendo_lotespróxima etapa por validar
pronta_para_aplicarpróxima etapa por aplicarou desvia para precisa_revisaoRecusas na prévia. Corrija no ERP e inicie outra ingestão.
aplicandopróxima etapa por trabalho durável
aplicadaou desvia para falhou_aplicacaoLeia codigo_falha. Nada foi publicado pela metade.

Estados de uma ingestão pela API

O tutorial Do ERP à primeira análise percorre este fluxo com o script completo. Esta página é a referência de cada etapa.

1. Inicie a ingestão

POST/v1/catalogos/ingestoescatalogo:escreverReferência

{
  "catalogo_id": "7c7b354f-07b6-4461-9240-263418c81cdb",
  "operacao": "mesclar",
  "referencia_externa": "erp-2026-10-13"
}

{ "ingestao_id": "5306d957-04d7-44dd-9c63-e4d04d2e19fe", "estado": "recebendo_lotes", "repetida": false, "catalogo_id": "7c7b354f-07b6-4461-9240-263418c81cdb", "versao_catalogo": 1 }

Operação	Efeito ao aplicar
`mesclar`	Adiciona ou atualiza os produtos recebidos e preserva os ausentes.
`substituicao_catalogo`	Substitui os vínculos somente no catálogo escolhido.
`substituicao_integral`	Alias legado de `substituicao_catalogo`. Não autoriza apagar a empresa.

Se catalogo_id for omitido, a operação só prossegue quando existe exatamente um catálogo ativo. Com mais de um, o servidor devolve DESTINO_CATALOGO_OBRIGATORIO.

2. Envie os lotes

PUT/v1/catalogos/ingestoes/{id}/lotes/{sequencia}catalogo:escreverReferência

Envie sequências a partir de 1. Cada lote aceita até 200 produtos e 256 KiB; os dois limites valem juntos.

{
  "produtos": [
    {
      "codigo_cliente": "000123",
      "descricao_cliente": "Luva cirúrgica estéril de látex",
      "ncm": "40151900",
      "desativado_por_ato": false,
      "atributos": [
        { "codigo": "ATT_123", "valores": ["valor informado"] }
      ]
    }
  ]
}

Resposta	Quando
`201` com `"repetido": false`	Lote novo recebido.
`200` com `"repetido": true`	Mesmo lote, mesma `Idempotency-Key`: recibo original, sem ocupar o limite de novo.
`409 LOTE_CONFLITANTE`	Mesma sequência ou mesma chave com outro conteúdo.

O teto é de 50 mil produtos e 64 MiB por ingestão, com até 10 mil sequências. Preserve códigos e NCMs como texto, inclusive zeros à esquerda.

3. Feche e valide

POST/v1/catalogos/ingestoes/{id}/validarcatalogo:escreverReferência

{ "ultima_sequencia": 1 }

{
  "ingestao_id": "5306d957-04d7-44dd-9c63-e4d04d2e19fe",
  "estado": "pronta_para_aplicar",
  "hash_previa": "4bee6b75d2d85b7a1ed8f4dd9657f131c7d9b1dca79c0eac2c3c912091d131ae",
  "totais": { "lotes": 1, "produtos": 3, "incompletos": 0, "atributos": 0 },
  "guardas": []
}

Sequência ausente, referência conflitante, NCM inválida e revisão de mapeamento aparecem como falha explícita. Com recusas, o estado é precisa_revisao e guardas lista os motivos, como ncm_inexistente ou linha_sem_ncm. Uma resposta vazia nunca deve ser lida como catálogo válido.

GET/v1/catalogos/ingestoes/{id}catalogo:lerReferência

A consulta recupera o estado, os totais e cada item com seus erros. Use-a também depois de um timeout, antes de decidir repetir qualquer passo.

{ "id_temporario": "1:1", "codigo_cliente": "000123", "descricao_cliente": "Luva cirúrgica estéril de látex", "ncm": "40151100", "posicao": 1, "erros": ["NCM não existe na nomenclatura vigente."] }

4. Aplique a prévia

POST/v1/catalogos/ingestoes/{id}/aplicarcatalogo:aplicarReferência

{ "hash_previa": "4bee6b75d2d85b7a1ed8f4dd9657f131c7d9b1dca79c0eac2c3c912091d131ae" }

{ "ingestao_id": "5306d957-04d7-44dd-9c63-e4d04d2e19fe", "estado": "aplicando", "repetida": false }

O servidor responde 202 somente depois de persistir o aceite e envia Location para a consulta. 202 não significa catálogo atualizado. Acompanhe progresso_aplicacao até aplicada:

{
  "estado": "aplicada",
  "progresso_aplicacao": { "fase": "concluida", "itens_preparados": 3, "itens_previstos": 3 },
  "codigo_falha": null,
  "aplicada_em": "2026-10-13T16:48:04.093Z"
}

falhou_aplicacao exige tratar codigo_falha. Uma edição concorrente do catálogo invalida a prévia sem publicar parte do lote. Aplicar em precisa_revisao devolve 409 REVISAO_HUMANA_NECESSARIA.

Com um webhook configurado, a conclusão gera catalogo.aplicado e uma validação com recusas gera catalogo.revisao_necessaria. Veja Webhooks.

CSV e XLSX

Arquivos CSV e XLSX passam pelo envio de arquivo da interface do produto; não existe endpoint público de upload de arquivo no contrato REST atual. O arquivo tem teto de 10 MiB e o extrator atual limita o conteúdo a 200 mil linhas. A prévia precisa ser conferida e confirmada antes da aplicação.

Para automação por API, converta os dados no seu ambiente para os lotes JSON acima. Não envie um arquivo como multipart/form-data para as rotas de ingestão.