NF-e 电子发票 · TF Fiscal API

POST/api/invoice/create

开具新发票

开具 NF-e（型号 55）。开票公司通过 token 请求头识别，请勿在请求体中传入 company_id。

必需请求头

请求头	类型	说明
token	string	开票公司的令牌
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	秒级 Unix 时间戳（5 分钟有效窗口）

Body — 顶层字段

字段	类型	说明
标识和操作
id	string	客户端提供的唯一 ID 用于幂等性（组成去重键）
nature_of_operation *	string	操作性质（如："商品销售"）
transaction_type *	string	类型: `"0"`=入库, `"1"`=出库, `"2"`=进口, `"3"`=出口
model *	string	文档型号: `"55"`=NF-e
issuance_type *	string	开具类型 (`"1"`=正常, `"9"`=应急, 等)
ambiente *	string	`"1"`=生产, `"2"`=测试
finalidade	string	用途: `"1"`=正常, `"2"`=补充, `"3"`=调整, `"4"`=退货
ref_nfe_chave	string	引用 NF-e 的 44 位访问密钥（补充/调整/退货用）
is_reopen	boolean	重新打开/覆盖之前已开具的 NF-e
dh_sai_ent	string	出入库日期时间（ISO 8601）。默认: 当前时间戳
金额和折扣
total_discount_amount	decimal	发票总折扣
price_includes_ipi	boolean	单价是否已含 IPI。true 时从含税价倒推 IPI，发票总额 = 报价；默认 false。可被商品行同名字段覆盖
troco	decimal	找零（NFC-e 常见）
seguro	decimal	保险金额（按比例分摊到各产品的 XML `vSeg` 字段）
outras_despesas	decimal	其他费用（按比例分摊到各产品的 XML `vOutro` 字段）
指示符和附加信息
ind_final	string	最终消费者: `"0"`=B2B, `"1"`=B2C
ind_pres	string	到场指示符: `"1"`=面对面, `"2"`=互联网, `"3"`=电话服务等
informacoes_complementares	string	补充信息（写入 `infAdic.infCpl`）
informacoes_fisco	string	税务机关信息（写入 `infAdic.infAdFisco`）

Body — `cliente`（对象，必填）

对于国内操作（transaction_type 0 或 1）: cpf 或 cnpj、name、endereco、bairro（最少 2 个字符）、city、uf 和 cep 为必填。对于进口/出口（transaction_type 2 或 3）: 仅 name 为必填。

字段	类型	说明
cpf	string	客户 CPF（cnpj 的替代）
cnpj	string	客户 CNPJ（cpf 的替代）
ie	string	州注册号（Inscrição Estadual）
name *	string	公司名称 / 客户姓名
endereco	string	地址（街道）
complemento	string	地址补充
numero	string	地址门牌号
bairro	string	街区（国内操作最少 2 个字符）
city	string	城市
uf	string	州（UF）— 会被从 CEP 解析出的 UF 覆盖
cep	string	邮政编码（验证 UF 和城市）
telefone	string	电话
email	string	电子邮件
id_estrangeiro	string	外国 ID（用于进口/出口）
c_pais	int	BACEN 国家代码。默认: `1058`（巴西）
x_pais	string	国家名称。默认: `"BRASIL"`

Body — `products[]`（数组，至少 1 项）

每个产品需要税务信息: 通过 category_id（引用预注册的税务类别），或者 impostos 对象（内联配置），二选其一。

字段	类型	说明
codigo	string	产品内部代码
name *	string	产品描述（CJK 字符会被剔除）
ncm *	string	8 位 NCM
cest	string	CEST 代码（适用 ICMS-ST 时必填）
gtin	string	GTIN / 条形码
gtin_tributavel	string	计税单位 GTIN
count *	decimal	数量
unit *	string	商业单位（如: "UN"、"KG"、"MT"）
unit_price *	decimal	单价
total_price *	decimal	项目总价
discount_price	decimal	项目折扣
price_includes_ipi	boolean	本商品单价是否已含 IPI，覆盖顶层设置；不传 = 跟随整票
origem *	int	商品来源 (`0`=国产, `1`=进口—直接进口, 等)
indicador_total *	int	是否计入 NF-e 总额: `0`=否, `1`=是
category_id	string	预注册的税务类别 ID（若不传 `impostos` 则必填）
impostos	object	内联税务配置（`category_id` 的替代）。结构见下。旧字段名 `tax_info` 仍兼容。
disable_difal	boolean	禁用此项的 DIFAL 计算
desconta_icms_pis_cofins	boolean	算 PIS/COFINS 前先减去 ICMS，按（金额 − ICMS）计税（巴西现行标准）；默认 false 不减，税额会偏高
ii	object	进口税 — CFOP 3.xxx 时必填。结构见下
import_declarations	array	进口报关单（DI） — 当 `transaction_type="2"` 时必填。结构见下
nItemPed	int	采购订单项目 (I61)。从根 `id` 取得的 `xPed` 所引用订单内的项目顺序号。有效范围: 1–999999。默认: 省略。

Body — `products[].impostos`

字段	类型	说明
industria	string	基准行业/税率（别名: `aliquota`）
icms
icms.codigo_cfop	string	CFOP
icms.situacao_tributaria	string	ICMS 的 CST/CSOSN
icms.tipo_pessoa	string	人员类型（PF/PJ）
icms.codigo_beneficio_fiscal	string	cBenef（税收优惠代码）
icms.aliquota	string	自有 ICMS 税率（%）（CST 00、10、20、51、70、90）。留空则系统按州际/州内税率表推算
icms.aliquota_reducao	string	自有 ICMS 计税基础减免百分比（CST 20、51、70、90）
icms.aliquota_st	string	目的州 ICMS-ST 税率（%）（CST 10、30、70、90）
icms.aliquota_reducao_st	string	ICMS-ST 计税基础减免百分比（CST 10、30、70、90）
icms.aliquota_mva	string	MVA/IVA-ST（%）（CST 10、30、70、90）
icms.aliquota_fcp	string	自有 FCP 税率（%）— 在 ICMS 组中输出 pFCP/vFCP（CST 00、10、20、51、70、90）
icms.aliquota_fcp_st	string	FCP-ST 税率（%）（CST 10、30、70、90）
icms.aliquota_fcp_uf_dest	string	目的州的 FCP 税率 %（XML 的 pFCPUFDest）。不传则用 aliquota_fcp
icms.aliquota_uf_dest	string	目的州的 ICMS 税率 %。一般不用传——平台按州维护了标准税率。只有该商品在目的州适用差异化税率（饮料、烟草、电力等）时才需要覆盖。填目的州、不是发货州
icms.difal_desconta_icms_inter	boolean	DIFAL 基数先减掉已缴的州际 ICMS，对应州法规里的「com exclusão」。怎么选见本页「跨州开票：DIFAL 基数怎么传」
icms.difal_base_por_dentro	boolean	DIFAL 基数按「税含在价内」放大，对应州法规里的「base dupla」。怎么选见本页「跨州开票：DIFAL 基数怎么传」
icms.v_bc_uf_dest	string	自己已经算好 DIFAL 基数时，直接传这个金额 R$。传了它，difal_desconta_icms_inter 与 difal_base_por_dentro 都不再生效
icms.aliquota_credito	string	Simples Nacional 信用税率（%）（CSOSN 101、201、900）
icms.aliquota_diferimento	string	ICMS 递延百分比（CST 51）
icms.motivo_desoneracao	string	ICMS 免税理由代码（CST 20、40、41、50、90）
icms.ad_rem_icms	string	ICMS 单一环节 — 从量税率（雷亚尔/单位）（CST 02、15、53）
icms.ad_rem_icms_ret	string	ICMS 单一环节 — 代扣从量税（雷亚尔/单位）（CST 15、61）
icms.p_dif_mono	string	ICMS 单一环节 — 递延百分比（CST 53）
icms.q_bc_mono	string	ICMS 单一环节 — 计税数量（升/千克）。留空则使用项目数量（CST 02、15、53）
icms.valor_desoneracao	string	ICMS 免征金额（雷亚尔）— 输出 vICMSDeson（CST 40、41、50、90）
icms.v_bc_st_ret	string	上一环节已代扣 ICMS-ST 的计税基础（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
icms.p_st	string	最终消费者承担的税率（%）（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
icms.v_icms_st_ret	string	上一环节已代扣的 ICMS-ST 金额（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
icms.v_icms_substituto	string	替代纳税人自身的 ICMS 金额（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
icms.v_bc_fcp_st_ret	string	按 ST 代扣 FCP 的计税基础（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
icms.p_fcp_st_ret	string	按 ST 代扣的 FCP 税率（%）（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
icms.v_fcp_st_ret	string	按 ST 代扣的 FCP 金额（由调用方提供，不由系统计算 — CST 60、CSOSN 500）
ipi
ipi.codigo_enquadramento	string	IPI 法律分类代码
ipi.situacao_tributaria	string	IPI 的 CST
ipi.aliquota	string	IPI 税率
ipi.valor_unidade	string	IPI 按数量计税 — 单价（雷亚尔/单位）。仅在没有百分比税率时使用；填写了 `aliquota` 时以百分比优先（CST 00、50、49、99）
ipi.tipo_pessoa	string	人员类型
pis
pis.situacao_tributaria	string	PIS 的 CST
pis.aliquota	string	PIS 税率
pis.valor_unidade	string	PIS 按数量计税 — 单价（雷亚尔/单位）。vPIS = 数量 × 单价（CST 03 及其他按数量计税方式）
pis.tipo_pessoa	string	人员类型
cofins
cofins.situacao_tributaria	string	COFINS 的 CST
cofins.aliquota	string	COFINS 税率
cofins.valor_unidade	string	COFINS 按数量计税 — 单价（雷亚尔/单位）。vCOFINS = 数量 × 单价（CST 03 及其他按数量计税方式）
cofins.tipo_pessoa	string	人员类型
is（选择税）
is.cenario	string	IS 场景
is.situacao_tributaria	string	IS 的 CST
is.aliquota	string	IS 税率
is.tipo_pessoa	string	人员类型
ibs_cbs（税制改革）
ibs_cbs.situacao_tributaria	string	IBS/CBS 的 CST
ibs_cbs.tipo_pessoa	string	人员类型
ibs_cbs.classificacao_tributaria	string	IBS/CBS 税务分类
ibs_cbs.p_ibs_uf	string	IBS州税率（%）（可选；留空则使用过渡期默认值0.10（2026年））。支持点或逗号
ibs_cbs.p_ibs_mun	string	IBS市级税率（%）（可选；2026年默认0）
ibs_cbs.p_cbs	string	CBS税率（%）（可选；2026年默认0.90）
ibs_cbs.p_red_aliq	string	税率减免百分比（CST 011、200、515）
ibs_cbs.p_dif	string	递延百分比（CST 510、515）
ibs_cbs.p_red_bc	string	计税基础减免百分比（CST 222）
ibs_cbs.proporcao	string	操作比例（%）（CST 221）
ibs_cbs.aliquota_cbs_mono	string	CBS 单一环节 — 按计税基础的百分比税率；优先于 `valor_unidade_cbs`（CST 620）
ibs_cbs.aliquota_ibs_mono	string	IBS 单一环节 — 按计税基础的百分比税率；优先于 `valor_unidade_ibs`（CST 620）
ibs_cbs.valor_unidade_cbs	string	CBS 单一环节 — 从量金额（雷亚尔/单位）；仅在没有百分比税率时使用（CST 620）
ibs_cbs.valor_unidade_ibs	string	IBS 单一环节 — 从量金额（雷亚尔/单位）；仅在没有百分比税率时使用（CST 620）
ibs_cbs.valor_deducao_legal	string	计税基础的法定扣除额（雷亚尔）（CST 830）
difal
difal.disable_difal	boolean	禁用项目的 DIFAL（产品级 `disable_difal` 的替代）

