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: ele espera até 30 segundos pelo
desfecho; se a autorização não chegar a um estado terminal nesse tempo, a resposta degrada
para 202 com Location. Trate 202 como resultado possível sempre, e não só quando
você pediu.
Antes de emitir
A ordem das verificações é: contribuinte da assinatura (404), forma do pedido (400) e
regras da DC-e (422), contratação (403), e por fim o ambiente
contra o cadastro da empresa (422, regra B10-10). Nenhuma recusa consome numeração.
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.
Agrupar em lote
Para emitir vários documentos juntos e poder reenviá-los com segurança, chame esta
operação uma vez por documento, cada chamada com a sua Idempotency-Key, e o mesmo
X-Batch-Id em todas. O lote volta no campo batchId da resposta, do detalhe e da
listagem, onde é filtrável. A emissão em lote ($batch) agrupa, mas não oferece repetição
segura.
Request
Responses
- 200
- 202
- 400
- 401
- 403
- 404
- 409
- 422
- 503
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.
A requisição não tem a forma do contrato — JSON ilegível, tipo errado, valor fora do
conjunto aceito, cabeçalho fora do formato (X-Batch-Id), ou ausência de um campo que a
API exige antes de qualquer regra: emitterType, environment (ou valor fora de 1 e
2), ao menos um item em items, o issuer.cnpj em SelfIssuer, o emitterParty.site
em Marketplace. Também a identificação incompatível com a modalidade. O corpo é Problem
Details com errors[]: cada erro traz name (o caminho do campo, em camelCase) e reason
(a explicação, em inglês). Recusa de forma não traz rule.
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.
Já existe uma emissão em andamento com a mesma Idempotency-Key. Nenhum segundo
documento foi criado. Aguarde e repita com a mesma chave para receber o resultado.
A requisição se lê, e uma regra recusa o conteúdo — dígito verificador, ambiente divergente
do cadastro da empresa (B10-10), regras da DC-e. O corpo é Problem Details e errors[]
lista as violações, cada uma com name (o campo), reason (a explicação) e rule (o
identificador da regra, quando há) separados. O dígito verificador inválido de
issuer.cnpj ou issuer.cpf vem sem rule.
Também é 422 a Idempotency-Key repetida com outro corpo ou outro contribuinte, com
type …/idempotency-key-reused e sem errors[].
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 |