TF Fiscal

其他电子凭证

CT-e 运输凭证

5 个接口

CT-e API(型号 57,布局 4.00 + NT2025/001)支持开具、取消、更正(CC-e)与查询电子运输凭证。CT-e 用于记录货物运输服务。支持 6 种运输方式(公路、航空、水运、铁路、管道、多式联运)和 4 种 CT-e 类型(正常、补充、撤销、替代)。业务数据放在 /create 的请求体中;访问密钥的技术字段(cCT、cDV、cUF、dhEmi、mod)由服务器自动计算。serie 和 nCT 为可选字段——省略(或为 0)时由服务器自动分配,发送时则予以采用(适用于跳过编号,例如在税务局出现重复后)。

端点方法说明
/api/cte/createPOST开具 CT-e
/api/cte/cancelPOST取消 CT-e(事件 110111)
/api/cte/ccePOST更正函 — CC-e(事件 110110)
/api/cte/consultPOST查询 CT-e 状态

服务承接方(支付运费的一方)在 ide.toma 中定义:0=发件方,1=发货方,2=收货方,3=收件方,4=其他(此时请填写 ide.toma4)。

POST/api/cte/create

开具 CT-e

根据发送的请求体开具一张 CT-e。客户端只发送业务数据;访问密钥的技术识别字段由服务器计算(见 ide 表下方的说明)。仅在生产环境(tpAmb=1)且 CT-e 被授权时才扣除额度。下方示例覆盖最常见的情形:公路运输方式(modal=01)和 正常 CT-e(tpCTe=0)。

必需请求头

请求头类型说明
tokenstring开票公司的 Token
signstringMD5 签名:MD5(token + path + body + timestamp)
timestampstringUnix 时间戳(秒,5 分钟窗口)
请求中的必填字段: ide(tpAmb、CFOP、natOp、modal、tpCTe、toma、cMunIni、UFIni、cMunFim、UFFim);emit 含 CNPJ 或 CPF 和 xNome;rem 含 CNPJ 或 CPF;dest 含 CNPJ 或 CPF;vPrest.vTPrest > 0;imp(含一个 ICMS 变体)。对于 tpCTe=0(正常):infCTeNorm 含 infCarga(proPred + 至少 1 个 infQ)和 infModal(与 ide.modal 对应的运输方式;对于 modal=01,rodo.RNTRC 为必填)。其余字段均为可选。

Body — 根

字段类型说明
ide *objectCT-e 的标识
emit *object开具方(承运人)数据
rem *object货物发件方
dest *object货物收件方
vPrest *object服务提供的金额
imp *object税费(ICMS + 各项税)
infCTeNorm *object正常 CT-e 的主体 — 当 tpCTe=0(正常)或 3(替代)时必填
expedobject发货方(可选)
recebobject收货方(可选)
complobject补充数据(备注、流向、交付)
infCteCompobject被补充 CT-e 的密钥 — 当 tpCTe=1(补充)时必填:{ chCTe }
infCteAnuobject被撤销 CT-e 的密钥 — 当 tpCTe=2(撤销)时必填:{ chCte, dEmi }
autXMLarray被授权访问 XML 的 CNPJ/CPF:[{ CNPJ } | { CPF }]
infRespTecobject技术负责人 — 由服务器按 UF 自动填充

ide — 标识