跨州开票：DIFAL 基数怎么传

只有「跨州 + 卖给个人（非纳税人）」才需要看这一节，州内票和 B2B 票不用管。

第一步：按收货人所在州查下表

收货人所在州	除 aliquota、aliquota_fcp 外还要传
PE、RJ	不用再传
SE	只传 `difal_base_por_dentro: true`
其余 24 个州 AC AL AM AP BA CE DF ES GO MA MG MS MT PA PB PI PR RN RO RR RS SC SP TO	`difal_desconta_icms_inter: true` `difal_base_por_dentro: true`

请注意：DIFAL 基数口径直接决定应缴税额，选择不当会造成少缴（可能面临补税与滞纳金）或多缴。上表依据各州现行主流做法整理，仅供参考——州法规会调整，特定商品也可能适用差异化规则。接入前请与贵司会计或税务顾问确认目的州的适用口径。不确定时可将 difal_desconta_icms_inter 与 difal_base_por_dentro 均不传，系统按发票金额计算，此为最保守的口径。

第二步：按场景取用请求示例

卖到 RJ — 无需 difal_desconta_icms_inter、difal_base_por_dentro（FECP 2%）

{
  "icms": { "codigo_cfop": "6102", "situacao_tributaria": "00",
            "aliquota": "4", "aliquota_fcp": "2" }
}

卖到 AL — difal_desconta_icms_inter 与 difal_base_por_dentro 均传 true（FECP 1%）

{
  "icms": { "codigo_cfop": "6102", "situacao_tributaria": "00",
            "aliquota": "4", "aliquota_fcp": "1",
            "difal_desconta_icms_inter": true,
            "difal_base_por_dentro": true }
}

若贵司系统已自行计算 DIFAL 基数，可直接传入 v_bc_uf_dest；此时 difal_desconta_icms_inter 与 difal_base_por_dentro 不再生效

{
  "icms": { "aliquota": "4", "aliquota_fcp": "1", "v_bc_uf_dest": "122.29" }
}

这三种传法的差别

传法	DIFAL 基数	应缴 DIFAL
difal_desconta_icms_inter、difal_base_por_dentro 均不传	100.00	16.50
两者均传 true	122.29	21.07
传 v_bc_uf_dest=150	150.00	26.75

以发票 100.00、已缴州际 ICMS 4.00、目的州税率 20.5%、FECP 1% 计算。

为什么州与州不一样（不影响接入，可跳过）

ICMS 是价内税，税本身也算在价格里。部分州要求算 DIFAL 时把这笔税还原进计税基数（法规里写作 base dupla），并先扣掉已缴的州际 ICMS（com exclusão）；另一些州直接按发票金额计算（base única）。difal_desconta_icms_inter 与 difal_base_por_dentro 分别对应这两个动作。目的州税率不用传，平台已按州维护。

Body — `products[].ii`（进口税）

字段	类型	说明
vBC	decimal	II 计算基础
vDespAdu	decimal	海关费用
vII	decimal	II 金额
vIOF	decimal	IOF 金额

Body — `products[].import_declarations[]`

字段	类型	说明
nDI	string	DI 编号
dDI	string (date)	DI 日期
xLocDesemb	string	清关地点
UFDesemb	string	清关州
dDesemb	string (date)	清关日期
cExportador	string	出口商代码
tpViaTransp	int	国际运输方式
tpIntermedio	int	中介类型
vAFRMM	decimal	AFRMM 金额
additions	array	DI 附加项（字段: `nAdicao`、`nSeqAdic`、`cFabricante`、`vDescDI`、`nDraw`）

Body — `shipping_address` / `delivery_address`（对象，可选）

shipping_address 是取货地点（物理出发地，与开票方不同时使用）。delivery_address 是配送地点（物理目的地，与客户不同时使用）。指定时两个对象均需: cpf 或 cnpj、name、endereco、bairro（最少 2 个字符）、city、uf、cep。两个对象结构相同。

字段	类型	说明
cpf	string	CPF（cnpj 的替代）
cnpj	string	CNPJ（cpf 的替代）
ie	string	州注册号
name *	string	公司名称 / 姓名
endereco *	string	地址
complemento	string	地址补充
number	string	门牌号（注意: 字段名为 `number`，不是 `numero`）
bairro *	string	街区
city *	string	城市
uf *	string	州
cep *	string	邮政编码
telefone	string	电话
email	string	电子邮件

Body — `transportation`（对象，可选）

若 transportation 省略，系统假定 transport_mode="9"（无运费）。

字段	类型	说明
transport_mode	string	运费模式: `"0"`=开票方承担, `"1"`=收件方承担, `"2"`=第三方承担, `"3"`=发件人自行运输, `"4"`=收件人自行运输, `"9"`=无运费
freight_amount	decimal	运费总额
carrier_info — 承运商
carrier_info.cpf	string	承运商 CPF（cnpj 的替代）
carrier_info.cnpj	string	承运商 CNPJ（cpf 的替代）
carrier_info.ie	string	州注册号
carrier_info.name	string	公司名称
carrier_info.endereco	string	地址
carrier_info.city	string	城市
carrier_info.uf	string	州
carrier_info.cep	string	邮政编码
vehicle_info — 车辆
vehicle_info.plate	string	车牌
vehicle_info.uf	string	车牌州
vehicle_info.rntc	string	RNTC（国家货物承运商登记）
trailer_info — 拖车（与 vehicle_info 结构相同）
trailer_info.plate	string	拖车车牌
trailer_info.uf	string	州
trailer_info.rntc	string	RNTC
packages[] — 包裹
packages[].qty	int	数量
packages[].gross_weight	decimal	毛重
packages[].net_weight	decimal	净重
packages[].packaging_type	string	包装类型
packages[].number	string	编号
packages[].mark	string	标记
packages[].seals	array<string>	封条
transport_tax_retention_info — 运费 ICMS 代扣
transport_tax_retention_info.freight_service_amount	decimal	运输服务金额
transport_tax_retention_info.tax_base	decimal	代扣计算基础
transport_tax_retention_info.tax_rate	decimal	代扣税率
transport_tax_retention_info.cfop	string	CFOP
transport_tax_retention_info.cep	string	邮政编码

