--- title: "Emitir uma DC-e pela API" description: "Como emitir uma DC-e — síncrono ou assíncrono, as 3 modalidades de emissão, idempotência, e emissão em lote." source_url: https://nfe.io/docs/documentacao/declaracao-de-conteudo-eletronica/integracao-api/emitir-uma-declaracao-de-conteudo last_updated: 2026-09-04 --- # 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 | :::caution O modo síncrono também pode responder `202` Se 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`. ```json title="Emissão própria (SelfIssuer)" { "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": "contato@exemplo.com.br" }, "items": [ { "itemNumber": 1, "description": "EQUIPAMENTO DE EXEMPLO", "ncm": "84713012", "quantity": 2, "unitValue": 1500.00, "totalValue": 3000.00 } ], "transport": { "mode": "Carrier", "carrierCnpj": "12345678000195" } } ``` ```json title="Marketplace (identifica o cliente, informa o site)" { "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](../autenticacao.md)). **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`. :::caution O lote é sempre assíncrono, e não avalia `Idempotency-Key` Cada 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. ```json title="Resposta do lote — um item aceito, um recusado" [ { "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` | ## Veja também - [Conceitos da DC-e](../conceitos.md) - [Autenticação](../autenticacao.md) - [Como consultar uma DC-e](./como-consultar-uma-declaracao-de-conteudo.md)