TF Fiscal
开发文档

DC-e

发行 DC-e

受理一张电子内容申报单（模型 99），并异步向 SEFAZ 授权。

POST/openapi/v2/empresas/{empresaId}/dc-e

需要 token、timestamp、sign 三个签名头，参见认证与签名。

受理成功返回 HTTP 200 无内容。同一 id 重复提交：报文指纹相同复用原任务（幂等），指纹不同返回 10019030，上一次以失败告终则按新报文重开。结果经查询接口或 Webhook dce.authorized / dce.rejected 获知（见 DC-e）。主体须已审批通过、证书可用且配置了 emissaoDCe；ambiente 须与主体当前环境一致（注意字段名是 ambiente，不是 NF-e 的 ambienteEmissao）。枚举字符串大小写不敏感。

参数

路径参数

请求体

  • idstring必填

    集成商单据 id（≤64），后续查询 / 取消以它作路径变量 dceId；幂等键。

    示例: DCe-000012333
  • ambientestring必填

    Producao / Homologacao，须与主体当前环境一致（注意字段名是 ambiente，不是 NF-e 的 ambienteEmissao）。不一致返回 DCe00004。

  • dataEmissaostring可选

    开票时刻 ISO-8601，缺省受理时刻。带偏移或 Z（2026-09-08T10:00:00-03:00）按原偏移换算；不带偏移的本地时间（2026-09-08T10:00:00）按主体 UF 时区解释。允许窗口：最多超前当前时刻 5 分钟、最多回溯 30 天（服务端可配），超出回 10019048（SEFAZ 会驳回超前的 dhEmi 并白耗一个号；回溯过远会把 chave 的 AAMM 带到远期）；落 XML dhEmi（按主体 UF 时区带偏移）。

    示例: 2026-09-06T12:00:00Z
  • remetenteobjectMarketplace / Carrier 主体必填

    发件方（Marketplace / Carrier 主体缺失返回 DCe00005）；OwnIssuer 主体可省略（等于主体自身），传了 cpfCnpj 须与主体 CNPJ 一致。

  • destinatarioobject必填

    收件方，cpfCnpj 必填（DCe00009）。

  • itensarray必填

    申报物品，1-999 项。

  • transporteobject必填

    运输信息。

  • autorizacaoDownloadXmlarray可选

    授权下载 XML 的 CPF / CNPJ，≤10（10019022）。不要放发行方自身 CNPJ（默认已可下载，授权方回「CNPJ do Marketplace ja autorizado para download」），同一证件不要重复：两者受理侧即拒。

  • informacoesAdicionaisstring可选

    电商平台附加信息（≤5000）→ infAdic/infAdMarketplace。

  • informacoesAdicionaisFiscostring可选

    面向税务机关的附加信息（≤2000）→ infAdic/infAdFisco。

  • informacoesAdicionaisEmitentestring可选

    发行方补充信息（≤5000）→ infAdic/infCpl。

  • observacoesMarketplacearray可选

    ≤10 条 → infAdic/obsMarketplace（xCampo 属性 + xTexto）。

响应

200

已受理；无响应体。单据进入 Pendente，异步取号并送 SEFAZ。通过查询接口或 Webhook 跟进。

无响应体

错误

错误码HTTP
10003000404

empresaId 不存在。

DCe00004400

主体未配置 DC-e 发行（缺 tipoEmitente / 模型 99 号段 / Marketplace 站点），或 ambiente 与主体当前环境不一致（如注册后尚未切生产就传 Producao）。注册时传 emissaoDCe 或带 id 更新补配；按主体当前环境提交。

DCe00005400

Marketplace / Carrier 主体未传 remetente。补发件方。

DCe00006400

remetente.endereco 缺失。补发件方地址。

DCe00007400

巴西发件方缺 cpfCnpj。补发件方证件。

DCe00008400

主体不可发行（未审批 / 证书未就绪）。等待审批 / 关联证书。

DCe00009400

巴西收件方缺 cpfCnpj。补收件方证件。

GW001400

市政 IBGE 码不存在或与 uf 不一致。核对 cidade / uf。

10019005400

同请求并发重复。稍后重试。

10019006400

该 CNPJ 待处理任务超限。稍后重试。

10019007400

号段无法确定（多个启用号段）。联系运营收敛号段。

10019013400

主体类型 Carrier 当前不支持发行。改用 Marketplace / OwnIssuer 主体。

10019018400

明细不合法（NCM 位数、数量 ≤ 0、单价为负）。按 mensagem 修正。

10019019400

枚举或格式非法（mensagem 点名字段：tipoPessoa、modalidade、dataEmissao、证件、电话、邮箱、自发主体 remetente 与主体不符等）。按 mensagem 修正。

10019020400

承运商 CNPJ 不合法。修正 cnpjTransportadora。

10019021400

附加信息超长。缩短文本。

10019022400

autorizacaoDownloadXml 条数或证件不合法；含发行方自身 CNPJ；同一证件重复。修正列表。

10019030400

同 id 报文不同。换 id 或沿用原报文。

10019031400

生产环境同 id 已有在途 / 已授权单据。查询原单。

10019048400

dataEmissao 超出允许窗口（超前 > 5 分钟或回溯 > 30 天，mensagem 带当前允许范围）。改用当前时刻或省略 dataEmissao。

10001001400

请求字段校验失败（每字段一条）。按 mensagem 修正。

平台计算值与文本净化

vProd = quantidade × valorUnitario（HALF_UP 2 位），vDC = Σ vProd，由平台计算并落 XML。文本字段会被净化（去变音、控制字符换空格、折叠空白）后校验长度。

受理侧校验

受理侧校验（不取号、不出站，直接 400）：主体可开票且证书可用、DC-e 已配置；ambiente 与主体一致；证件位数与校验位；市政 IBGE 与 UF 一致；cep 8 位；itens 非空且数量 / 单价 / NCM 合法；条数上限；文本超长。

发行阶段的 SEFAZ 驳回不走 HTTP 错误，而是查询结果 Negada + Webhook dce.rejected。完整状态机见 DC-e。

上一页DC-e下一页查询 DC-e