Body — `pag_info[]`（数组，可选）

省略时系统假定 [{ "payment_method": "01", "payment_indicator": "0" }]（现金、一次性付清）。

字段	类型	说明
payment_method *	string	支付方式: `"01"`=现金, `"02"`=支票, `"03"`=信用卡, `"04"`=借记卡, `"05"`=店内信用, `"10"`=食品券, `"11"`=餐券, `"15"`=银行账单, `"17"`=PIX, `"90"`=无支付, `"99"`=其他
payment_indicator *	string	指示符: `"0"`=一次性付清, `"1"`=分期
payment_value	decimal	支付金额
card_info — 卡片信息（用于 payment_method 03/04）
card_info.integration_type *	string	终端集成类型（指定 `card_info` 时必填）
card_info.brand_code *	string	卡品牌（指定 `card_info` 时必填）
card_info.acquirer_cnpj	string	收单方 CNPJ
card_info.authorization_code	string	授权码

* 必填字段。

返回字段（`data`）

字段	类型	说明
uuid	string	NF-e 内部标识符。用于后续调用（`/api/invoice/get_detail`、`/refresh`、`/cancel`）
status	string	状态：`"Success"`（已授权）、`"Failed"`（被拒/失败）、`"Processing"`（处理中）、`"Canceled"`（已取消）
motivo	string	与 `cStat` 对应的税务局官方消息（PT / 中文双语格式）
nfe	int	已开具的 NF-e 号码
serie	int	NF-e 系列号
chave	string	44 位访问密钥（未授权时为空）
modelo	string	单据模型：`"nfe"`
epec	boolean	是否为 EPEC 应急开具
xml	string	已授权 XML 的 URL。DANFE（PDF）及其他格式请通过 `/api/invoice/get_detail` 获取

返回 — 拒绝 / 错误

当税务局拒绝该发票时，success 为 false，data.motivo 给出原因；chave 返回为空。字段校验错误（提交税务局之前）返回 success: false，消息位于 message，且没有 data 对象。

        {
          "success": false,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "status": "Failed",
            "motivo": "Rejeição 226: Código da UF do Emitente diverge da UF autorizadora / 拒绝 226: 发件人所在州代码与授权州不一致",
            "nfe": 100,
            "serie": 1,
            "chave": "",
            "modelo": "nfe",
            "epec": false,
            "xml": ""
          }
        }

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/invoice/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "nature_of_operation": "Venda de mercadoria",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "cliente": {
            "cpf": "12345678909",
            "name": "Cliente Exemplo",
            "endereco": "Rua Exemplo",
            "numero": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000",
            "email": "cliente@exemplo.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Produto Exemplo",
              "ncm": "85176277",
              "count": 2,
              "unit": "matriz",
              "unit_price": 150.00,
              "total_price": 300.00,
              "category_id": "SEU_CATEGORY_ID",
              "origem": 0,
              "indicador_total": 1
            }
          ],
          "pag_info": [
            { "payment_method": "01", "payment_indicator": "0", "payment_value": 300.00 }
          ]
        }

        {
          "id": "PEDIDO-2026-0001",
          "nature_of_operation": "Venda de mercadoria",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "finalidade": "1",
          "ref_nfe_chave": "",
          "is_reopen": false,
          "dh_sai_ent": "",
          "total_discount_amount": 0.0,
          "troco": 0.0,
          "seguro": 0.0,
          "outras_despesas": 0.0,
          "price_includes_ipi": false,
          "ind_final": "1",
          "ind_pres": "9",
          "informacoes_complementares": "Entrega via transportadora",
          "informacoes_fisco": "ICMS recolhido conforme legislação",
          "cliente": {
            "cpf": "",
            "cnpj": "12345678000199",
            "ie": "123456789",
            "name": "Cliente Exemplo LTDA",
            "endereco": "Av. Paulista",
            "numero": "1000",
            "complemento": "Sala 200",
            "bairro": "Bela Vista",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "telefone": "11999998888",
            "email": "cliente@exemplo.com",
            "id_estrangeiro": "",
            "c_pais": 1058,
            "x_pais": "BRASIL"
          },
          "shipping_address": {
            "cnpj": "98765432000111",
            "name": "Depósito Origem LTDA",
            "ie": "987654321",
            "endereco": "Rua do Depósito",
            "number": "50",
            "complemento": "Galpão 3",
            "bairro": "Industrial",
            "city": "Guarulhos",
            "uf": "SP",
            "cep": "07000000",
            "telefone": "11988887777",
            "email": "deposito@exemplo.com"
          },
          "delivery_address": {
            "cnpj": "12345678000199",
            "name": "Cliente Exemplo LTDA",
            "ie": "123456789",
            "endereco": "Rua de Entrega",
            "number": "25",
            "complemento": "Loja 2",
            "bairro": "Centro",
            "city": "Campinas",
            "uf": "SP",
            "cep": "13010000",
            "telefone": "11977776666",
            "email": "entrega@exemplo.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Notebook Dell",
              "ncm": "84713012",
              "cest": "",
              "gtin": "7891234567890",
              "gtin_tributavel": "7891234567890",
              "count": 2,
              "unit": "matriz",
              "unit_price": 3500.0,
              "total_price": 7000.0,
              "discount_price": 0.0,
              "origem": 0,
              "indicador_total": 1,
              "category_id": "TF00001",
              "nItemPed": 1,
              "price_includes_ipi": false,
              "desconta_icms_pis_cofins": false,
              "disable_difal": false
            },
            {
              "codigo": "PROD002",
              "name": "Mouse sem fio",
              "ncm": "84716053",
              "count": 5,
              "unit": "matriz",
              "unit_price": 80.0,
              "total_price": 400.0,
              "origem": 0,
              "indicador_total": 1,
              "nItemPed": 2,
              "impostos": {
                "icms": {
                  "codigo_cfop": "5102",
                  "situacao_tributaria": "00",
                  "industria": "",
                  "tipo_pessoa": "juridica",
                  "codigo_beneficio_fiscal": "",
                  "aliquota": "18",
                  "aliquota_fcp": "0",
                  "aliquota_reducao": "0",
                  "aliquota_st": "0",
                  "aliquota_reducao_st": "0",
                  "aliquota_mva": "0",
                  "aliquota_fcp_st": "0",
                  "aliquota_credito": "0",
                  "motivo_desoneracao": "",
                  "valor_desoneracao": "0",
                  "aliquota_uf_dest": "20.5",
                  "difal_desconta_icms_inter": true,
                  "difal_base_por_dentro": true,
                  "v_bc_uf_dest": ""
                },
                "ipi": {
                  "codigo_enquadramento": "999",
                  "situacao_tributaria": "99",
                  "aliquota": "0.00",
                  "tipo_pessoa": "juridica"
                },
                "pis": {
                  "situacao_tributaria": "01",
                  "aliquota": "0.65",
                  "tipo_pessoa": "juridica"
                },
                "cofins": {
                  "situacao_tributaria": "01",
                  "aliquota": "3.00",
                  "tipo_pessoa": "juridica"
                },
                "ibs_cbs": {
                  "situacao_tributaria": "000",
                  "tipo_pessoa": "juridica",
                  "classificacao_tributaria": "000001",
                  "p_ibs_uf": "0.1",
                  "p_ibs_mun": "0",
                  "p_cbs": "0.9"
                },
                "is": {},
                "difal": {
                  "disable_difal": false
                }
              },
              "discount_price": 0.0,
              "price_includes_ipi": false,
              "desconta_icms_pis_cofins": true
            }
          ],
          "transportation": {
            "transport_mode": "1",
            "freight_amount": 150.0,
            "carrier_info": {
              "cnpj": "11222333000144",
              "ie": "112223334",
              "name": "Transportadora Exemplo LTDA",
              "endereco": "Rod. BR-101, km 50",
              "city": "Santos",
              "uf": "SP",
              "cep": "11000000"
            },
            "vehicle_info": {
              "plate": "ABC1D23",
              "uf": "SP",
              "rntc": "12345"
            },
            "trailer_info": {
              "plate": "DEF4G56",
              "uf": "SP",
              "rntc": "67890"
            },
            "packages": [
              {
                "qty": 3,
                "gross_weight": 12.5,
                "net_weight": 11.0,
                "packaging_type": "CAIXA",
                "number": "001-003",
                "mark": "FRAGIL",
                "seals": [
                  "LACRE001",
                  "LACRE002"
                ]
              }
            ],
            "transport_tax_retention_info": {
              "freight_service_amount": 150.0,
              "tax_base": 150.0,
              "tax_rate": 12.0,
              "cfop": "5932",
              "cep": "11000000"
            }
          },
          "pag_info": [
            {
              "payment_indicator": "1",
              "payment_method": "03",
              "payment_value": 7400.0,
              "card_info": {
                "integration_type": "1",
                "brand_code": "01",
                "acquirer_cnpj": "01234567000189",
                "authorization_code": "AUTH987654"
              }
            }
          ]
        }

        {
          "success": true,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "status": "Success",
            "motivo": "Autorizado o uso da NF-e",
            "nfe": 100,
            "serie": 1,
            "chave": "35260112345678000199550010000001001000000017",
            "modelo": "nfe",
            "epec": false,
            "xml": "https://oss.example.com/.../chave.xml"
          }
        }

