DC-e

Visão geral e fluxo de onboarding

O DC-e (modelo 99, Declaração de Conteúdo Eletrônica, Ajuste SINIEF 05/2021) é a declaração eletrônica de conteúdo que acompanha remessas de mercadorias enviadas por não contribuintes, emitida em nome deles por um marketplace, ou por uma empresa para si mesma. Cadastro de empresa, vinculação de certificado e registro de webhook são compartilhados com a NF-e; o segmento de recurso mantém o dc-e original do documento e toda operação em nível de documento fica sob /dc-e/{dceId}.

A autenticação é idêntica à NF-e: cabeçalhos token / timestamp / sign, com sign = MD5(token + path + body + timestamp) em hexadecimal minúsculo; path inclui o prefixo /openapi e as variáveis de caminho e exclui a query string; GET / DELETE sem corpo usam a string vazia; um DELETE com corpo (cancelamento com motivo) assina o JSON bruto com CR/LF removidos. Veja Autenticação.

Pré-requisitos

• A empresa deve estar aprovada com certificado utilizável (caso contrário DCe00008). O autorizador do DC-e é a SEFAZ-PR (o único autorizador listado no portal nacional do DC-e); empresas de todos os estados são roteadas para ele.
• A empresa deve ter os parâmetros de emissão de DC-e configurados: emissaoDCe.tipoEmitente e uma série do modelo 99 (sequencialDCe / serieDCe); a falta de qualquer um devolve DCe00004.
• A fase um suporta dois tipos de emitente: Marketplace (uma plataforma emitindo em nome de vendedores não contribuintes / pessoas físicas) e OwnIssuer (uma empresa emitindo para si mesma). Carrier pode ser cadastrado, mas a emissão é rejeitada (10019013) até a SVRS publicar o novo pacote de schema.
• ambiente na requisição deve ser igual ao ambiente atual da empresa, caso contrário DCe00004 (texto do documento: "not configured for the informed environment"). Após o cadastro a empresa está no ambiente de homologação (Homologacao); a troca para produção é uma ação da operação sem API, e enviar ambiente=Producao antes da troca devolve DCe00004.
• A fase um suporta apenas emissão normal (tpEmis=1); a contingência offline vem na fase dois.

Cadastro de empresa: a seção emissaoDCe

Registrar empresa aceita uma seção opcional emissaoDCe (todos os demais campos inalterados):

"emissaoDCe": {
  "ambienteProducao": {
    "tipoEmitente": "Marketplace",
    "sequencialDCe": 1,
    "serieDCe": "1",
    "siteMarketplace": "https://loja.exemplo.com.br"
  }
}

• Uma empresa cadastrada sem emissaoDCe não fica habilitada para DC-e: o cadastro é aceito, mas a resposta traz dceHabilitado=false e a emissão devolve DCe00004. Confira esse campo logo após cadastrar.
• Para habilitar DC-e depois, elevar o número inicial ou corrigir dados de contato, reenvie o payload de cadastro com id. A série do modelo 99 só avança; as regras completas de atualização estão na página Registrar empresa.

Endpoints

Carga do webhook

O registro de webhook e os cabeçalhos de assinatura são compartilhados com a NF-e; registre a URL de callback em Registrar webhook. Cabeçalhos da entrega: além dos cinco cabeçalhos de assinatura da plataforma (X-Tffiscal-Event / X-Tffiscal-Event-Id / X-Tffiscal-Delivery-Id / X-Tffiscal-Timestamp / X-Tffiscal-Signature), toda entrega traz token e x-token com o mesmo valor (o token registrado no webhook, devolvido sem alteração); o receptor pode verificar qualquer um deles.

Códigos de evento e carga de compatibilidade (tipo="DC-e", 14 campos em ordem fixa):

Campos da carga

dce.authorized