字段类型说明
tpAmb *int环境:1=生产,2=测试
CFOP *int操作的财税代码(例如:5353 州内,6353 跨州)
natOp *string操作性质(例如:"PRESTACAO DE SERVICO DE TRANSPORTE")
modal *string运输方式:"01"=公路,"02"=航空,"03"=水运,"04"=铁路,"05"=管道,"06"=多式联运
tpCTe *intCT-e 类型:0=正常,1=补充,2=撤销,3=替代
tpServ *int服务类型:0=正常,1=分包,2=转运,3=中间转运,4=与多式联运关联的服务
toma *int服务承接方:0=发件方,1=发货方,2=收货方,3=收件方,4=其他
toma4object承接方数据 — 当 toma=4 时必填(见下表)
indIETomaint承接方 IE 指示符:1=ICMS 纳税人,2=免税,9=非纳税人(为 9 时承接方的 IE 会被自动省略)
cMunIni *long服务起始自治市的 IBGE 代码(7 位)
xMunInistring起始自治市名称
UFIni *string起始 UF(2 个字母)
cMunFim *long服务终止自治市的 IBGE 代码(7 位)
xMunFimstring终止自治市名称
UFFim *string终止 UF(2 个字母)
cMunEnvlong开具自治市的 IBGE 代码
xMunEnvstring开具自治市名称
UFEnvstring开具 UF
retiraint是否在起运地自提:0=是,1=否。默认:1
xDetRetirastring自提详情
tpImpintDACTE 格式:1=纵向,2=横向。默认:1
infPercursoarray途经的 UF:[{ UFPer }]
dhContstring进入应急状态的日期/时间(ISO 8601)
xJuststring应急理由
serieintCT-e 系列号(访问密钥的 3 位)。可选——省略或为 0 时自动分配(公司的 CT-e 系列);发送时则按发送值使用
nCTlongCT-e 编号(构成访问密钥)。可选——省略或为 0 时由服务器自动递增;发送时则按发送值使用(便于跳过编号,例如:发生重复后)

由服务器自动填充——无须发送: mod(固定为 57)、cCT(8 位数字代码)、cDV(校验位)、cUF(从开具方的 UF 推导)、dhEmi(当前日期/时间)、tpEmis(默认 1=正常)、procEmi 和 verProc。

toma4 — 承接方“其他”(当 ide.toma=4 时)

字段类型说明
CNPJ ⚠ / CPF ⚠string承接方证件(二者之一)
IEstring州登记号
xNomestring公司名称/姓名
xFant, fone, emailstring商号、电话、电子邮箱
enderTomaobject地址:{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, cPais, xPais }

emit — 开具方(承运人)

字段类型说明
CNPJ ⚠string开具方 CNPJ(14 位)
CPF ⚠string开具方 CPF(11 位)
IEstring州登记号
IESTstring税务代扣代缴义务人的州登记号
xNome *string公司名称
xFantstring商号
CRTint税收制度代码:1=简易税制,2=超出子上限的简易税制,3=常规税制,4=个体微型企业(MEI)。默认:3
enderEmitobject地址:{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone }

rem — 发件方

字段类型说明
CNPJ ⚠ / CPF ⚠string发件方证件(二者之一)
IEstring州登记号(或 "ISENTO")
xNomestring公司名称/姓名
xFant, fone, emailstring商号、电话、电子邮箱
enderRemeobject发件方地址(结构见下方)
locColetaarray收件地点(可选):[{ CNPJ|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }]

dest — 收件方

字段类型说明
CNPJ ⚠ / CPF ⚠string收件方证件(二者之一)
IEstring州登记号(或 "ISENTO")
xNomestring公司名称/姓名
fone, email, ISUFstring电话、电子邮箱、SUFRAMA 登记号
enderDestobject收件方地址(结构见下方)
locEntobject交付地点(可选):{ CNPJ|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }

exped / receb — 发货方 / 收货方(可选)

字段类型说明
CNPJ / CPFstring证件(二者之一)
IE, xNome, fone, emailstring州登记号、名称、电话、电子邮箱
enderExped / enderRecebobject地址(与下方通用结构相同)

地址(enderEmit / enderReme / enderExped / enderReceb / enderDest)

字段类型说明
xLgrstring街道
nrostring门牌号
xCplstring补充信息
xBairrostring街区
cMunstring自治市 IBGE 代码(7 位)
xMunstring自治市名称
CEPstring邮政编码(8 位)— 在 enderEmit 中不使用
UFstringUF 简称(2 个字母)
cPaisstring国家代码(可选,默认 1058 巴西)
xPaisstring国家名称(可选)
fonestring电话(仅在 enderEmit 中)

vPrest — 服务提供的金额

字段类型说明
vTPrest *decimal服务提供的总金额(> 0)
vRecdecimal应收金额
Comparray金额构成项:[{ xNome, vComp }] — 例如:"FRETE PESO"、"PEDÁGIO"、"GRIS"

