Emitir uma DC-e pela API
POST /v2/companies/{companyId}/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.
Síncrono ou assíncrono
| Você envia | Você recebe |
|---|---|
Sem o cabeçalho Prefer | 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 dentro do tempo de espera do servidor, 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.
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",
"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",
"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 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 |
A chamada anterior falhou na validação (400/422) | A chave é liberada — pode reenviar a mesma chave com o corpo corrigido |
A chave é isolada por assinatura (veja Autenticação). A emissão em lote não avalia este cabeçalho.
Emissão em lote
POST /v2/companies/{companyId}/ContentDeclarations/$batch
Recebe um array de declarações e aceita cada uma independentemente. A resposta é sempre 200, com um resultado por item — a posição no array de entrada volta em index.
Idempotency-KeyCada item aceito volta com status: 202 — nenhum item traz o documento pronto na resposta; acompanhe cada id por GET {id}. Reenviar o mesmo lote emite os documentos de novo. Se seu processo tem retry automático, controle a repetição do seu lado, ou emita item por item com Idempotency-Key.
Todos os itens do lote compartilham o mesmo batchId — é o que correlaciona a emissão em lote depois.
[
{
"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"
}
]
Erros de validação
| Código | O que significa |
|---|---|
400 | Requisição recusada na validação de forma ou identidade. O corpo traz um único erro, e errorMessage traz só o caminho do campo (ex.: emitterType), não a explicação — use a tabela de modalidades acima para interpretar |
422 | Requisição bem formada, mas em violação de regra de negócio. O corpo lista todas as violações, cada uma com o identificador da regra entre colchetes e a explicação completa |
401 | Token ausente, expirado, com audiência errada, ou chave de API no lugar de JWT |
403 | Token válido mas sem o escopo/papel da operação, ou assinatura não determinada — veja X-Subscription-Id |
409 | Já existe uma emissão em andamento com a mesma Idempotency-Key |