GET/api/invoice/get_list

NF-e 列表（分页）

分页列出公司的 NF-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"`（已取消）、`"Voided"`（已作废）、`"Processing"`（处理中）、`"InvoicingFailed"`（开票失败）、`"Failed"`（失败）、`"Contingencia"`（离线应急）、`"Unknown"`（未知））

* 必填字段。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X GET "https://api.tffiscal.com/api/invoice/get_list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN"

GET /api/invoice/get_list?page=1&page_size=20&status=Success

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35210112345678901234567890123456789012345678",
                "status": "Success",
                "create": "2024-01-10T10:30:00Z",
                "issue_time": "2024-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

GET/api/invoice/get_detail

查询 NF-e 详情

通过 UUID 或访问密钥（chave）返回特定 NF-e 的详情。包括 XML URL、DANFE URL（完整、简化、标签）和元数据。

必需请求头

请求头	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名（path 包含查询字符串）
timestamp	string	秒级 Unix 时间戳

查询字符串

参数	类型	说明
uuid	string	NF-e UUID
chave	string	NF-e 访问密钥（44 位数字）

请提供 uuid 或 chave（至少一个）。若同时发送，以 uuid 为准。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X GET "https://api.tffiscal.com/api/invoice/get_detail" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN"

GET /api/invoice/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9
GET /api/invoice/get_detail?chave=35210112345678901234567890123456789012345678

        {
          "success": true,
          "data": {
            "id": "pedido-2024-0001",
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234567890123456789012345678",
            "serie": 1,
            "number": 100,
            "status": "Success",
            "total_price": 300.00,
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave.pdf",
            "danfe_simples": "https://oss.example.com/.../chave_simplie.pdf",
            "danfe_etiqueta": "https://oss.example.com/.../chave_etiqueta.pdf",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST/api/invoice/refresh

更新发票状态

查询税务局上 NF-e 的当前状态并更新本地记录。当开票卡在处理中或应急状态时使用。

必需请求头

请求头	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
uuid *	string	要查询的 NF-e 的 UUID

* 必填字段。

POST/api/invoice/cancel

取消发票

取消已授权的 NF-e。发送给税务局的理由是固定的: "Erro no preenchimento da nota fiscal." — 无法通过载荷配置。

必需请求头

请求头	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
uuid *	string	要取消的 NF-e 的 UUID（由 `/api/invoice/create` 返回的内部标识符）

* 必填字段。

返回字段（`data`）

字段	类型	说明
motivo	string	税务局确认取消的官方消息
status	string	状态：`"Canceled"`（已取消）
nfe	int	已取消的 NF-e 号码
serie	int	NF-e 系列号
chave	string	44 位访问密钥
modelo	string	单据模型：`"nfe"`
epec	boolean	是否为 EPEC 应急开具
xml	string	取消事件 XML 的 URL

返回 — 错误

失败时返回 success: false，税务局消息位于 message，且没有 data 对象。当缺少 uuid、证书无效，或税务局拒绝取消（如超过期限、发票已取消）时发生。

        {
          "success": false,
          "message": "Rejeição: NF-e já está cancelada na base de dados da 税务局 "
        }

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/invoice/cancel" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

        {
          "success": true,
          "data": {
            "motivo": "Cancelamento de NF-e homologado",
            "status": "Canceled",
            "nfe": 100,
            "serie": 1,
            "chave": "35260112345678000199550010000001001000000017",
            "modelo": "nfe",
            "epec": false,
            "xml": "https://oss.example.com/.../chave-cancelamento.xml"
          }
        }

POST/api/invoice/invalid

作废编号范围

作废一段未授权的 NF-e 编号范围（不要与取消混淆 — 取消适用于已授权的发票）。该操作在税务局上记录，不可撤销。

必需请求头

请求头	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
modelo *	string	文档型号: `"55"`=NF-e, `"65"`=NFC-e。（注意: 字段名为 `modelo`，不是 `model`）
ambiente *	string	`"1"`=生产, `"2"`=测试
serie *	int	要作废的编号系列
start_number *	int	范围起始编号
end_number *	int	范围结束编号
motivo *	string	作废理由（税务局要求至少 15 个字符）

* 必填字段。

返回字段（`data`）

字段	类型	说明
uuid	string	作废记录的内部标识符
xml	string	税务局授权的作废 XML 的 URL

返回 — 错误

失败时返回 success: false，税务局消息位于 message，且没有 data 对象。当缺少必填字段、证书无效，或税务局拒绝作废（如号段已作废）时发生。

        {
          "success": false,
          "message": "Rejeição: Faixa de numeração já inutilizada"
        }

POST/api/invoice/get_danfe

获取 NF-e DANFE

返回 NF-e DANFE 的三个 URL:完整 DANFE(PDF)、简化 DANFE 的 PDF(小票格式)和简化 DANFE 的 PNG(标签图片)。PDF 按需从授权 XML 生成,并缓存在 OSS。后续调用时,如果发票状态未更改,则返回现有缓存;如果状态已更改(例如发票被取消),则重新生成 PDF。

必需请求头

请求头	类型	说明
token	string	发行企业 token
sign	string	MD5 签名:`MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳(秒,5 分钟窗口)

Body

字段	类型	说明
uuid ⚠	string	NF-e 内部 UUID(由 `/api/invoice/create` 返回)
chave ⚠	string	NF-e 访问密钥(44 位)

⚠ uuid 或 chave 二选一,必填。

响应字段

字段	类型	说明
danfe	string	完整 DANFE PDF 的 URL(A4 格式)
danfe_simples	string	简化 DANFE PDF 的 URL(小票格式)
danfe_simples_png	string	简化 DANFE PNG(标签图片)的 URL

错误响应

消息	原因
uuid/chave不能为空	`uuid` 和 `chave` 都未发送
发票不存在	未找到该 token 用户的发票,或缺少授权 XML
发票详情不存在	未找到发票详情(带协议)
获取PDF失败:<原因>	从 XML 生成 PDF 失败

POST/api/invoice/get_xml

批量导出 NF-e

为用户发票启动异步批量导出任务,按时间段和状态过滤。可生成 Excel 表格(仅元数据)或包含 XML 的 ZIP 包。第一次调用创建任务并返回 status: "Processing";使用相同参数的后续调用返回进度,直到 status: "Success" 时 url 字段包含下载链接。

必需请求头

请求头	类型	说明
token	string	发行企业 token
sign	string	MD5 签名
timestamp	string	Unix 时间戳(秒)

Body

字段	类型	说明
type *	string	输出格式:`"excel"`(元数据表格)或其他值(如 `"xml"`)— XML 的 ZIP
status	string	按发票状态过滤(如 `"Success"`、`"Canceled"`、`"Voided"`)。`type=excel` 时内部转为小写
month	int	月份(1–12)。如提供,覆盖 `start_create_time`/`end_create_time`;使用 `America/Sao_Paulo` 时区和当前年份(若月份在未来则使用上一年)
start_create_time	long	时间段开始,包含(Unix 时间戳,毫秒)。取该值的 UTC 日期时间,按巴西利亚时间解释:请传当天的 UTC 零点,如 `Date.UTC(2026, 7, 1)` = `1785542400000` 表示巴西时间 2026-08-01 00:00
end_create_time	long	时间段结束,不含(同样规则)。请传所需最后一天的下一天的 UTC 零点:导出 2026 年 8 月整月,传 `Date.UTC(2026, 8, 1)` = `1788220800000`

* 必填字段。

时间范围:start_create_time/end_create_time 按其 UTC 日期时间读取,并解释为巴西利亚时间(UTC−3,无夏令时)。请传日历日的 UTC 零点:开始包含,结束不含。示例,导出 2026-08-29 至 2026-09-01 全天:start_create_time = 1787961600000(2026-08-29T00:00Z),end_create_time = 1788307200000(2026-09-02T00:00Z)。不要在该值上加 3 小时。

响应字段

字段	类型	说明
status	string	任务执行时为 `"Processing"`,文件准备就绪时为 `"Success"`
progress_count	int	已处理的发票数量
total_count	int	待处理发票总数
url	string	最终文件下载 URL(`status = Processing` 时为空字符串)

幂等性: 任务通过参数哈希(uid + token + 时间段 + status + type)去重。使用相同参数的重复调用返回同一任务的进度,不会触发新的执行。

错误响应

消息	原因
发票类型字段不能为空	`type` 缺失

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/invoice/get_xml" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "type": "xml",
          "status": "Success",
          "start_create_time": 1787961600000,
          "end_create_time": 1788307200000
        }

        {
          "success": true,
          "data": {
            "status": "Processing",
            "progress_count": 120,
            "total_count": 543,
            "url": ""
          }
        }

        {
          "success": true,
          "data": {
            "status": "Success",
            "progress_count": 543,
            "total_count": 543,
            "url": "https://storage.../exports/uid/<sn>.zip"
          }
        }

POST/api/invoice/consultar_status

查询 NF-e 状态

通过 NfeConsultaProtocolo4 服务,使用访问密钥(44 位)直接在税务局查询 NF-e 或 NFC-e 的当前状态。适用于 token 公司开具的自有发票以及通过 DistDFe 捕获的第三方发票。模型(NF-e/NFC-e)从密钥的 20-21 位自动检测。

必需请求头

请求头	类型	说明
token	string	企业 token(其证书将用于查询)
sign	string	MD5 签名:`MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳(秒,5 分钟窗口)

Body

字段	类型	说明
chave *	string	访问密钥(44 位数字)。发行者 UF 从 0-1 位置提取;模型从 20-21 位置提取(`55`=NF-e,`65`=NFC-e)。
ambiente	string	查询哪个环境:`1`=正式、`2`=测试(也接受 `producao`/`homologacao`)。不传时按该票开票时所用的环境自动判断;本地查不到这张票则按正式环境查。正式与测试是两套独立数据库,用测试环境开的票去查正式环境必然返回 217。

* 必填字段。

响应字段

字段	类型	说明
chave	string	查询的访问密钥
status	string	规范化状态(见下表)
cstat	int	税务局原始 `cStat` 代码
motivo	string	税务局原始 `xMotivo` 消息

状态映射

`status`	税务局 cStat	含义
autorizada	`100`, `150`	NF-e 已授权使用
cancelada	`101`, `151`	已取消(即使 `cStat=100`,如果有关联的取消事件也返回)
denegada	`110`, `301`, `302`	税务局拒绝使用
inutilizada	`102`	号码已作废(号码范围)
nao_encontrada	`217`	NF-e 在税务局数据库中不存在
desconhecido	其他	未映射的 cStat — 查看原始 `cstat` 和 `motivo`

错误响应

消息	原因
chave inválida: deve ter 44 dígitos	密钥缺失、大小非 44 或包含非数字字符
empresa não possui certificado configurado	token 公司未注册 `cert_file`
税务局 retornou resposta vazia	税务局未返回响应(超时、宕机)
erro ao consultar 税务局: <详情>	调用服务时异常(无效 XML、超时、证书过期等)

POST/api/invoice/return

开具退货 NF-e

从原始 NF-e 开具退货 NF-e（型号 55，用途 4）。支持两种模式：全额退货（通过 uuid 或 chave 引用原始发票 — 退货票为原始 NF-e 的完整克隆）或 部分／自定义退货（在 body 根级直接发送 chave + 发票完整字段，与 /api/invoice/create 结构相同）。

必需请求头

请求头	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body — 始终读根级的字段

字段	类型	说明
uuid	string	原发票的 UUID（整票退货；与 `chave` 至少传一个）。格式是 36 位带横线的 GUID，不是 24 位的 `_id`。传了 uuid 且未传 `return_detail` 时按整票克隆；同时传了 `return_detail` 则按部分退货
chave	string	原始 NF-e 的 44 位访问密钥（部分退货必填；全额退货时作为 `uuid` 的替代）
return_detail	object	部分退货的明细对象。部分退货的字段必须全部放在本对象内（cliente、products、transaction_type、model、issuance_type、ambiente、id）；散在根级会直接报错。`chave`、`cfop`、`natureza_operacao` 始终读根级，根级的 `natureza_operacao` 会覆盖对象内的同名字段
cfop *	string	退货 CFOP。退货票是入库（`tpNF=0`），须用入库 CFOP：州内 `"1202"`、`"1411"`，跨州 `"2202"`、`"2411"`。不传时按州内/跨州自动取 `"1202"`/`"2202"`。传出库 CFOP（`"5202"`、`"6202"` 等）会与 tpNF 冲突，被税务局拒
natureza_operacao	string	操作性质（例如："Devolução de venda"）。接受别名：`nature_of_operation`

Body — `return_detail` 内的字段

以下字段全部放在 return_detail 对象内。放到请求根级不生效，接口会直接返回错误（不会静默改成整票退货）。

字段	类型	说明
transaction_type	string	交易类型。必填但取值无效：接口会无条件覆盖为入库（`tpNF=0`），传 `"0"` 或 `"1"` 结果相同，仅作占位
model	string	单据型号：`"55"`（部分退货必填）
issuance_type	string	开具类型：`"1"`=正常（部分退货必填）
ambiente	string	环境：`"1"`=生产，`"2"`=测试（部分退货必填）
id	string	订单号（退货去重键）。退货不走订单预留机制，重复保护完全依赖本字段：同一 `id` 已有退货票时直接返回原票，不重复开具。不传则无任何重复保护，同一笔退货可被反复开出，强烈建议传
total_discount_amount	number	整单折扣金额。默认 0
cliente	object	收件方数据，与 `/api/invoice/create` 结构相同（部分退货必填）。注意：地址门牌号字段是 `number`（英文），不是 `numero`。不传 `number` 时地址以 nro "S/N" 输出；IBGE 代码、城市和州由 `cep` 解析
products	array	退货商品，与 `/api/invoice/create` 结构相同（部分退货必填）。`codigo` 可选 — 缺省时 cProd 使用 `name` 税务信息可用 `category_id` 或 `impostos`，二选一 —— 原发票由其他服务商开具时用后者。
products[].n_item	int	该商品在原发票上的行号（1..990）。仅测试环境退货需要：此时退货票按商品行引用原票，而部分退货无法自行推断该行号（原票可能不在本平台）。不传则省略引用组，税务局返回 `Rejeição 321`。正式环境按票头引用，无需此字段

* 必填字段。uuid 或 chave 也必填（仅其中一个）。

退货时自动处理：支付固定为 90（无支付），pag_info 会被忽略；未传 natureza_operacao 时使用 "Devolução de Mercadoria"；商品税务信息（CST/CSOSN、PIS/COFINS、IPI、IBS/CBS）由 category_id 对应的税务分类按人员类型和场景解析；也可改用 impostos 直接在商品行内传税率，两者二选一。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/invoice/return" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "uuid": "4663a257-adf1-4561-971f-6aaffbd30ca8",
          "cfop": "1202",
          "natureza_operacao": "Devolução de venda"
        }

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "1202",
          "natureza_operacao": "Devolução parcial",
          "return_detail": {
            "id": "PED-2026-0001",
            "transaction_type": "1",
            "model": "55",
            "issuance_type": "1",
            "ambiente": "2",
            "total_discount_amount": 0,
            "cliente": {
              "cnpj": "12345678000199",
              "cpf": "",
              "ie": "111222333444",
              "name": "Fornecedor",
              "endereco": "Rua das Flores",
              "number": "1000",
              "complemento": "Sala 2",
              "bairro": "Centro",
              "city": "Sao Paulo",
              "uf": "SP",
              "cep": "01001000",
              "telefone": "1132294790",
              "email": "fornecedor@exemplo.com.br"
            },
            "products": [
              {
                "name": "Produto A",
                "codigo": "SKU-001",
                "ncm": "39269090",
                "cest": "",
                "gtin": "SEM GTIN",
                "gtin_tributavel": "SEM GTIN",
                "count": 1,
                "unit": "UN",
                "unit_price": 100,
                "total_price": 100,
                "discount_price": 0,
                "category_id": "68b1f0c2a1d4e5f6a7b8c9d0",
                "origem": 0,
                "indicador_total": 1,
                "price_includes_ipi": false,
                "n_item_ped": 1,
                "n_item": 1
              }
            ]
          }
        }

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "1202",
          "natureza_operacao": "Devolução parcial",
          "return_detail": {
            "id": "PED-2026-0002",
            "transaction_type": "1",
            "model": "55",
            "issuance_type": "1",
            "ambiente": "2",
            "cliente": {
              "cnpj": "12345678000199",
              "name": "Fornecedor",
              "endereco": "Rua das Flores",
              "number": "1000",
              "bairro": "Centro",
              "city": "Sao Paulo",
              "uf": "SP",
              "cep": "01001000"
            },
            "products": [
              {
                "name": "Produto A",
                "ncm": "39269090",
                "count": 1,
                "unit": "UN",
                "unit_price": 100,
                "total_price": 100,
                "origem": 0,
                "indicador_total": 1,
                "n_item": 1,
                "impostos": {
                  "icms": {
                    "codigo_cfop": "1202",
                    "situacao_tributaria": "102",
                    "tipo_pessoa": "juridica",
                    "aliquota": "18"
                  },
                  "ipi": {
                    "codigo_enquadramento": "999",
                    "situacao_tributaria": "99",
                    "aliquota": "0.00",
                    "tipo_pessoa": "juridica"
                  },
                  "pis": {
                    "situacao_tributaria": "07",
                    "aliquota": "0.00",
                    "tipo_pessoa": "juridica"
                  },
                  "cofins": {
                    "situacao_tributaria": "07",
                    "aliquota": "0.00",
                    "tipo_pessoa": "juridica"
                  }
                }
              }
            ]
          }
        }

