其他电子凭证
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/create | POST | 开具 CT-e |
/api/cte/cancel | POST | 取消 CT-e(事件 110111) |
/api/cte/cce | POST | 更正函 — CC-e(事件 110110) |
/api/cte/consult | POST | 查询 CT-e 状态 |
服务承接方(支付运费的一方)在 ide.toma 中定义:0=发件方,1=发货方,2=收货方,3=收件方,4=其他(此时请填写 ide.toma4)。
/api/cte/create开具 CT-e
根据发送的请求体开具一张 CT-e。客户端只发送业务数据;访问密钥的技术识别字段由服务器计算(见 ide 表下方的说明)。仅在生产环境(tpAmb=1)且 CT-e 被授权时才扣除额度。下方示例覆盖最常见的情形:公路运输方式(modal=01)和 正常 CT-e(tpCTe=0)。
必需请求头
| 请求头 | 类型 | 说明 |
|---|---|---|
| token | string | 开票公司的 Token |
| sign | string | MD5 签名:MD5(token + path + body + timestamp) |
| timestamp | string | Unix 时间戳(秒,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 * | object | CT-e 的标识 |
| emit * | object | 开具方(承运人)数据 |
| rem * | object | 货物发件方 |
| dest * | object | 货物收件方 |
| vPrest * | object | 服务提供的金额 |
| imp * | object | 税费(ICMS + 各项税) |
| infCTeNorm * | object | 正常 CT-e 的主体 — 当 tpCTe=0(正常)或 3(替代)时必填 |
| exped | object | 发货方(可选) |
| receb | object | 收货方(可选) |
| compl | object | 补充数据(备注、流向、交付) |
| infCteComp | object | 被补充 CT-e 的密钥 — 当 tpCTe=1(补充)时必填:{ chCTe } |
| infCteAnu | object | 被撤销 CT-e 的密钥 — 当 tpCTe=2(撤销)时必填:{ chCte, dEmi } |
| autXML | array | 被授权访问 XML 的 CNPJ/CPF:[{ CNPJ } | { CPF }] |
| infRespTec | object | 技术负责人 — 由服务器按 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 * | int | CT-e 类型:0=正常,1=补充,2=撤销,3=替代 |
| tpServ * | int | 服务类型:0=正常,1=分包,2=转运,3=中间转运,4=与多式联运关联的服务 |
| toma * | int | 服务承接方:0=发件方,1=发货方,2=收货方,3=收件方,4=其他 |
| toma4 | object | 承接方数据 — 当 toma=4 时必填(见下表) |
| indIEToma | int | 承接方 IE 指示符:1=ICMS 纳税人,2=免税,9=非纳税人(为 9 时承接方的 IE 会被自动省略) |
| cMunIni * | long | 服务起始自治市的 IBGE 代码(7 位) |
| xMunIni | string | 起始自治市名称 |
| UFIni * | string | 起始 UF(2 个字母) |
| cMunFim * | long | 服务终止自治市的 IBGE 代码(7 位) |
| xMunFim | string | 终止自治市名称 |
| UFFim * | string | 终止 UF(2 个字母) |
| cMunEnv | long | 开具自治市的 IBGE 代码 |
| xMunEnv | string | 开具自治市名称 |
| UFEnv | string | 开具 UF |
| retira | int | 是否在起运地自提:0=是,1=否。默认:1 |
| xDetRetira | string | 自提详情 |
| tpImp | int | DACTE 格式:1=纵向,2=横向。默认:1 |
| infPercurso | array | 途经的 UF:[{ UFPer }] |
| dhCont | string | 进入应急状态的日期/时间(ISO 8601) |
| xJust | string | 应急理由 |
| serie | int | CT-e 系列号(访问密钥的 3 位)。可选——省略或为 0 时自动分配(公司的 CT-e 系列);发送时则按发送值使用 |
| nCT | long | CT-e 编号(构成访问密钥)。可选——省略或为 0 时由服务器自动递增;发送时则按发送值使用(便于跳过编号,例如:发生重复后) |
由服务器自动填充——无须发送: mod(固定为 57)、cCT(8 位数字代码)、cDV(校验位)、cUF(从开具方的 UF 推导)、dhEmi(当前日期/时间)、tpEmis(默认 1=正常)、procEmi 和 verProc。
toma4 — 承接方“其他”(当 ide.toma=4 时)
| 字段 | 类型 | 说明 |
|---|---|---|
| CNPJ ⚠ / CPF ⚠ | string | 承接方证件(二者之一) |
| IE | string | 州登记号 |
| xNome | string | 公司名称/姓名 |
| xFant, fone, email | string | 商号、电话、电子邮箱 |
| enderToma | object | 地址:{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, cPais, xPais } |
emit — 开具方(承运人)
| 字段 | 类型 | 说明 |
|---|---|---|
| CNPJ ⚠ | string | 开具方 CNPJ(14 位) |
| CPF ⚠ | string | 开具方 CPF(11 位) |
| IE | string | 州登记号 |
| IEST | string | 税务代扣代缴义务人的州登记号 |
| xNome * | string | 公司名称 |
| xFant | string | 商号 |
| CRT | int | 税收制度代码:1=简易税制,2=超出子上限的简易税制,3=常规税制,4=个体微型企业(MEI)。默认:3 |
| enderEmit | object | 地址:{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone } |
rem — 发件方
| 字段 | 类型 | 说明 |
|---|---|---|
| CNPJ ⚠ / CPF ⚠ | string | 发件方证件(二者之一) |
| IE | string | 州登记号(或 "ISENTO") |
| xNome | string | 公司名称/姓名 |
| xFant, fone, email | string | 商号、电话、电子邮箱 |
| enderReme | object | 发件方地址(结构见下方) |
| locColeta | array | 收件地点(可选):[{ CNPJ|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }] |
dest — 收件方
| 字段 | 类型 | 说明 |
|---|---|---|
| CNPJ ⚠ / CPF ⚠ | string | 收件方证件(二者之一) |
| IE | string | 州登记号(或 "ISENTO") |
| xNome | string | 公司名称/姓名 |
| fone, email, ISUF | string | 电话、电子邮箱、SUFRAMA 登记号 |
| enderDest | object | 收件方地址(结构见下方) |
| locEnt | object | 交付地点(可选):{ CNPJ|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF } |
exped / receb — 发货方 / 收货方(可选)
| 字段 | 类型 | 说明 |
|---|---|---|
| CNPJ / CPF | string | 证件(二者之一) |
| IE, xNome, fone, email | string | 州登记号、名称、电话、电子邮箱 |
| enderExped / enderReceb | object | 地址(与下方通用结构相同) |
地址(enderEmit / enderReme / enderExped / enderReceb / enderDest)
| 字段 | 类型 | 说明 |
|---|---|---|
| xLgr | string | 街道 |
| nro | string | 门牌号 |
| xCpl | string | 补充信息 |
| xBairro | string | 街区 |
| cMun | string | 自治市 IBGE 代码(7 位) |
| xMun | string | 自治市名称 |
| CEP | string | 邮政编码(8 位)— 在 enderEmit 中不使用 |
| UF | string | UF 简称(2 个字母) |
| cPais | string | 国家代码(可选,默认 1058 巴西) |
| xPais | string | 国家名称(可选) |
| fone | string | 电话(仅在 enderEmit 中) |
vPrest — 服务提供的金额
| 字段 | 类型 | 说明 |
|---|---|---|
| vTPrest * | decimal | 服务提供的总金额(> 0) |
| vRec | decimal | 应收金额 |
| Comp | array | 金额构成项:[{ xNome, vComp }] — 例如:"FRETE PESO"、"PEDÁGIO"、"GRIS" |
imp — 税费
| 字段 | 类型 | 说明 |
|---|---|---|
| ICMS * | object | ICMS 课税 — 仅填写一个变体(见下方) |
| vTotTrib | decimal | 税费近似总额 |
| infAdFisco | string | 税务机关关注的附加信息 |
| ICMSUFFim | object | DIFAL(跨州分摊,可选):{ vBCUFFim, pFCPUFFim, pICMSUFFim, pICMSInter, vFCPUFFim, vICMSUFFim, vICMSUFIni } |
| infTribFed | object | 联邦税(可选):{ 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 | 货物信息(见下表) |
| infDoc | object | 所运输的单据(见下表) |
| infModal * | object | 运输方式信息(见下表) |
| docAnt | object | 前序单据(分包/转运):{ emiDocAnt[]{ CNPJ|CPF, IE, UF, xNome, idDocAnt[] } } |
| seg | array | 货物保险:[{ respSeg, xSeg, CNPJ, nApol, nAver, vCarga }] — respSeg:1=发件方……6=承接方 |
| cobr | object | 收款/发票:{ fat{ nFat, vOrig, vDesc, vLiq }, dup[]{ nDup, dVenc, vDup } } |
| veicNovos | array | 所运输的新车辆:[{ chassi, cCor, xCor, cMod, vUnit, vFrete }] |
| infCteSub | object | 替代 — 当 tpCTe=3 时必填:{ chCte, indAltToma, refNF, tomaICMS, tomaNaoICMS } |
infCTeNorm.infCarga — 货物
| 字段 | 类型 | 说明 |
|---|---|---|
| proPred * | string | 主要产品 |
| vCarga | decimal | 货物总金额 |
| xOutCat | string | 货物其他特征(例如:FRIA、GRANEL、REFRIGERADA) |
| vCargaAverb | decimal | 用于保险登记的货物金额 |
| infQ[] * | array | 数量 — 最少 1 个:[{ cUnid, tpMed, qCarga }] |
| infQ[].cUnid | string | 单位:"00"=立方米,"01"=千克,"02"=吨,"03"=件,"04"=升,"05"=MMBTU |
| infQ[].tpMed | string | 计量类型(例如:"PESO BRUTO"、"PESO DECLARADO") |
| infQ[].qCarga | decimal | 数量 |
infCTeNorm.infDoc — 所运输的单据
| 字段 | 类型 | 说明 |
|---|---|---|
| infNFe | array | 按访问密钥列出的 NF-e:[{ chave, PIN, dPrev, infUnidCarga[], infUnidTransp[] }] — chave 为 44 位 |
| infNF | array | 纸质票据(旧式):[{ mod, serie, nDoc, dEmi, vBC, vICMS, vProd, vNF, nCFOP, nPeso, … }] |
| infOutros | array | 其他单据:[{ 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, xEmi | string | 运输的附加特征 / 服务的附加特征 / 开票人姓名 |
| origCalc, destCalc | string | 用于计算运费的起始 / 终止自治市 |
| xObs | string | 一般备注 |
| ObsCont / ObsFisco | array | 纳税人 / 税务机关的自由备注:[{ xCampo, xTexto }] |
| fluxo, Entrega | object | 货物流向(起点/中转/终点/路线)和预计交付 |
* 必填字段。⚠ 本组中 CNPJ 或 CPF 至少其中一个为必填项。
/api/cte/cancel取消 CT-e
取消一张已授权的 CT-e(事件 110111)。要求该 CT-e 已被授权(具有协议号)且尚未取消。
必需请求头
| 请求头 | 类型 | 说明 |
|---|---|---|
| token | string | 开票公司的 Token |
| sign | string | MD5 签名 |
| timestamp | string | Unix 时间戳(秒) |
Body
| 字段 | 类型 | 说明 |
|---|---|---|
| chCTe * | string | CT-e 访问密钥(44 位) |
| xJust * | string | 取消理由(按税务局要求最少 15 个字符) |
| nProt | string | 授权协议号。可选:省略时使用开具时登记的协议号 |
* 必填字段。
/api/cte/cce更正函(CC-e)
对一张已授权的 CT-e 登记一份电子更正函(事件 110110)。CC-e 不能更正影响税额的金额、变更开具方/承接方/发件方/收件方的登记数据,或开具日期。每条更正需指明组、字段和新值。
必需请求头
| 请求头 | 类型 | 说明 |
|---|---|---|
| token | string | 开票公司的 Token |
| sign | string | MD5 签名 |
| timestamp | string | Unix 时间戳(秒) |
Body
| 字段 | 类型 | 说明 |
|---|---|---|
| chCTe * | string | CT-e 访问密钥(44 位) |
| infCorrecao[] * | array | 更正项(最少 1 项,最多 20 项) |
| infCorrecao[].grupoAlterado * | string | 被更改的组(例如:"ide"、"rem"、"dest") |
| infCorrecao[].campoAlterado * | string | 被更改的字段(例如:"xNome") |
| infCorrecao[].valorAlterado * | string | 新值 |
| infCorrecao[].nroItemAlterado | int | 被更改项的编号(当该组为列表时) |
* 必填字段。使用条件(xCondUso)由服务器自动填充。
/api/cte/consult查询 CT-e 状态
根据访问密钥在税务局查询 CT-e 的状态。当 CT-e 已取消(本地记录)时,响应会反映该取消。
必需请求头
| 请求头 | 类型 | 说明 |
|---|---|---|
| token | string | 开票公司的 Token |
| sign | string | MD5 签名 |
| timestamp | string | Unix 时间戳(秒) |
Body
| 字段 | 类型 | 说明 |
|---|---|---|
| chCTe * | string | CT-e 访问密钥(44 位) |
* 必填字段。
/api/cte/get_listCT-e 列表(分页)
分页列出公司的 CT-e。参数通过 查询字符串(query string)传递(不在 body 中)。时间过滤可选,但若使用则需同时传入 start_create_time 和 end_create_time。
必需请求头
| 请求头 | 类型 | 说明 |
|---|---|---|
| token | string | 开票公司令牌 |
| sign | string | MD5 签名(path 包含查询字符串) |
| timestamp | string | 秒级 Unix 时间戳 |
查询字符串
| 参数 | 类型 | 说明 |
|---|---|---|
| page * | int | 页码(≥ 1) |
| page_size * | int | 每页大小(1–50) |
| start_create_time | long | Unix 时间戳(毫秒) — 起始(需要 end_create_time) |
| end_create_time | long | Unix 时间戳(毫秒) — 结束 |
| status | string | 按状态过滤。值: "Success"(已授权)、"Canceled"(已取消)、"Processing"(处理中)、"Failed"(失败)、"Unknown"(未知) |
* 必填字段。