Ingestão em lote

A ingestão REST separa recebimento, validação e aplicação. Nenhum lote altera o catálogo antes da confirmação final.

1. Inicie a ingestão

POST /v1/catalogos/ingestoes
Authorization: Bearer <chave>
Idempotency-Key: 3712438e-827e-4e8f-bcdd-2d10e4bc8e17
Content-Type: application/json

{
  "catalogo_id": "11111111-1111-4111-8111-111111111111",
  "operacao": "mesclar",
  "referencia_externa": "importacao-erp-001"
}

Use mesclar para adicionar ou atualizar os produtos recebidos e preservar os ausentes. Use substituicao_catalogo para substituir os vínculos somente no catálogo escolhido. O literal legado substituicao_integral é aceito como alias de substituição daquele catálogo e 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

Envie sequências a partir de 1 em PUT /v1/catalogos/ingestoes/{id}/lotes/{sequencia}. Cada lote aceita até 200 produtos e 256 KiB; os dois limites se aplicam juntos.

{
  "produtos": [
    {
      "codigo_cliente": "000123",
      "descricao_cliente": "Produto de exemplo",
      "ncm": "01012100",
      "desativado_por_ato": false,
      "atributos": [
        { "codigo": "ATT_123", "valores": ["valor informado"] }
      ]
    }
  ]
}

O teto estruturado é de 50 mil produtos e 64 MiB por ingestão, com até 10 mil sequências. Repetir o mesmo lote com a mesma chave idempotente não ocupa o limite novamente. Um lote diferente com a mesma chave gera conflito.

3. Feche e valide

POST /v1/catalogos/ingestoes/{id}/validar

{ "ultima_sequencia": 25 }

A resposta contém hash_previa, totais, guardas e os dados de revisão. Corrija recusas antes de aplicar. Sequência ausente, referência conflitante, NCM inválida e revisão de mapeamento aparecem como falha explícita; uma resposta vazia não deve ser interpretada como catálogo válido.

GET /v1/catalogos/ingestoes/{id} recupera o estado e a prévia. Use essa consulta também após um timeout.

4. Aplique a prévia

POST /v1/catalogos/ingestoes/{id}/aplicar

{ "hash_previa": "<sha256-em-hexadecimal-retornado-na-validacao>" }

O servidor responde 202 com estado: "aplicando" somente depois de persistir o aceite e envia Location para a consulta. 202 não significa catálogo atualizado. Continue até aplicada; falhou_aplicacao exige tratar codigo_falha. Uma edição concorrente do catálogo invalida a prévia sem publicar parte do lote.

CSV e XLSX

Arquivos CSV e XLSX passam pelo fluxo de envio de arquivo oferecido na 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 canônicos acima. Preserve códigos e NCMs como texto, inclusive zeros à esquerda. Não envie um arquivo como multipart/form-data para as rotas de ingestão JSON.