Emitir DC-e em lote
POST/v1/subscriptions/:subscriptionId/taxpayers/:taxpayerId/contentdeclarations/$batch
Recebe uma lista de declarações de um mesmo contribuinte e aceita cada uma independentemente.
Passadas as verificações do lote inteiro (contribuinte, cabeçalhos e
contratação), a resposta é 200, com um resultado por item, na mesma ordem do array de
entrada — cada resultado traz em index a posição do documento no array enviado.
Correlacione por index.
Todos os itens compartilham o mesmo batchId: o valor do cabeçalho X-Batch-Id
exatamente como você enviou, ou, sem o cabeçalho, um GUID com hífens gerado pelo
servidor.
⚠️ O lote é sempre assíncrono. Cada item aceito volta com status: 202; nenhum item
traz o documento pronto. Acompanhe cada id por GET {id}.
⚠️ Numeração e ordem de autorização não seguem a ordem de entrada. Série, número e
autorização acontecem de forma assíncrona e em paralelo. Se você precisa de numeração
sequencial na ordem do seu sistema, envie um POST por vez e espere o anterior.
Sem repetição segura
🔴 Esta operação recusa Idempotency-Key com 400, e nada é criado. A recusa é de
propósito: uma chave só não protege vários documentos, e aceitá-la sem avaliar faria um
reenvio depois de um timeout emitir o lote inteiro de novo — com você acreditando estar
protegido.
Reenviar o mesmo lote emite os documentos de novo. Se o seu processo reenvia (timeout,
retry automático), use a emissão unitária: uma chamada por documento, cada uma com a sua
Idempotency-Key e o mesmo X-Batch-Id. O agrupamento é o mesmo, e o reenvio devolve os
documentos já criados em vez de emitir outros.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 503
Lote processado, um resultado por item, na ordem do array enviado. Cada item traz o
código de status que a mesma requisição teria recebido sozinha: 202 quando aceita,
400 ou 422 quando recusada — inclusive o 422 da regra B10-10, conferida item a
item. Os detalhes da recusa não vêm no lote: para lê-los, envie o item recusado pela
emissão unitária.
O lote inteiro foi recusado antes de qualquer item, e nenhum documento foi criado. Os
dois motivos próprios desta operação estão nos cabeçalhos: a requisição trouxe
Idempotency-Key, ou trouxe X-Batch-Id fora do formato aceito. O item de errors
traz o nome do cabeçalho em name.
⚠️ A recusa de um item não cai aqui: ela volta dentro do 200, no status daquele
item.
Token ausente, expirado ou inválido. O token tem validade curta: ao receber 401, peça um
token novo e repita a chamada.
A emissão não é permitida. Leia o type:
type | Quando | O que fazer |
|---|---|---|
…/subscription-scope-undetermined | a assinatura da URL não é a do token | corrija o {subscriptionId} |
…/product-not-contracted | a assinatura não tem a DC-e contratada | contrate o produto para a assinatura |
Nada é criado e nenhuma numeração é consumida.
O contribuinte do caminho ({taxpayerId}) não existe ou não pertence à assinatura da URL.
A resposta é a mesma nos dois casos, e vem antes de qualquer coisa do pedido ser lida.
Uma verificação necessária para emitir não pôde ser feita agora. Nada foi criado; tente de
novo. Leia o type:
type | Quando |
|---|---|
…/company-ownership-unverified | não deu para verificar que o contribuinte pertence à assinatura |
…/company-environment-unverified | não deu para ler o ambiente cadastrado da empresa, e por isso o environment do pedido não pôde ser conferido |