TF Fiscal
开发文档

CT-e

发行 CT-e

受理一张 CT-e（模型 57，公路模态），异步向 SEFAZ 授权。

POST/openapi/v2/empresas/{empresaId}/cte

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

受理成功返回 HTTP 200 无内容。同一 id 重复提交：报文指纹相同复用原任务（幂等），指纹不同返回 10017030，上一次以失败告终则按新报文重开。结果经查询或 Webhook 获知。枚举字符串大小写不敏感。

参数

路径参数

  • empresaIdstring必填

    注册时返回的主体（承运人）标识。

    示例: 1934811222334455

请求体

  • idstring必填

    集成商单据 id，后续查询 / 取消 / 事件全部以它作路径变量 cteId。

    示例: CTE-ORD-1
  • ambienteEmissaostring必填

    须与主体当前环境一致（10017010）。

    取值:ProducaoHomologacao
  • naturezastring必填

    业务性质（natOp），最长 60 字符。

    示例: PRESTACAO DE SERVICO DE TRANSPORTE
  • cfopstring必填

    4 位 CFOP。

    示例: 5353
  • tipostring必填

    CT-e 类型。Complementar 须传 ctesComplementados；Substituto 须传 cteSubstituido（10017015）。

    取值:NormalComplementarSubstituto
  • tipoServicostring必填

    服务类型。分包 / 转运 / 中转转运须传 documentosAnteriores。

    取值:NormalSubcontratacaoRedespachoRedespachoIntermediarioVinculadoMultimodal
  • modalstring必填

    一期只接受 Rodoviario；其余模态受理即拒（10017018）。

  • tomadorstring必填

    服务承担方。

    取值:RemetenteExpedidorRecebedorDestinatarioOutros
  • indicadorIeTomadorstring必填

    承担方 IE 指示。Contribuinte 要求承担方有数字 IE（10017013）。

  • retiraMercadoriaboolean可选

    收货人是否自提。

  • detalheRetirastring可选

    自提说明，最长 160 字符。

  • municipioEnvioobject可选

    开票地市政；缺省取主体档案市政。

  • origemobject必填

    起运市政。

  • destinoobject必填

    目的市政。

  • remetenteobject`remetente` 与 `destinatario` 至少一方

    发货人。tomador 指向的参与方必须传（10017012）。

  • destinatarioobject`remetente` 与 `destinatario` 至少一方

    收货人（destinatário）。

  • expedidorobject可选

    发运方（可选）。

  • recebedorobject可选

    接收方（recebedor，可选）。

  • tomadorOutrosobject`tomador=Outros` 时必填

    服务承担方不是上述四方之一时的承担方信息。

  • cargaobject必填

    货物信息。

  • documentosobject正常单必填

    运输单据引用；nfe / nf / outros 三者只能传一种（10017014）。补充单不再要求 documentos。

  • documentosAnterioresarray分包 / 转运 / 中转转运时必填

    前序运输单据，每个前序承运人一条；其余服务类型禁传（10017014）。

  • rodoviarioobject必填

    公路模态信息。

  • valorPrestacaoobject必填

    运费金额。

  • impostosobject必填

    税参；完整规则见下方税参小节。

  • cobrancaobject可选

    账单与分期票据（可选）。

  • cteSubstituidoobject`tipo=Substituto` 时必填

    被替代的 CT-e。

  • ctesComplementadosarray`tipo=Complementar` 时必填

    被补充 CT-e 的 chave（44 位字符串），1 到 10 个。

  • caracteristicasAdicionaisobject可选

    附加特征（可选）。

  • fluxoobject可选

    运输路线（可选）。

  • entregaobject可选

    交付窗口（可选）。

  • observacoesstring可选

    自由备注，最长 2000 字符。

  • observacoesContribuintearray可选

    纳税人备注，最多 10 条。

  • observacoesFiscoarray可选

    给税务机关的备注，最多 10 条。

  • autorizadosXmlarray可选

    授权下载 XML 的 CPF / CNPJ（字符串数组），最多 10 个。

响应

200

已受理。无响应体；授权异步进行。

无响应体

错误

错误码HTTP
10003000404

empresaId 不存在。

10017004400

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

10017005400

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

10017006400

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

10017007400

号段无法确定（未配置或多个启用号段未指定）。配置模型 57 号段。

10017010400

ambienteEmissao 与主体环境不一致。按主体环境提交。

10017011400

市政 IBGE 码不存在。核对 codigoIbge。

10017012400

参与方缺失。补充 tomador 指向的参与方。

10017013400

承担方与 IE 指示不符。调整 indicadorIeTomador 或承担方 IE。

10017014400

单据引用不合法（缺失、chave 校验位错、三种类型混用、前序单据与服务类型不符）。

10017015400

单据类型与引用不符。按 tipo 补 ctesComplementados / cteSubstituido。

10017016400

运费组成合计不等于总额，或 aReceber > 总额。修正金额。

10017017400

RNTRC 非法。

10017018400

模态不支持。

10017019400

枚举或格式非法；mensagem 点名字段。

10017020400

税参缺失。

10017021400

税参禁传（如 ibsCbs，或 CST 00 传了 percentualReducaoBase）。

10017022400

CST 与主体税制不符（Simples 只能 SN，正常计税不得 SN）。

10017023400

跨州且承担方为非纳税人时缺 icmsUfFim。

10017024400

州内无税率表且未直传税率。

10017025400

CST 不支持。

10017030400

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

10017031400

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

10001001400

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

税参（`impostos`）

字段说明
icms.situacaoTributaria（必填）00 / 20 / 40 / 41 / 51 / 60 / 90 / 90-OutraUF / SN；须与主体税制匹配：Simples（CRT 1/4）只能 SN，正常计税不得 SN（10017022）
icms.baseCalculo / aliquota / valor直传优先；不传时税基取服务总额，税率取州内税率表 / 州际法定率（7% 或 12%），税额自动计算；州内无税率表且未直传返回 10017024
icms.percentualReducaoBaseCST 20 必填；CST 00 禁传
icms.valorDesonerado / codigoBeneficioCST 20 / 40 / 41 / 51 / 60 / 90 组可选，缺省 0.00 / SEM CBENEF
icms.valorCreditoCST 60 / 90 可选
icms.stRetidoCST 60 必填：{ "baseCalculo", "aliquota", "valor" }
icms.outraUf90-OutraUF 可选：{ "baseCalculo", "aliquota", "valor", "percentualReducaoBase" }，缺省回落 icms.*
icmsUfFim跨州且 indicadorIeTomador=NaoContribuinte 必填（10017023）；州内禁传。字段 baseCalculo / percentualFcp / aliquotaInterna / aliquotaInterestadual / valorFcp / valorUfFim / valorUfIni 全部可选，缺省按目的州内部率与 FCP 表计算
percentualCargaTributaria近似税负百分比，用于 vTotTrib
informacoesFisco给税务机关的附加信息（≤2000）
ibsCbs一期未开放，传了即拒（10017021）

SEFAZ 驳回

发行阶段的 SEFAZ 驳回不走 HTTP 错误，而是查询结果 Negada + Webhook cte.rejected，motivoStatus / cteMotivoStatus 形如 cStat - xMotivo。任务终态失败（Falha）不发回调，请经查询获知。

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