imp — 税费

字段类型说明
ICMS *objectICMS 课税 — 仅填写一个变体(见下方)
vTotTribdecimal税费近似总额
infAdFiscostring税务机关关注的附加信息
ICMSUFFimobjectDIFAL(跨州分摊,可选):{ vBCUFFim, pFCPUFFim, pICMSUFFim, pICMSInter, vFCPUFFim, vICMSUFFim, vICMSUFIni }
infTribFedobject联邦税(可选):{ vPIS, vCOFINS, vIR, vINSS, vCSLL }

ICMS — 变体(仅填写一个)

变体何时使用字段
ICMS00正常课税{ vBC, pICMS, vICMS }(CST 00)
ICMS20含计税基数减免{ pRedBC, vBC, pICMS, vICMS }(CST 20)
ICMS45免税 / 不课税 / 递延{ CST } — "40"=免税,"41"=不课税,"51"=递延
ICMS60按税务代扣代缴征收的 ICMS{ vBCSTRet, vICMSSTRet, pICMSSTRet, vCred }(CST 60)
ICMS90其他(特殊制度){ pRedBC, vBC, pICMS, vICMS, vCred }(CST 90)
ICMSOutraUF应缴往其他 UF 的 ICMS{ pRedBCOutraUF, vBCOutraUF, pICMSOutraUF, vICMSOutraUF }
ICMSSN简易税制开具方{ CST: "90", indSN: 1 }

infCTeNorm — 正常 CT-e(tpCTe=0/3 时必填)

字段类型说明
infCarga *object货物信息(见下表)
infDocobject所运输的单据(见下表)
infModal *object运输方式信息(见下表)
docAntobject前序单据(分包/转运):{ emiDocAnt[]{ CNPJ|CPF, IE, UF, xNome, idDocAnt[] } }
segarray货物保险:[{ respSeg, xSeg, CNPJ, nApol, nAver, vCarga }] — respSeg:1=发件方……6=承接方
cobrobject收款/发票:{ fat{ nFat, vOrig, vDesc, vLiq }, dup[]{ nDup, dVenc, vDup } }
veicNovosarray所运输的新车辆:[{ chassi, cCor, xCor, cMod, vUnit, vFrete }]
infCteSubobject替代 — 当 tpCTe=3 时必填:{ chCte, indAltToma, refNF, tomaICMS, tomaNaoICMS }

infCTeNorm.infCarga — 货物

字段类型说明
proPred *string主要产品
vCargadecimal货物总金额
xOutCatstring货物其他特征(例如:FRIA、GRANEL、REFRIGERADA)
vCargaAverbdecimal用于保险登记的货物金额
infQ[] *array数量 — 最少 1 个:[{ cUnid, tpMed, qCarga }]
infQ[].cUnidstring单位:"00"=立方米,"01"=千克,"02"=吨,"03"=件,"04"=升,"05"=MMBTU
infQ[].tpMedstring计量类型(例如:"PESO BRUTO"、"PESO DECLARADO")
infQ[].qCargadecimal数量

infCTeNorm.infDoc — 所运输的单据

字段类型说明
infNFearray按访问密钥列出的 NF-e:[{ chave, PIN, dPrev, infUnidCarga[], infUnidTransp[] }] — chave 为 44 位
infNFarray纸质票据(旧式):[{ mod, serie, nDoc, dEmi, vBC, vICMS, vProd, vNF, nCFOP, nPeso, … }]
infOutrosarray其他单据:[{ tpDoc, descOutros, nDoc, dEmi, vDocFisc }] — tpDoc:"00"=声明,"10"=管道,"99"=其他

infCTeNorm.infModal — 运输方式(仅填写与 ide.modal 对应的一项)