{ "tipo": "DC-e", "empresaId": "1934811222334455", "dceId": "DCe-000012333", "dceStatus": "Autorizada", "dceMotivoStatus": null,
  "dceLinkDace": "https://api.v2.tffiscal.com/openapi/files/dace/35260940673061000134990010000000011100000012?token=...", "dceLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/7?token=...",
  "dceNumero": "1", "dceSerie": "1", "dceChaveAcesso": "41260940673061000134990010000000011101234567",
  "dceDataEmissao": "2026-09-06T12:00:00Z", "dceDataAutorizacao": "2026-09-06T12:00:03Z",
  "dceNumeroProtocolo": "141260000000001", "dceDigestValue": "tasG40Ic6Zh7PIBiLEEH7Hb940Y=" }

dce.rejected

{ "tipo": "DC-e", "empresaId": "1934811222334455", "dceId": "DCe-000012333", "dceStatus": "Negada",
  "dceMotivoStatus": "225 - Rejeicao: Falha no schema XML", "dceLinkDace": null, "dceLinkXml": null,
  "dceNumero": "1", "dceSerie": "1", "dceChaveAcesso": "4126...", "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": null, "dceNumeroProtocolo": null, "dceDigestValue": null }

Falha antes da numeração (empresa não configurada para DC-e / série ausente / falha no mapeamento da mensagem e outras falhas terminais em que o documento nunca foi numerado e não tem chave): dce.rejected é entregue mesmo assim, os campos de fato do documento são null, dceMotivoStatus traz o motivo da falha e dceDataEmissao o momento da aceitação. Correlacione por dceId e nunca presuma que dceChaveAcesso está presente:

{ "tipo": "DC-e", "empresaId": "1934811222334455", "dceId": "DCe-000012333", "dceStatus": "Negada",
  "dceMotivoStatus": "Empresa não configurada para emissão de DC-e", "dceLinkDace": null, "dceLinkXml": null,
  "dceNumero": null, "dceSerie": null, "dceChaveAcesso": null, "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": null, "dceNumeroProtocolo": null, "dceDigestValue": null }

dce.canceled

{ "tipo": "DC-e", "empresaId": "1934811222334455", "dceId": "DCe-000012333", "dceStatus": "Cancelada", "dceMotivoStatus": null,
  "dceLinkDace": "https://.../openapi/files/dace/35260940673061000134990010000000011100000012?token=...", "dceLinkXml": "https://.../openapi/files/xml/7?token=...",
  "dceNumero": "1", "dceSerie": "1", "dceChaveAcesso": "4126...", "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": "2026-09-06T15:00:00Z", "dceNumeroProtocolo": "141260000000099", "dceDigestValue": null }

dce.cancel_rejected

{ "tipo": "DC-e", "empresaId": "1934811222334455", "dceId": "DCe-000012333", "dceStatus": "CancelamentoNegado",
  "dceMotivoStatus": "594 - Rejeicao: O numero de sequencia do evento informado e maior que o permitido",
  "dceLinkDace": null, "dceLinkXml": "https://.../openapi/files/xml/7?token=...", "dceNumero": "1", "dceSerie": "1",
  "dceChaveAcesso": "4126...", "dceDataEmissao": "2026-09-06T12:00:00Z", "dceDataAutorizacao": null,
  "dceNumeroProtocolo": "141260000000001", "dceDigestValue": "tasG40Ic6Zh7PIBiLEEH7Hb940Y=" }

Nos callbacks de autorização / cancelamento, dceLinkDace é o link do DACE renderizado sob demanda pela chave (nada é renderizado no momento da entrega; o primeiro download renderiza e arquiva); os dois links têm o mesmo formato da API de consulta (/openapi/files/{kind}/{ref}?token=…) e sua validade vem da configuração do inquilino (padrão 7 dias). Veja Download de arquivos.

Modelo de erros

Mesmos formatos da NF-e: erros de negócio são [{ "codigo", "mensagem" }] (HTTP 400; documento / tarefa inexistente é HTTP 404 com codigo DCe0001); erros da camada de autenticação usam o envelope da plataforma (401 / 403 / 429, veja Autenticação). Casos com código de exemplo documentado reutilizam o código do documento; todo outro codigo é o código de erro numérico da plataforma, e mensagem é localizada pelo idioma da requisição (o português usa o texto do documento).

