DC-e

能力概述与接入流程

DC-e（模型 99，Declaração de Conteúdo Eletrônica，Ajuste SINIEF 05/2021）是随非纳税人寄件货物流转的电子内容申报单，由电商平台代其发件，或由企业自发。主体注册、证书关联、Webhook 登记与 NF-e 完全共用；资源段沿用文档原文 dc-e，所有单据级操作都挂在 /dc-e/{dceId} 之下。

鉴权与 NF-e 完全相同：请求头 token / timestamp / sign，sign = MD5(token + path + body + timestamp) 小写十六进制；path 含 /openapi 前缀与路径变量、不含查询串；GET / DELETE 无 body 时取空串；有 body 的 DELETE（取消带理由）按 JSON 原文去 CR/LF 参与签名。参见认证与签名。

前提

• 主体须已审批通过、证书可用（否则 DCe00008）。DC-e 的授权方为 SEFAZ-PR（DC-e 国家门户列出的唯一授权方），任何 UF 的主体都送 PR 授权方。
• 主体须配置 DC-e 发行参数：emissaoDCe.tipoEmitente 与模型 99 号段（sequencialDCe / serieDCe），缺一即 DCe00004。
• 一期支持两种主体类型：Marketplace（电商平台代非纳税人卖家 / 个人发件）与 OwnIssuer（企业自发）。Carrier 可登记但发行被拒（10019013），待 SVRS 发布新 schema 包后放开。
• 请求里的 ambiente 必须与主体当前环境一致，否则 DCe00004（文档语义 "not configured for the informed environment"）。注册后主体处于认证测试环境（Homologacao）；切生产是运营动作、不开 API，切换前传 ambiente=Producao 会收到 DCe00004。
• 一期只支持正常发行（tpEmis=1），离线应急二期。

主体注册：emissaoDCe 配置段

注册开票主体请求体新增可选段（其余字段不变）：

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

• 未传 emissaoDCe 的主体不会开通 DC-e：注册仍成功，但响应 dceHabilitado=false，发行时收到 DCe00004。请在注册当场核对该字段。
• 补开 DC-e、抬高起始号或修正联系信息：带 id 重传注册报文。模型 99 号段只升不降；完整更新规则见注册开票主体。

端点

Webhook 回调载荷

复用 NF-e 的 Webhook 登记与签名头，回调地址通过注册 Webhook登记。投递请求头：平台签名五头（X-Tffiscal-Event / X-Tffiscal-Event-Id / X-Tffiscal-Delivery-Id / X-Tffiscal-Timestamp / X-Tffiscal-Signature）之外，同时带 token 与 x-token 两个同值头（登记 webhook 时的令牌原样回传），接收端校验任一即可。

事件码与兼容载荷（tipo="DC-e"，14 个字段顺序固定）：

载荷字段

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 }

单据编号前失败（主体未配置 DC-e / 号段缺失 / 报文映射失败等终局失败，单据未编号、无 chave）：同样收到 dce.rejected，单据事实字段为 null，dceMotivoStatus 为失败原因，dceDataEmissao 为受理时刻。请以 dceId 关联，不要假定 dceChaveAcesso 一定有值：

{ "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=" }

dceLinkDace 在授权 / 取消回调里为按 chave 懒渲染的 DACE 链接（投递时刻不渲染，首次下载才渲染归档）；两个链接与查询接口同形（/openapi/files/{kind}/{ref}?token=…），有效期取租户级设置（缺省 7 天）。参见文件下载。

错误模型

错误形状与 NF-e 相同：业务错误为 [{ "codigo", "mensagem" }]（HTTP 400；单据 / 任务不存在 HTTP 404，codigo 为 DCe0001），鉴权层错误为平台信封（401 / 403 / 429，见认证与签名）。文档给出示例码的情形沿用文档码值，其余 codigo 为平台错误码数字串，mensagem 随请求语言本地化（葡语为文档原文）。

各端点的错误码清单见发行 DC-e、查询 DC-e与取消 DC-e。发行阶段的 SEFAZ 驳回不走 HTTP 错误，而是查询结果 Negada + Webhook dce.rejected；取消阶段的 SEFAZ 拒绝同理走 dce.cancel_rejected。

状态机

受理（POST 200）─→ Pendente ─取号 + 送 SEFAZ─┬─ cStat 100 ─→ Autorizada ─DELETE 200─→ CancelamentoPendente ─┬─ 135/136/155 ─→ Cancelada
                                             │                                                             └─ SEFAZ 拒绝 ─→ Autorizada（Webhook CancelamentoNegado）
                                             ├─ 其他终局 cStat ─→ Negada
                                             └─ 参数无法解析 / 重投超限 ─→ Falha（可同 id 重提）

• Pendente 期间 SEFAZ 瘫痪（108 / 109）由平台退避重试，一期无应急改道；重复发行（451 / 452 / 539）由平台先查采认。
• Negada / Falha 后同一 id 可重新提交（按新报文重开）；Autorizada 后同一 id 再提交只会命中幂等。

注意事项

• chave 的 CNPJ 是平台主体：第 7-20 位永远是授权发行方（Marketplace 主体或自发企业）的 CNPJ，CPF 发件人只出现在 XML 的 emit 组与 DACE 的 REMETENTE 块。
• 认证测试环境收件人名固定：tpAmb=2 时 XML 与 DACE 的收件人名为 DCE EMITIDA EM AMBIENTE DE HOMOLOGACAO（SEFAZ 校验 598），查询回显仍为原文。
• 24 小时取消窗口：自授权时刻起算，超时只能保留单据；DC-e 官方只有取消事件，没有更正信函与作废号段。
• Carrier 暂不支持：当前官方 schema 的 tpEmit 只允许 Marketplace / 企业自发，承运商主体登记后发行会被 10019013 拒绝。
• DACE：A4 纵向，按需渲染并缓存；取消后重渲染带 CANCELADA 水印；认证测试环境带 SEM VALOR FISCAL - HOMOLOGAÇÃO 水印。
• 授权方：全部 UF 的 DC-e 送 SEFAZ-PR 授权方，二维码指向 https://www.fazenda.pr.gov.br/dce/qrcode?chDCe={chave}&tpAmb={tpAmb}。

联调清单

1. 认证测试环境完成主体注册（带 emissaoDCe，确认响应 dceHabilitado=true）、证书关联、Webhook 登记（收端同时接受 token / x-token）。
2. 发行一张最小 DC-e（发行 DC-e页面的示例），查询到 Autorizada，下载 XML 与 DACE，收到 dce.authorized 回调。
3. 同 id 重发一次，确认返回 200 且未产生第二张单据；改一条明细重发，确认 10019030。
4. 取消单据，确认 200 无内容、查询到 CancelamentoPendente → Cancelada，收到 dce.canceled 回调，DACE 带水印。
5. 对已取消单据再次取消，确认 10019040；对不存在的 id 查询，确认 404 DCe0001。
6. 故意传错（ambiente=Producao、cidade=9999999、缺 remetente），确认收到 400 错误数组且码值为 DCe00004 / GW001 / DCe00005。
7. 对未开通 DC-e 的主体发行，确认 DCe00004；带 id 重传注册报文把 sequencialDCe 抬高，确认 200 且后续单据从新号起；再传更小的号，确认 400 10001001。