运输方式对象字段
01 公路rodo{ RNTRC* } — RNTRC 为 8 位或 "ISENTO"。可选:occ[](收件单)
02 航空aereo{ nMinu, nOCA, dPrevAereo, natCarga{ xDime, cInfManu[] }, tarifa{ CL, cTar, vTar }, peri[] } — dPrevAereo AAAA-MM-DD
03 水运aquav{ vPrest, vAFRMM, xNavio, nViag, direc, irin, tpNav, balsa[], detCont[] } — direc:N/L/S/O;tpNav:0=内河,1=沿海航运
04 铁路ferrov{ tpTraf, respFat, ferrEmi, vFrete, chCTeFerroOrigem, ferroEnv[] } — tpTraf:0=自有,1=互用,2=公铁联运,3=公路
05 管道duto{ vTar, dIni, dFim } — 日期 AAAA-MM-DD
06 多式联运multimodal{ COTM, indNegociavel, seg[] } — indNegociavel:0=否,1=是

整个 infModal 块都接受 versaoModal(默认 "4.00")。

compl — 补充数据(可选)

字段类型说明
xCaracAd, xCaracSer, xEmistring运输的附加特征 / 服务的附加特征 / 开票人姓名
origCalc, destCalcstring用于计算运费的起始 / 终止自治市
xObsstring一般备注
ObsCont / ObsFiscoarray纳税人 / 税务机关的自由备注:[{ xCampo, xTexto }]
fluxo, Entregaobject货物流向(起点/中转/终点/路线)和预计交付

* 必填字段。⚠ 本组中 CNPJ 或 CPF 至少其中一个为必填项。

POST/api/cte/cancel

取消 CT-e

取消一张已授权的 CT-e(事件 110111)。要求该 CT-e 已被授权(具有协议号)且尚未取消。

必需请求头

请求头类型说明
tokenstring开票公司的 Token
signstringMD5 签名
timestampstringUnix 时间戳(秒)

Body

字段类型说明
chCTe *stringCT-e 访问密钥(44 位)
xJust *string取消理由(按税务局要求最少 15 个字符)
nProtstring授权协议号。可选:省略时使用开具时登记的协议号

* 必填字段。

POST/api/cte/cce

更正函(CC-e)

对一张已授权的 CT-e 登记一份电子更正函(事件 110110)。CC-e 不能更正影响税额的金额、变更开具方/承接方/发件方/收件方的登记数据,或开具日期。每条更正需指明组、字段和新值。

必需请求头

请求头类型说明
tokenstring开票公司的 Token
signstringMD5 签名
timestampstringUnix 时间戳(秒)

Body

字段类型说明
chCTe *stringCT-e 访问密钥(44 位)
infCorrecao[] *array更正项(最少 1 项,最多 20 项)
infCorrecao[].grupoAlterado *string被更改的组(例如:"ide"、"rem"、"dest")
infCorrecao[].campoAlterado *string被更改的字段(例如:"xNome")
infCorrecao[].valorAlterado *string新值
infCorrecao[].nroItemAlteradoint被更改项的编号(当该组为列表时)

* 必填字段。使用条件(xCondUso)由服务器自动填充。

POST/api/cte/consult

查询 CT-e 状态

根据访问密钥在税务局查询 CT-e 的状态。当 CT-e 已取消(本地记录)时,响应会反映该取消。

必需请求头

请求头类型说明
tokenstring开票公司的 Token
signstringMD5 签名
timestampstringUnix 时间戳(秒)

Body

字段类型说明
chCTe *stringCT-e 访问密钥(44 位)

* 必填字段。

GET/api/cte/get_list

CT-e 列表(分页)

分页列出公司的 CT-e。参数通过 查询字符串(query string)传递(不在 body 中)。时间过滤可选,但若使用则需同时传入 start_create_time 和 end_create_time。

必需请求头

请求头类型说明
tokenstring开票公司令牌
signstringMD5 签名(path 包含查询字符串)
timestampstring秒级 Unix 时间戳

查询字符串

参数类型说明
page *int页码(≥ 1)
page_size *int每页大小(1–50)
start_create_timelongUnix 时间戳(毫秒) — 起始(需要 end_create_time)
end_create_timelongUnix 时间戳(毫秒) — 结束
statusstring按状态过滤。值: "Success"(已授权)、"Canceled"(已取消)、"Processing"(处理中)、"Failed"(失败)、"Unknown"(未知)

* 必填字段。