As listas de códigos por endpoint estão em Emitir DC-e, Consultar DC-e e Cancelar DC-e. Rejeições da SEFAZ durante a emissão não são erros HTTP: aparecem como status Negada na consulta e no webhook dce.rejected; rejeições da SEFAZ ao cancelamento aparecem como dce.cancel_rejected.

Máquina de estados

Aceito (POST 200) ─→ Pendente ─numera + envia à SEFAZ─┬─ cStat 100 ─→ Autorizada ─DELETE 200─→ CancelamentoPendente ─┬─ 135/136/155 ─→ Cancelada
                                                      │                                                              └─ rejeição SEFAZ ─→ Autorizada (webhook CancelamentoNegado)
                                                      ├─ outro cStat terminal ─→ Negada
                                                      └─ parâmetros não interpretáveis / retentativas esgotadas ─→ Falha (mesmo id pode ser reenviado)

• Enquanto Pendente, indisponibilidades da SEFAZ (108 / 109) são retentadas com back-off pela plataforma; não há redirecionamento de contingência na fase um. Emissão duplicada (451 / 452 / 539) é reconciliada consultando a SEFAZ primeiro.
• Após Negada / Falha o mesmo id pode ser reenviado (reaberto com a nova mensagem); após Autorizada um reenvio com o mesmo id só aciona a idempotência.

Observações

• O CNPJ da chave é a empresa da plataforma: as posições 7-20 trazem sempre o emitente autorizado (a empresa Marketplace ou a empresa que emite para si); um remetente CPF só aparece no grupo emit do XML e no bloco REMETENTE do DACE.
• Nome fixo do destinatário no ambiente de homologação: com tpAmb=2 o nome do destinatário no XML e no DACE é DCE EMITIDA EM AMBIENTE DE HOMOLOGACAO (validação SEFAZ 598); o eco da consulta mantém o original.
• Janela de cancelamento de 24 horas: contada a partir do momento da autorização; depois dela o documento só pode ser mantido. O DC-e oficial só tem cancelamento: sem carta de correção, sem inutilização de numeração.
• Carrier ainda não suportado: o schema oficial atual restringe tpEmit a Marketplace / emitente próprio; uma empresa transportadora cadastrada é rejeitada com 10019013 na emissão.
• DACE: A4 retrato, renderizado sob demanda e cacheado; re-renderizado com a marca d'água CANCELADA após o cancelamento; o ambiente de homologação traz a marca d'água SEM VALOR FISCAL - HOMOLOGAÇÃO.
• Autorizador: o DC-e de todos os estados vai para o autorizador SEFAZ-PR; o QR code aponta para https://www.fazenda.pr.gov.br/dce/qrcode?chDCe={chave}&tpAmb={tpAmb}.

Checklist de integração

1. No ambiente de homologação: empresa cadastrada (com emissaoDCe, resposta dceHabilitado=true confirmada), certificado vinculado, webhook registrado (receptor aceita token / x-token).
2. Emita um DC-e mínimo (o exemplo em Emitir DC-e), consulte-o como Autorizada, baixe o XML e o DACE, receba o callback dce.authorized.
3. Reenvie o mesmo id uma vez e confirme HTTP 200 sem segundo documento; altere um item e reenvie, confirme 10019030.
4. Cancele o documento: confirme 200 sem corpo, consulte CancelamentoPendente → Cancelada, receba o callback dce.canceled, DACE com a marca d'água.
5. Cancele o documento cancelado de novo e confirme 10019040; consulte um id inexistente e confirme 404 DCe0001.
6. Envie erros deliberados (ambiente=Producao, cidade=9999999, remetente ausente) e confirme o array de erros 400 com os códigos DCe00004 / GW001 / DCe00005.
7. Emita para uma empresa não habilitada para DC-e e confirme DCe00004; reenvie o payload de cadastro com id e um sequencialDCe maior, confirme 200 e que o próximo documento começa do novo número; reenvie um número menor e confirme 400 10001001.