说明

发票发行完整示例

带运输的完整示例

        {
          "nature_of_operation": "Venda de mercadoria",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "ind_final": "0",
          "ind_pres": "1",
          "cliente": {
            "cnpj": "12345678000199",
            "ie": "123456789",
            "name": "Empresa Cliente Ltda",
            "endereco": "Rua Exemplo",
            "number": "123",
            "complemento": "Sala 45",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01234567",
            "telefone": "11999999999",
            "email": "contato@empresa.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Smartphone XYZ",
              "ncm": "85171210",
              "cest": "2804000",
              "count": 2,
              "unit": "matriz",
              "unit_price": 1500.00,
              "total_price": 3000.00,
              "category_id": "YOUR_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1"
            }
          ],
          "transportation": {
            "transport_mode": "0",
            "freight_amount": 30.00,
            "carrier_info": {
              "cnpj": "12345678000188",
              "name": "Transportadora Expressa",
              "endereco": "Rua da Transportadora",
              "city": "São Paulo",
              "uf": "SP"
            },
            "vehicle_info": {
              "plate": "ABC1234",
              "uf": "SP",
              "rntc": "123456"
            },
            "packages": [
              {
                "qty": 1,
                "packaging_type": "CX",
                "gross_weight": 2.500,
                "net_weight": 2.000
              }
            ]
          },
          "shipping_address": {
            "cnpj": "12345678000199",
            "name": "Remetente Ltda",
            "endereco": "Rua do Remetente",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000"
          },
          "delivery_address": {
            "cnpj": "98765432000111",
            "name": "Destinatário Ltda",
            "endereco": "Rua do Destinatário",
            "number": "200",
            "bairro": "Centro",
            "city": "Rio de Janeiro",
            "uf": "RJ",
            "cep": "20040020"
          },
          "pag_info": [
            {
              "payment_method": "03",
              "payment_indicator": "0",
              "card_info": {
                "integration_type": "1",
                "brand_code": "01"
              }
            }
          ],
          "informacoes_complementares": "Sem informações adicionais",
          "informacoes_fisco": "ICMS recolhido conforme legislação"
        }

