Emitir uma DC-e pela API
POST /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations
O serviço faz tudo em uma chamada: numeração, assinatura com o certificado da empresa, validação contra o schema e transmissão à SEFAZ.
{subscriptionId} é a assinatura sobre a qual você opera e {taxpayerId} é o contribuinte emitente — veja Autenticação para o que cada um tem de ser. O host é sempre https://api.nfe.io, em produção e em homologação: quem decide o ambiente é o cadastro da empresa (veja abaixo).
Antes de emitir, você pode conferir se o serviço de autorização da SEFAZ-PR está no ar — veja Status da SEFAZ.
Síncrono ou assíncrono
| Você envia | Você recebe |
|---|---|
Sem o cabeçalho Prefer | A requisição espera até 30 segundos pelo desfecho e responde 200 com o documento em estado terminal (autorizado, rejeitado ou recusado) |
Prefer: respond-async | 202 com o id e o cabeçalho Location, para consultar depois |
202Se a autorização não chegar a um estado terminal em 30 segundos, a resposta degrada para 202 com Location — mesmo sem você ter pedido o modo assíncrono. Trate 202 como resultado possível sempre, não só quando você pediu.
serie e number são atribuídos pelo servidor — não os envie. Eles aparecem na resposta assim que a numeração é definida.
O ambiente vai no corpo, e tem de bater com o cadastro da empresa
environment é obrigatório: 1 produção, 2 homologação. Ausente, 0 ou fora desses dois valores, a resposta é 400. O valor tem de coincidir com o ambiente cadastrado da empresa na plataforma — divergente, a resposta é 422, com name: environment e a regra B10-10 nomeando os dois valores. Empresa sem ambiente cadastrado é homologação, e em homologação o documento não tem validade fiscal.
O host não muda com o ambiente: produção e homologação respondem no mesmo https://api.nfe.io. Para homologar, deixe a empresa em homologação e envie environment: 2.
Se o CNPJ já emitiu DC-e pelo aplicativo do fisco ou por outro sistema, grave no painel, no campo Número da DC-e da configuração inicial da DC-e, o último número autorizado — a próxima DC-e sai com o número seguinte. Sem isso, a numeração começa em 1, e a SEFAZ recusa o número repetido com cStat 451. Veja Credenciamento.
As 3 modalidades de emissão
O campo emitterType define quem está emitindo e como o emitente se identifica:
| Modalidade | Identificação em issuer | emitterParty |
|---|---|---|
SelfIssuer (emissão própria) | Somente cnpj, com dígito verificador válido. Enviar cpf é recusado | Não exigido |
Marketplace | Exatamente um entre cnpj, cpf ou idOthers — identificação do cliente do marketplace | site obrigatório |
Carrier (transportadora) | Exatamente um entre cnpj, cpf ou idOthers | Não exigido |
O destinatário, em qualquer modalidade, sempre informa exatamente um entre cnpj, cpf ou idOthers.
{
"emitterType": "SelfIssuer",
"emissionType": "Normal",
"environment": 2,
"issuer": {
"cnpj": "11222333000181",
"name": "EMPRESA EXEMPLO LTDA - MATRIZ",
"address": {
"street": "Rua Exemplo",
"number": "1000",
"neighborhood": "Centro",
"cityCode": 3550308,
"cityName": "São Paulo",
"state": "SP",
"postalCode": "01001000"
}
},
"recipient": {
"cnpj": "99887766000105",
"name": "EMPRESA EXEMPLO LTDA - FILIAL",
"address": {
"street": "Avenida Exemplo",
"number": "250",
"neighborhood": "Jardim Exemplo",
"cityCode": 3304557,
"cityName": "Rio de Janeiro",
"state": "RJ",
"postalCode": "20010000"
},
"email": "[email protected]"
},
"items": [
{
"itemNumber": 1,
"description": "EQUIPAMENTO DE EXEMPLO",
"ncm": "84713012",
"quantity": 2,
"unitValue": 1500.00,
"totalValue": 3000.00
}
],
"transport": {
"mode": "Carrier",
"carrierCnpj": "12345678000195"
}
}
{
"emitterType": "Marketplace",
"emissionType": "Normal",
"environment": 2,
"issuer": {
"cpf": "11144477735",
"name": "VENDEDOR EXEMPLO",
"address": {
"street": "Rua do Vendedor",
"number": "45",
"neighborhood": "Centro",
"cityCode": 3550308,
"cityName": "São Paulo",
"state": "SP",
"postalCode": "01001000"
}
},
"recipient": {
"cnpj": "99887766000105",
"name": "COMPRADOR EXEMPLO LTDA",
"address": {
"street": "Avenida Exemplo",
"number": "250",
"neighborhood": "Jardim Exemplo",
"cityCode": 3304557,
"cityName": "Rio de Janeiro",
"state": "RJ",
"postalCode": "20010000"
}
},
"items": [
{
"itemNumber": 1,
"description": "ACESSORIO DE EXEMPLO",
"quantity": 1,
"unitValue": 89.90,
"totalValue": 89.90
}
],
"transport": { "mode": "Mail" },
"emitterParty": { "site": "https://marketplace.exemplo.com.br" },
"additionalInfo": { "marketplaceInfo": "Pedido 123456" }
}
Repetição segura (Idempotency-Key)
Envie o cabeçalho Idempotency-Key com uma chave escolhida por você (por exemplo, o identificador do pedido no seu sistema) para que um reenvio — timeout de rede, retry automático — não emita um segundo documento nem consuma numeração fiscal de novo.
| Situação | Resposta |
|---|---|
| Primeira chamada com a chave | Segue normalmente (200/202) |
| Repetição com o mesmo corpo, depois de concluída | O mesmo código de status da primeira resposta, com Location apontando para o documento já criado, e sem corpo — consulte o Location para ler o documento |
| Repetição enquanto a primeira ainda está em andamento | 409 — nunca se enfileira uma segunda emissão |
| Mesma chave com corpo ou empresa diferente | 422, com type terminado em idempotency-key-reused, e nada é criado — use uma chave nova para um documento novo, ou repita o corpo original para receber o resultado dele |
A chamada anterior foi recusada sem criar documento (400, 403, 404, 422, 503) | A chave é liberada — pode reenviar a mesma chave com o corpo corrigido |
A chave vale por 24 horas e é isolada por assinatura (veja Autenticação): passado esse prazo, a mesma chave é tratada como nova. A emissão em lote ($batch) recusa este cabeçalho com 400 — para ter a garantia em vários documentos, veja Agrupar emissões em lote.
Agrupar emissões em lote com repetição segura
Para emitir vários documentos juntos e poder reenviá-los depois de um timeout, chame a emissão unitária uma vez por documento: cada chamada com a sua Idempotency-Key, e o mesmo cabeçalho X-Batch-Id em todas. É o mesmo caminho que o painel da NFE.io usa para emitir em lote.
POST /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations
Authorization: Bearer {token}
Content-Type: application/json
Prefer: respond-async
Idempotency-Key: pedido-0042-item-1
X-Batch-Id: pedido-2026-10-06-0042
| Você quer | Como |
|---|---|
| Reenviar o lote inteiro sem duplicar | Repita cada chamada com a mesma Idempotency-Key de antes. O que já foi criado volta como repetição; só o que faltou é emitido |
| Saber quais documentos são do lote | O campo batchId vem na resposta 202, no detalhe e na listagem — filtre com $filter=batchId eq 'pedido-2026-10-06-0042' (veja Como consultar) |
| Emitir sem lote | Não envie o cabeçalho. Ele é opcional, e o documento fica sem batchId |
O valor do X-Batch-Id é seu: a API não o interpreta, só guarda e devolve em batchId exatamente como foi enviado, sem normalizar.
- Aceita de 1 a 64 caracteres entre letras, dígitos, ponto, sublinhado, dois-pontos e hífen — cabe um GUID, uma data ou o número do seu pedido.
- Valor fora do formato é recusado com
400, sem criar documento. Ele não é truncado nem corrigido. - O lote não interfere na chave: dois documentos do mesmo lote com chaves diferentes são os dois criados.
- No filtro da listagem, um GUID casa com ou sem hífens.
Emissão em lote
POST /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/$batch
Recebe um array de declarações e aceita cada uma independentemente. A resposta é 200, com um resultado por item na mesma ordem do pedido, e cada resultado traz em index a posição do documento no array de entrada — correlacione por index.
Cada item tem o próprio status: 202 quando aceito, ou o código que o POST unitário responderia para aquele documento (400 ou 422, inclusive a B10-10). O que vale para a empresa ou para a assinatura inteira — 404, 403, 503 e o 400 de cabeçalho — recusa o lote todo, sem resultado por item.
Numeração (série e número) e autorização acontecem de forma assíncrona e em paralelo, então não seguem a ordem do pedido. Se você precisa de números sequenciais na ordem dos seus documentos, envie um POST unitário por vez e espere o anterior.
Cada item aceito volta com status: 202 — nenhum item traz o documento pronto na resposta; acompanhe cada id por GET {id}.
Esta rota recusa Idempotency-Key com 400, e nada é criado. A API recusa em vez de ignorar de propósito: uma chave só não protege vários documentos, e quem reenviasse achando estar protegido emitiria o lote inteiro de novo. Sem a chave, é isso o que acontece: reenviar o mesmo lote emite os documentos de novo. Se o seu processo reenvia, use o agrupamento com repetição segura.
Todos os itens compartilham o mesmo batchId: o valor do cabeçalho X-Batch-Id, exatamente como você o enviou, ou — sem o cabeçalho — um GUID com hífens gerado pelo servidor.
[
{
"index": 0,
"status": 202,
"id": "0f6b1f5c-9a5e-4a0e-9c1b-2f4e6d8a1b23",
"batchId": "7c9a2f10-4b3d-4e91-8a5f-1d2c3b4a5e6f"
},
{
"index": 1,
"status": 422,
"batchId": "7c9a2f10-4b3d-4e91-8a5f-1d2c3b4a5e6f"
}
]
Quem não integra pela API emite em lote subindo uma planilha no painel — o formato do arquivo está em Template de planilha para emissão de DC-e em lote. Esse caminho não usa a rota $batch: cada linha vira uma emissão própria. Antes de reenviar uma planilha, veja nessa página como evitar emitir de novo o que já foi autorizado.
Erros
400 ou 422: forma ou regra
A divisão entre os dois é fixa:
400é forma — o pedido não se lê como deveria: JSON ilegível, tipo errado, valor fora do conjunto aceito, cabeçalho fora do formato, campo obrigatório ausente (emitterType,environment, ao menos um item emitems,issuer.cnpjna emissão própria,emitterParty.siteno marketplace) ou identificação incompatível com a modalidade. Não trazrule.422é regra — o pedido se lê, e uma regra recusa o conteúdo: dígito verificador de CNPJ ou CPF,environmentdivergente do cadastro da empresa (B10-10), regras do leiaute da DC-e (por exemplo, mais de 999 itens,L-ITEMS). Toda recusa que trazruleé422.
Tabela de códigos
| Código | O que significa |
|---|---|
400 | Recusa de forma (acima), X-Batch-Id fora do formato, ou Idempotency-Key enviada ao $batch. errors[] traz name (o campo ou o cabeçalho) e reason (a explicação) |
401 | Token ausente, inválido ou expirado — peça um novo token (veja Autenticação) |
403 | type terminado em issuance-not-released: a emissão de DC-e ainda não foi liberada para esta empresa neste ambiente. A liberação é feita por empresa — fale com o suporte da NFE.io para liberar |
403 | type terminado em product-not-contracted: a assinatura do token não tem a DC-e contratada |
403 | type terminado em subscription-scope-undetermined: a assinatura da URL não é a do token nem uma que o usuário acessa |
404 | type terminado em company-not-in-subscription: a empresa da URL ({taxpayerId}) não existe ou não pertence à assinatura — a resposta é a mesma nos dois casos |
409 | Já existe uma emissão em andamento com a mesma Idempotency-Key |
422 | Recusa de regra (acima). errors[] lista todas as violações, cada uma com name, reason e, quando a recusa vem de uma regra do leiaute, rule. Também idempotency-key-reused, quando a mesma chave chega com outro corpo ou outra empresa |
503 | Não deu para verificar agora a titularidade da empresa (company-ownership-unverified) ou o ambiente do cadastro dela (company-environment-unverified). Nada foi criado — tente de novo |
Todo erro vem em application/problem+json (RFC 9457): type é o identificador estável para o seu código, no espaço https://docs.nfe.io/errors/dce/…; title, detail e errors[].reason são texto para pessoas, em inglês. A exceção é o motivo da SEFAZ (xMotivo), repassado em português como veio — por exemplo em rejectionReason, na consulta.
{
"type": "https://docs.nfe.io/errors/dce/validation-failed",
"status": 400,
"errors": [
{ "name": "emitterType", "reason": "emitterType is required." }
]
}
{
"status": 422,
"errors": [
{ "name": "recipient.address.cityCode", "reason": "The recipient's city code does not exist in the IBGE table.", "rule": "E10-10" },
{ "name": "items", "reason": "The number of items must be between 1 and 999.", "rule": "L-ITEMS" }
]
}