Emitir uma DC-e
POST/v1/subscriptions/:subscriptionId/taxpayers/:taxpayerId/contentdeclarations
Cria e transmite uma DC-e em uma única chamada.
O serviço faz tudo: numeração, assinatura com o certificado da empresa, validação contra o XSD 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 |
⚠️ 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. Trate 202 como resultado possível sempre, e não só quando você pediu.
Numeração e série
serie e number são atribuídos pelo servidor — não os envie. Eles aparecem na resposta
assim que a numeração é definida.
Repetição segura
Envie Idempotency-Key para que um reenvio (timeout de rede, retry automático) não
emita um segundo documento nem consuma numeração fiscal de novo. Veja a descrição do
cabeçalho.
Request
Responses
- 200
- 202
- 400
- 401
- 403
- 409
- 422
Emissão concluída no modo síncrono. O documento está em estado terminal — leia status
para saber qual.
Emissão aceita e em processamento. Consulte o Location (ou GET {id}) até o status
ficar terminal.
Response Headers
Caminho relativo do documento criado.
Requisição recusada na validação de forma ou de identidade — campo obrigatório ausente,
identificação incompatível com a modalidade, environment ausente ou divergente do cadastro
da empresa (B10-10). O corpo é Problem Details com errors[]: cada erro traz name (o
caminho do campo, em camelCase) e reason (a explicação, em inglês); rule aparece quando a
recusa vem de uma regra identificada.
Token ausente, expirado, com audiência diferente de dfetech.contentdeclaration.api, ou
chave de API no lugar de um JWT.
O token autentica, mas não autoriza: falta o escopo ou o papel da operação, ou a assinatura
da URL não é do token (nem acessível ao usuário). Leia o type para distinguir — o de
assinatura é …/subscription-scope-undetermined.
Já existe uma emissão em andamento com a mesma Idempotency-Key. Nenhum segundo
documento foi criado.
Requisição bem formada, mas em violação de regra de negócio da DC-e. O corpo é Problem
Details e errors[] lista todas as violações, cada uma com name (o campo), reason (a
explicação) e rule (o identificador da regra) separados — não há mais texto a fatiar.