💡 信息： 此示例包括所有重要字段，包括运输、详细税务信息和支付。请根据您的具体需求调整值。

进口完整示例

        {
          "id": "PED-IMP-001",
          "nature_of_operation": "Importacao para revenda",
          "transaction_type": "2",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "finalidade": "1",
          "ind_final": "0",
          "ind_pres": "9",
          "cliente": {
            "name": "EXPORTADOR EXTERIOR CO LTD",
            "endereco": "Pudong District",
            "numero": "456",
            "city": "Shanghai",
            "id_estrangeiro": "CN-EXP-001",
            "c_pais": 1600,
            "x_pais": "CHINA"
          },
          "products": [
            {
              "name": "Fonte chaveada 12V 2A Quickfitting",
              "codigo": "123450000888",
              "ncm": "85044090",
              "count": 2,
              "unit": "PC",
              "unit_price": 0.25,
              "total_price": 0.50,
              "origem": 1,
              "indicador_total": "1",
              "category_id": "YOUR_CATEGORY_ID",
              "import_declarations": [
                {
                  "nDI": "2312345678",
                  "dDI": "2026-04-12",
                  "xLocDesemb": "PORTO DE SANTOS",
                  "UFDesemb": "SP",
                  "dDesemb": "2026-04-15",
                  "tpViaTransp": 1,
                  "vAFRMM": 0.01,
                  "tpIntermedio": 1,
                  "cExportador": "EXP-CN-001",
                  "additions": [
                    {
                      "nAdicao": 1,
                      "nSeqAdic": 1,
                      "cFabricante": "FAB-CN-001",
                      "vDescDI": 0,
                      "nDraw": ""
                    }
                  ]
                }
              ]
            },
            {
              "name": "Quick fitting MA",
              "codigo": "123450000157",
              "ncm": "85044090",
              "count": 2,
              "unit": "PC",
              "unit_price": 0.25,
              "total_price": 0.50,
              "origem": 1,
              "indicador_total": "1",
              "category_id": "YOUR_CATEGORY_ID",
              "ii": {
                "vBC": 0.50,
                "vDespAdu": 0.00,
                "vII": 0.00,
                "vIOF": 0.00
              },
              "import_declarations": [
                {
                  "nDI": "2312345678",
                  "dDI": "2026-04-12",
                  "xLocDesemb": "PORTO DE SANTOS",
                  "UFDesemb": "SP",
                  "dDesemb": "2026-04-15",
                  "tpViaTransp": 1,
                  "vAFRMM": 1.00,
                  "tpIntermedio": 1,
                  "cExportador": "EXP-CN-001",
                  "additions": [
                    {
                      "nAdicao": 1,
                      "nSeqAdic": 2,
                      "cFabricante": "FAB-CN-001",
                      "vDescDI": 0,
                      "nDraw": ""
                    }
                  ]
                }
              ]
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

💡 信息： NFe进口示例 (CFOP 3.xxx)。与国内 NFe 的差异：

transaction_type: "2" — 入库（进口）操作。
cliente 没有 cnpj/cpf/uf/cep；使用 id_estrangeiro、c_pais（BACEN 表 — 中国 = 1600）和 x_pais。
category_id 必须指向具有 CFOP 3.xxx 和与进口兼容的 CST/CSOSN 的税务类别。
产品 origem = 1（外国 — 直接进口）或 2（外国 — 在国内市场购买）。
当 CFOP 为 3.xxx 时，ii 区块（进口税）为必填。数值来自报关员开具的 DI（vBC、vDespAdu、vII、vIOF）。测试时可为零。
import_declarations 区块（进口申报）包含通关数据：nDI、dDI、通关地点/UF/日期、运输方式、中介、出口商和附加。
当 tpViaTransp = 1（海运）时，vAFRMM 为必填。

说明

NFe 调整 / 补充

补充NFe和调整NFe是为了更正已授权发票的税务值而开具的新发票。与CC-e不同（CC-e仅更正登记信息），这些发票允许修改税额、数量和价格。

补充NFe（finalidade = 2）：

用于增加在原始发票中申报不足的金额
价格补充、数量或税额的补充
例如：开具了ICMS为12%的发票，但正确税率为18% — 开具补充发票补差额

调整NFe（finalidade = 3）：

用于法规规定的各种税务调整
库存调整、税收抵免转移、税务合规化
例如：ICMS核算调整、分支机构之间的税收抵免转移

重要：

两者都是新发票 — 生成新的访问密钥和新编号
必须通过 ref_nfe_chave 字段引用原始发票（44位密钥）
原始发票必须已授权
每张消耗1个额度（与正常开票相同）

认证

使用与NFe开票相同的接口和认证方式：

Header	类型	描述
token	string	企业令牌（注册时获取）
sign	string	MD5签名：`MD5(token + path + body + timestamp)`
timestamp	string	Unix时间戳（秒）（5分钟窗口）

POST/api/invoice/create

开具补充 NF-e

必填请求头

Header	类型	描述
token	string	企业令牌
sign	string	MD5签名：`MD5(token + path + body + timestamp)`
timestamp	string	Unix时间戳（秒）（5分钟窗口）

特定字段

字段	类型	描述
finalidade	string	`"2"` 表示补充（必填）
ref_nfe_chave	string	原始发票访问密钥 — 44位（必填）

说明： 其余字段与 /api/invoice/create 正常开票接口的格式相同。请参阅NFe开票文档了解所有字段的详细信息。

付款： 在补充发票中，付款方式通常为 "90"（无付款），因为这仅是税务值的补充。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/invoice/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "finalidade": "2",
          "ref_nfe_chave": "CHAVE_NFE_AQUI",
          "nature_of_operation": "Complemento de preço",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "ind_final": "1",
          "ind_pres": "2",
          "cliente": {
            "cpf": "264.438.800-72",
            "name": "Nome do Destinatário",
            "endereco": "Rua Example",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "indIEDest": "9"
          },
          "products": [
            {
              "codigo": "001",
              "name": "Complemento de valor - Produto X",
              "ncm": "82100090",
              "count": 1,
              "unit": "matriz",
              "unit_price": 5.00,
              "total_price": 5.00,
              "category_id": "SEU_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5102"
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

        {
          "success": true,
          "data": {
            "uuid": "a1b2c3d4-e5f6-...",
            "chave": "35260312345678000195550010000004051234567890",
            "status": "Success",
            "motivo": "Autorizado o uso da NF-e",
            "nfe": 405,
            "serie": 1,
            "danfe": "https://storage.../danfe.pdf",
            "xml": "https://storage.../xml.xml"
          }
        }

POST/api/invoice/create

开具调整 NF-e

必填请求头

Header	类型	描述
token	string	企业令牌
sign	string	MD5签名：`MD5(token + path + body + timestamp)`
timestamp	string	Unix时间戳（秒）（5分钟窗口）

特定字段

字段	类型	描述
finalidade	string	`"3"` 表示调整（必填）
ref_nfe_chave	string	原始发票访问密钥 — 44位（必填）

可用的 finalidade 值：

值	描述
1	正常（默认）
2	补充
3	调整
4	退货

补充与调整的区别：

补充（2）： 补充原始发票的金额（价格、税额、申报不足的数量）
调整（3）： 法规规定的税务调整（合规化、税收抵免转移、库存调整）

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/invoice/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "finalidade": "3",
          "ref_nfe_chave": "CHAVE_NFE_AQUI",
          "nature_of_operation": "Ajuste fiscal",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "ind_final": "1",
          "ind_pres": "2",
          "cliente": {
            "cpf": "264.438.800-72",
            "name": "Nome do Destinatário",
            "endereco": "Rua Example",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01310100",
            "indIEDest": "9"
          },
          "products": [
            {
              "codigo": "001",
              "name": "Ajuste fiscal - Regularização",
              "ncm": "82100090",
              "count": 1,
              "unit": "matriz",
              "unit_price": 0.01,
              "total_price": 0.01,
              "category_id": "SEU_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1",
              "cfop": "5949"
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

POST/api/invoice/v2/create

异步开具 NF-e

请求体与 /api/invoice/create 完全相同，校验规则也相同。区别在于不等待税务局：校验通过后立即入队并返回受理单号 task_id，由后台异步完成开票。结果通过 /api/invoice/v2/task/get 轮询，或由后台配置的 Webhook 地址接收推送（见下文「Webhook 回调」）。

必需请求头

字段	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段与 /api/invoice/create 完全一致（cliente、products[]、pag_info 等），此处不再重复。请求里的 callback_url 会被忽略：回调地址只取后台配置。

字段	类型	说明
is_reopen	boolean	重新打开 / 覆盖之前已开具的 NF-e，语义与 v1 相同

处理规则

规则	说明
幂等	传了业务单号 `id` 时，同一 CNPJ 在 5 分钟内内容相同的请求复用同一任务，返回同一 `task_id`，不重复入队；未传 `id` 不做去重。
限流	同一 CNPJ 1 分钟内最多 100 个排队或处理中的任务，超出返回 `Rate limit exceeded for this CNPJ`。
状态	受理后为 `pending`，处理中 `processing`，终态 `success` / `failed`。

响应字段

字段	类型	说明
task_id	string	任务号，用于轮询与回调去重
id	string	请求里的业务单号（未传为空）
status	string	任务状态，受理时恒为 `pending`

响应 — 被拒

{ "success": false, "message": "Rate limit exceeded for this CNPJ, please slow down" }

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/invoice/v2/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

{
  "id": "PED-1001",
  "nature_of_operation": "Venda de mercadoria",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "2",
  "cliente": { "cpf": "26443880072", "name": "Nome do Destinatário", "endereco": "Rua Example",
               "number": "100", "bairro": "Centro", "city": "São Paulo", "uf": "SP", "cep": "01310100" },
  "products": [ { "codigo": "P1", "name": "Produto", "ncm": "10063021", "count": 1, "unit": "UN",
                  "unit_price": 100, "total_price": 100, "origem": 0, "indicador_total": 1,
                  "category_id": "CATEGORY_ID" } ],
  "pag_info": [ { "payment_method": "01", "payment_indicator": "0", "payment_value": 100 } ]
}

{
  "success": true,
  "message": "Recebido. Consulte o resultado via /api/invoice/v2/task/get (task_id) ou aguarde o callback. Não reenvie.",
  "task_id": "66d0a1b2c3d4e5f6a7b8c9d0",
  "id": "PED-1001",
  "status": "pending"
}

POST/api/invoice/v2/task/get

查询异步开票结果

按 task_id 查询任务状态与结果。规范路径为 /api/invoice/v2/task/get；历史路径 /api/invoice/task/get 继续可用，行为与计费相同。只能查询本账号提交的任务，否则返回 Task not found。建议每 1–2 秒轮询一次，任务通常在数秒内完成。

必需请求头

字段	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
task_id *	string	`/api/invoice/v2/create` 返回的任务号

status

状态	含义
pending	已受理，等待处理
processing	正在向税务局提交
success	开票成功，响应体含与 `/api/invoice/create` 相同的 `data`
failed	开票失败，`message` 为失败原因（优先税务局拒收原因）

顶层 status 是任务状态（小写）；成功时 data.status 是开票结果状态（如 Success），与 /api/invoice/create 一致。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/invoice/v2/task/get" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

{ "task_id": "66d0a1b2c3d4e5f6a7b8c9d0" }

{ "success": true, "message": "Em processamento, consulte novamente.", "status": "processing" }

{
  "success": true,
  "message": "成功",
  "status": "success",
  "data": {
    "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
    "status": "Success",
    "motivo": "Autorizado o uso da NF-e",
    "nfe": 100,
    "serie": 1,
    "chave": "35260112345678000199550010000001001000000017",
    "modelo": "nfe",
    "epec": false,
    "xml": "https://oss.example.com/.../chave.xml"
  }
}

{ "success": false, "message": "Rejeição 539: Duplicidade de NF-e, com diferença na Chave de Acesso", "status": "failed" }

说明

Webhook 回调（开票结果推送）

异步开票任务到达终态后，平台向集成商配置的地址推送一条结果通知。推送与轮询可同时使用：以回调为主、轮询兜底。

配置与地址要求

账号级地址：集成商后台「账号信息 → 推送地址」。
应用级地址：在管理该公司的应用（API 密钥）上配置，可按接口订阅；优先级应用级 > 账号级。
请求级 callback_url 不支持，传了也会被忽略。
地址必须是公网 http(s)，不能是内网或环回地址；不跟随重定向，返回 3xx 按失败处理；超时 10 秒；返回 2xx 视为成功。

投递时机与重试

任务终态（success / failed）后立即投递一次。
失败后按 +1 分钟、+10 分钟、+60 分钟、+4 小时、+12 小时重推，共 6 次（约 17 小时）；仍失败则停止，可用 /api/invoice/v2/task/get 兜底。
投递语义为「至少一次」，接收方须按 task_id 去重。

报文（解密后）

字段	类型	说明
task_id	string	任务号，去重键
id	string	请求里的业务单号
company_id	int	开票公司 ID
cnpj	string	开票公司 CNPJ
status	string	`success` / `failed`
result	object	成功时为与 `/api/invoice/create` 相同的响应对象，并补充 `data.danfe`（DANFE PDF 地址）；失败时为 `null`
error	string	失败原因，优先税务局拒收原因；成功时为空串
test	boolean	仅后台「测试推送」发出的报文带此字段且为 `true`，接收方应忽略

{
  "task_id": "66d0a1b2c3d4e5f6a7b8c9d0",
  "id": "PED-1001",
  "company_id": 1263,
  "cnpj": "12345678000199",
  "status": "success",
  "result": {
    "success": true,
    "message": "成功",
    "data": {
      "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
      "status": "Success",
      "motivo": "Autorizado o uso da NF-e",
      "nfe": 100, "serie": 1,
      "chave": "35260112345678000199550010000001001000000017",
      "modelo": "nfe", "epec": false,
      "xml": "https://oss.example.com/.../chave.xml",
      "danfe": "https://oss.example.com/.../chave.pdf"
    }
  },
  "error": ""
}

加密信封

报文用 AES-256-GCM 加密后投递。密钥由集成商 API 密钥派生，无需交换额外密钥：key = SHA-256(UTF-8(token))，其中 token 为管理该公司的应用密钥。GCM 自带完整性校验，篡改任一字段（含 ts）都会导致解密失败，因此不再附加签名头。

请求头：X-Webhook-Timestamp（Unix 秒，与信封 ts 相同）、X-Webhook-Encryption: A256GCM。解析不到密钥时会以明文投递，此时没有 X-Webhook-Encryption 头，接收方应据此区分。

解密：nonce、payload、tag 为 Base64；附加认证数据（AAD）为 ts 的十进制字符串（UTF-8）。

POST {webhook_url}
Content-Type: application/json
X-Webhook-Timestamp: 1786990396
X-Webhook-Encryption: A256GCM

{
  "enc": "A256GCM",
  "kid": "token",
  "ts": 1786990396,
  "nonce": "<base64, 12 bytes>",
  "payload": "<base64 ciphertext>",
  "tag": "<base64, 16 bytes>"
}

Python 解密示例（cryptography）

import base64, hashlib, json
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

def decrypt(token, body):
    env = json.loads(body)
    key = hashlib.sha256(token.encode("utf-8")).digest()
    aad = str(env["ts"]).encode("utf-8")
    data = base64.b64decode(env["payload"]) + base64.b64decode(env["tag"])
    plain = AESGCM(key).decrypt(base64.b64decode(env["nonce"]), data, aad)
    return json.loads(plain)

Node.js 解密示例

const crypto = require("crypto");

function decrypt(token, body) {
  const env = JSON.parse(body);
  const key = crypto.createHash("sha256").update(token, "utf8").digest();
  const d = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(env.nonce, "base64"));
  d.setAAD(Buffer.from(String(env.ts), "utf8"));
  d.setAuthTag(Buffer.from(env.tag, "base64"));
  const plain = Buffer.concat([d.update(Buffer.from(env.payload, "base64")), d.final()]);
  return JSON.parse(plain.toString("utf8"));
}

联调

后台「推送地址」旁的「测试推送」按钮会向该地址发送一条加密的测试报文（test: true），用于验证连通性与解密。
也可以把系统提供的测试收件箱地址（/webhook/inbox/{slot}，slot 为自定义标识）配置为推送地址，在后台查看解密后的报文。

说明

CC-e — 电子更正函

CC-e（电子更正函）是附加在NF-e上的事件，允许更正已授权发票的信息，但不能修改税务值。依据 Ajuste SINIEF 01/07 规范。

可以通过CC-e更正的内容：

收件人或发件人的地址
收件人的公司名称（不更改CNPJ/CPF）
税务操作代码（CFOP），前提是不改变税种
商品描述
附加数据和补充信息

不能通过CC-e更正的内容：

税务值（计税基数、税率、税额）
商品的数量和金额
发件人或收件人的CNPJ/CPF
影响税款计算的数据

规则：

只有状态为已授权（Success）的发票才能接收CC-e
更正文本必须在15到1000个字符之间
同一张发票最多可以发送20个CC-e
每个CC-e消耗1个额度

认证

所有CC-e接口使用与主API相同的认证方式：

Header	类型	描述
token	string	企业令牌（注册时获取）
sign	string	MD5签名：`MD5(token + path + body + timestamp)`
timestamp	string	Unix时间戳（秒）（5分钟窗口）

POST/api/invoice/cce/send

发送更正函（CC-e）

向税务局发送 CC-e（事件 110110），以更正已授权的 NF-e 的数据。序列号（nSeqEvento）会自动计算 — 请勿发送。只能更正非财务数据（不能更正金额、CNPJ、IE 等）。

必需请求头

请求头	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
uuid	string	NF-e UUID（如果没有 `chave` 则必填）
chave	string	NF-e 的 44 位访问密钥（如果没有 `uuid` 则必填）
correcao *	string	更正文本（税务局限制：15–1000 个字符）
n_seq_evento	int	事件序列号。默认由系统按本平台已登记的更正函数量推算；当该发票在别处已经发过更正函时，需显式传入更大的序号

* 必填字段。uuid 或 chave 至少一个也必填。

在别处开具的发票同样可以发送更正函：更正函是独立于原发票的事件，只要访问密钥中的开票方税号属于该令牌名下的公司即可。此类发票本平台没有原始记录，序列号无从推算，默认取 1；若税务局返回该序号的事件已存在，请改用更大的 n_seq_evento 重新提交。此类发票不提供更正函 PDF，仅提供事件 XML。

POST/api/invoice/cce/get_list

CC-e 列表

返回特定 NF-e 发出的所有 CC-e（更正函），按从最新到最旧排序。

必需请求头

请求头	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
uuid	string	NF-e UUID（如果没有 `chave` 则必填）
chave	string	NF-e 的 44 位访问密钥（如果没有 `uuid` 则必填）

uuid 或 chave 至少一个必填。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
curl -X POST "https://api.tffiscal.com/api/invoice/cce/get_list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

        {
          "success": true,
          "data": {
            "items": [
              {
                "id": "65fa1b2c3d4e5f6a7b8c9d0e",
                "detail": "Corrigir nome do destinatario para Empresa XYZ LTDA",
                "nProt": "135210000123456",
                "nSeqEvento": 1,
                "date": "15/01/2024 14:30:00",
                "pdfUrl": "https://oss.example.com/.../cce_seq1.pdf",
                "xmlUrl": "https://oss.example.com/.../cce.xml"
              }
            ],
            "total": 1
          }
        }

POST/api/invoice/cce/download_pdf

下载 CC-e PDF

返回 CC-e 的 PDF URL。PDF 在首次调用时按需生成（从发票 XML + CC-e XML 渲染）并存储在 OSS 中；后续调用返回现有 URL。

必需请求头

请求头	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
cce_id *	string	由 `/api/invoice/cce/get_list` 的 `id` 字段返回的 CC-e ID（ObjectId）

* 必填字段。

POST/api/invoice/cce/download_xml

下载 CC-e XML

返回签名后的 CC-e XML URL（在提交到税务局后已存储在 OSS 中）。

必需请求头

请求头	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
cce_id *	string	由 `/api/invoice/cce/get_list` 的 `id` 字段返回的 CC-e ID（ObjectId）

* 必填字段。

必需请求头

Body — 顶层字段

Body — cliente（对象，必填）

Body — products[]（数组，至少 1 项）

Body — products[].impostos

跨州开票：DIFAL 基数怎么传

Body — products[].ii（进口税）

Body — products[].import_declarations[]

Body — shipping_address / delivery_address（对象，可选）

Body — transportation（对象，可选）

Body — pag_info[]（数组，可选）

返回字段（data）

返回 — 拒绝 / 错误

必需请求头

查询字符串

必需请求头

查询字符串

必需请求头

Body

必需请求头

Body

返回字段（data）

返回 — 错误

必需请求头

Body

返回字段（data）

返回 — 错误

必需请求头

Body

响应字段

错误响应

必需请求头

Body

响应字段

错误响应

必需请求头

Body

响应字段

状态映射

错误响应

必需请求头

Body — 始终读根级的字段

Body — return_detail 内的字段

带运输的完整示例

进口完整示例

认证

必填请求头

特定字段

必填请求头

特定字段

必需请求头

Body

处理规则

响应字段

响应 — 被拒

必需请求头

Body

status

配置与地址要求

投递时机与重试

报文（解密后）

加密信封

联调

认证

必需请求头

Body

必需请求头

Body

必需请求头

Body

必需请求头

Body

Body — `cliente`（对象，必填）

Body — `products[]`（数组，至少 1 项）

Body — `products[].impostos`

Body — `products[].ii`（进口税）

Body — `products[].import_declarations[]`

Body — `shipping_address` / `delivery_address`（对象，可选）

Body — `transportation`（对象，可选）

Body — `pag_info[]`（数组，可选）

返回字段（`data`）

返回字段（`data`）

返回字段（`data`）

Body — `return_detail` 内的字段