CT-e

概述

CT-e 接口代承运人开具电子运输单据（CT-e，模型 57，公路模态），并支持查询状态、取消，以及登记授权后事件（信函更正、交付凭证、交付失败、服务不符）。主体注册、证书关联、Webhook 注册与 NF-e 完全共用，本文只引用不重复。

路径规范：资源段按单据大类 cte，所有单据级操作都挂在 /openapi/v2/empresas/{empresaId}/cte/{cteId} 之下，其中 cteId 就是发行时传入的 id。

接入流程

前提

• 主体须已审批通过、证书可用，且该 CNPJ 在其州税务局有 CT-e 发行资质（IE 登记为运输服务提供者并在 SEFAZ 完成 CT-e 认证）。资质缺失时 SEFAZ 返回 230 - IE do emitente não cadastrada，这是主体侧的税务登记问题，平台无法代为解决。
• 主体须配置 CT-e 号段（模型 57）；未配置或存在多个启用号段且请求未指定时返回 10017007。
• 一期只支持公路模态（Rodoviario），其余模态受理即拒（10017018）。
• 请求里的 ambienteEmissao 必须与主体当前环境一致（10017010），见环境。

鉴权

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

端点

以下路径均相对于 /openapi/v2/empresas/{empresaId}/cte。

所有事件同步出站，成功返回事件对象（chaveAcesso、tipo、codigo、sequencia、status、motivo、protocolo、data、linkXml）。文本字段会被净化（去变音、折叠空白）后校验长度；坐标按六位小数登记。

注意： 服务不符两个端点是唯一以他人开具的 CT-e 的 chave 寻址的端点：本主体作为该单据的收货方 / 承担方登记事件，事件送往该单据所属州。

Webhook 回调载荷

Webhook 登记与签名头复用 NF-e，见 Webhooks。CT-e 会发出四个事件码：

cte.authorized、cte.rejected、cte.canceled

三个单据结果事件使用兼容载荷（tipo="CT-e"，字段顺序固定），与 NF-e 的 nfe* 字段平行：

{ "tipo": "CT-e", "empresaId": "1934811222334455", "cteId": "CTE-ORD-1", "cteStatus": "Autorizada", "cteMotivoStatus": null,
  "cteLinkDacte": "https://.../openapi/files/dacte/3526...?token=...", "cteLinkXml": "https://.../openapi/files/xml/7?token=...", "cteNumero": "1", "cteSerie": "1",
  "cteChaveAcesso": "3526...", "cteDataEmissao": "2026-09-06T12:00:00Z", "cteDataAutorizacao": "2026-09-06T12:00:03Z",
  "cteNumeroProtocolo": "135260000000001", "cteDigestValue": "..." }

cteLinkDacte 与 cteLinkXml 在授权回调里即可用（DACTE 首次下载才渲染）；链接不需要签名头、302 跳转，有效期与错误码见文件下载。

cte.event.registered

取消以外的任一授权后事件登记成功时发出（信函更正、交付凭证、交付失败、服务不符及其撤销）。使用平台信封（version / event_id / event_type / occurred_at / data）：

{
  "version": "1.0",
  "event_id": "7312345678901234567",
  "event_type": "cte.event.registered",
  "occurred_at": "2026-09-06T13:00:00Z",
  "data": {
    "cte_id": "1001",
    "chave": "35260940673061000134570010000000011000000010",
    "external_ref": "CTE-ORD-1",
    "event_code": "110110",
    "n_seq": 1,
    "protocolo": "135260000000099"
  }
}

错误模型

错误形状与 NF-e 相同：业务错误为 [{ "codigo", "mensagem" }]（HTTP 400；单据 / 任务不存在 HTTP 404，codigo 为 CTe0001），鉴权层错误为平台信封（401 / 403 / 429，见认证与签名）。

发行阶段的 SEFAZ 驳回不走 HTTP 错误，而是查询结果 Negada + Webhook cte.rejected。

支持范围与限制

• 模型 57 CT-e 4.00，公路模态；正常 / 补充 / 替代单；服务类型全部五种。
• 税组 ICMS 00 / 20 / 40 / 41 / 51 / 60 / 90 / OutraUF / SN + ICMSUFFim + vTotTrib；IBS/CBS 二期。
• 应急：SVC（SVC-RS / SVC-SP）与 EPEC 由平台按州配置切换，集成商无感知，查询 tipoEmissao 可见；应急授权的单据其后续事件仍送本州正常授权方。
• 不支持：其他模态、多式联运、GTV、CT-e OS（模型 67）、收票（DistDFe）。

联调清单

1. 认证测试环境完成主体注册、证书关联、CT-e 号段配置。
2. 发行一张最小 CT-e（发行 CT-e 中的示例），查询到 Autorizada，下载 XML 与 DACTE。
3. 同 id 重发一次，确认返回 200 且未产生第二张单据。
4. 登记一条信函更正与一条交付凭证，事件列表可见；撤销交付凭证。
5. 取消单据，查询到 Cancelada，收到 cte.canceled 回调。
6. 故意传错（模态 Aereo、组成合计不符），确认收到 400 错误数组。