REST API v2.5 系统运行正常

NFE API 文档

欢迎来到TF Fiscal API文档。这是一个完整的巴西电子发票（NF-e）发行、查询和取消API。支持自动计算税款（ICMS、IPI、PIS/COFINS），生成XML，SEFAZ授权以及与管理系统的集成。

list_alt

API重要字段

关键字段解释

本部分解释了NFE API中最重要且对正确发行发票至关重要的字段。

⚠️ 注意：这些字段的正确配置对于有效发行发票至关重要。请始终参考现行税务法规。

字段	描述	可能值	重要性
`invoice_type`	公司类型（法人/自然人）	`juridica`, `fisica`	高 - 定义税收制度
`nature_of_operation`	操作性质（销售、退货等）	例如：`VENDA`, `DEVOLUCAO`	高 - 确定CFOP
`transaction_type`	交易类型（进/出）	`ENTRADA`, `SAIDA`	高 - 引导税务流程
`model`	发票模型	`nfe`, `nfce`	高 - 文档模型
`issuance_type`	发行类型（正常、应急）	`NORMAL`, `CONTINGENCIA`	中 - 发行模式
`ambiente`	处理环境	`PRODUCAO`, `HOMOLOGACAO`	高 - 定义SEFAZ目的地
`cliente`	客户/买方类型	`CONSUMIDOR`, `CONTRIBUINTE`	高 - 影响税款
`products.origem`	产品来源（国内/进口）	`0` 至 `8`	高 - 決定征税
`products.indicador_total`	产品是否计入发票总额	`true`, `false`	中 - 用于样品项目

💡 提示：对于产品，origem字段至关重要：0-国内，1-直接进口外国产品，2-在国内市场购买的外国产品等。请参考完整的商品来源表。

sync_alt

发票发行流程

完整的NF-e发行流程图

从公司创建到最终文件生成的完整巴西电子发票发行流程。

business

1. 创建公司

创建巴西本地公司的税务信息

send

2. 信息推送

订单数据（用户、地址、产品税款）

receipt

3. 发行发票

处理并发送给SEFAZ授权

assignment_returned

4. 返回结果

发行状态和NF-e数据

description

5. 生成文件

发票的XML和PDF

published_with_changes

税务验证

与SEFAZ验证

check_circle

成功

error

失败

初始配置

数据处理

税务发行

正面结果

📊 详细流程： 流程遵循逻辑顺序：(1) 公司配置 → (2) 接收订单数据 → (3) 处理和发行NF-e → (4) 返回状态 → (5) 生成文件。決策点（税务验证）決定发行是否获得SEFAZ授权。

flash_on

端点快速参考

NFE API所有端点

API中所有可用端点的完整概述。使用此表作为瀏览文档的快速参考。

基础URL

https://api.tffiscal.com

路径	HTTP方法	功能
receipt NFC-e (消费者电子发票)
`/api/nfce/company/create`	POST	注册NFC-e企业
`/api/nfce/company/update`	POST	更新NFC-e企业
`/api/nfce/company/get`	POST	查询NFC-e企业
`/api/nfce/create`	POST	开具NFC-e
`/api/nfce/cancel`	POST	取消NFC-e
`/api/nfce/get_detail`	POST	查询NFC-e
`/api/nfce/get_danfe`	POST	获取NFC-e DANFE
description NFS-e (服务电子发票)
`/api/nfse/create`	POST	开具NFS-e
`/api/nfse/cancel`	POST	取消NFS-e
`/api/nfse/get_danfse`	POST	获取DANFSE (PDF)
`/api/nfse/get_xml`	POST	下载NFS-e XML

📋 重要说明：

所有端点都需要通过标头进行认证： sign, timestamp, token
要创建公司和列出公司，请使用分销商令牌（b2b_token）
Content-Type必须始终为 application/json;charset=utf-8
响应遵循带有success、 message和data字段的JSON标准

200

成功

请求处理成功

400

客户端错误

无效或缺少数据

500

服务器错误

服务器内部错误

account_balance

NFE API

巴西电子发票（NF-e）

用于巴西电子发票（NF-e）发行、查询和取消的完整API。支持自动计算税款（ICMS、IPI、PIS/COFINS），生成XML，SEFAZ授权以及与管理系统的集成。目前支持为整个巴西境内的产品发行发票。

基础URL（生产环境）

https://api.tffiscal.com/v1

认证

标头：sign, timestamp, token

要求

有效的A1数字证书

sync_alt 系统流程

input 输入数据

客户信息
产品数据
税务信息
运输数据

settings 处理

数据验证
税款计算
XML生成
SEFAZ授权

download 输出

发票XML
发票PDF
DANFE（辅助文档）
授权状态

主要端点

POST /api/company/create

注册新的开票公司

在分销商（b2b）账户下注册开票公司。当公司数据已有时使用此端点。要从数字证书自动提取数据，请使用 /api/company/v2/create。

必需请求头

请求头	类型	说明
token	string	分销商令牌（b2b — 账户必须具有 `isb2b=true`）
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
标识
cnpj *	string	开票公司 CNPJ
name *	string	公司名称
ie *	string	州注册号（Inscrição Estadual）
invoice_type *	string	税务制度（例如：`"simples_nacional"`、`"normal"`）
unit *	string	单位类型
email	string	公司电子邮件
地址
cep *	string	邮政编码
address *	string	街道地址
house_number *	string	地址门牌号
town *	string	街区
city *	string	城市
state *	string	UF（州缩写）
数字证书
cert_file *	string	A1 数字证书（.pfx 或 .p12）的 HTTPS URL
cert_pwd *	string	证书密码
编号和设置
serie *	int	NF-e 系列
number *	int	编号的初始值
is_create_category_template	boolean	自动创建默认税务类别。默认值：`true`

* 必填字段。

载荷示例

        {
          "cnpj": "12345678000199",
          "name": "Empresa Exemplo LTDA",
          "ie": "123456789",
          "invoice_type": "simples_nacional",
          "unit": "UN",
          "email": "contact@example.com",
          "cep": "01001000",
          "address": "Example Street",
          "house_number": "100",
          "town": "Downtown",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://example.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "serie": 1,
          "number": 1
        }

响应

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/v2/create

使用证书自动填充注册公司

/api/company/create 的简化版本：API 验证数字证书并通过内部查询自动提取公司名称、IE、地址等数据。只有 cnpj、cert_file 和 cert_pwd 是必填的。

必需请求头

请求头	类型	说明
token	string	分销商令牌（b2b — 账户必须具有 `isb2b=true`）
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
cnpj *	string	开票公司 CNPJ
cert_file *	string	A1 数字证书（.pfx 或 .p12）的 HTTPS URL
cert_pwd *	string	证书密码
is_create_category_template	boolean	自动创建默认税务类别。默认值：`true`

* 必填字段。

载荷示例

        {
          "cnpj": "12345678000199",
          "cert_file": "https://example.com/cert.pfx",
          "cert_pwd": "senha_do_certificado"
        }

响应

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/edit

编辑公司数据

更新开票公司数据。只发送要更改的字段 — 除 company_id 外，所有字段都是可选的。CNPJ 不可修改：发送会返回错误。更新 cep 时，系统自动解析 stateCode 和 ibge。当 cert_file 和 cert_pwd 一起发送时，证书在保存前会经过验证。

必需请求头

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

Body

字段	类型	说明
company_id *	string	要编辑的公司 ID
name	string	公司名称
invoice_type	string	税务制度
ie	string	州注册号
unit	string	单位类型
email	string	电子邮件
cep	string	邮政编码（自动更新 `stateCode` 和 `ibge`）
address	string	街道地址
house_number	string	门牌号
town	string	街区
city	string	城市
state	string	UF
cert_file	string	新证书（.pfx 或 .p12）的 HTTPS URL。与 `cert_pwd` 一起发送时，在保存前进行验证
cert_pwd	string	新证书密码
serie	int	新 NF-e 系列
number	int	新初始编号

* 必填字段。发送 cnpj 会返回错误。

载荷示例

                {
                  "company_id": "comp_789012",
                  "name": "Nova Razão Social LTDA",
                  "email": "new@company.com",
                  "cep": "01310100"
                }

响应

                {
                  "success": true
                }

GET /api/company/get_list

列出分销商公司

分页列出分销商（b2b）账户下的开票公司。参数通过 查询字符串 传递。

必需请求头

请求头	类型	说明
token	string	分销商令牌（b2b — 账户必须具有 `isb2b=true`）
sign	string	MD5 签名（path 包含查询字符串）
timestamp	string	秒级 Unix 时间戳

查询字符串

参数	类型	说明
page *	int	页码（≥ 1）
page_size *	int	每页大小（1–20）

* 必填字段。

调用示例

GET /api/company/get_list?page=1&page_size=10

响应

        {
          "success": true,
          "data": {
            "companys": [
              {
                "company_id": "comp_789012",
                "invoice_type": "simples_nacional",
                "token": "eyJhbGciOiJIUzI1NiIs...",
                "cnpj": "12345678000199",
                "name": "Empresa Exemplo LTDA",
                "ie": "123456789",
                "unit": "UN",
                "email": "contact@example.com",
                "cep": "01001000",
                "address": "Example Street",
                "house_number": "100",
                "town": "Downtown",
                "city": "São Paulo",
                "state": "SP",
                "cert_file": "https://example.com/cert.pfx",
                "cert_pwd": "***",
                "serie": 1,
                "number": 142
              }
            ],
            "page": 1,
            "total": 8,
            "total_pages": 1
          }
        }

GET /api/company/get_detail

已认证公司的详情

返回由 token 请求头标识的公司的完整数据，包括已注册的税务类别列表。不接受 body 或查询字符串。

必需请求头

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

调用示例

GET /api/company/get_detail

响应

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "name": "Empresa Exemplo LTDA",
            "token": "eyJhbGciOiJIUzI1NiIs...",
            "invoice_type": "simples_nacional",
            "cnpj": "12345678000199",
            "ie": "123456789",
            "unit": "UN",
            "email": "contact@example.com",
            "cep": "01001000",
            "address": "Example Street",
            "house_number": "100",
            "town": "Downtown",
            "city": "São Paulo",
            "state": "SP",
            "cert_file": "https://example.com/cert.pfx",
            "cert_pwd": "***",
            "serie": 1,
            "number": 142,
            "categorys": [
              {
                "category_id": "cat_001",
                "descricao": "Venda de mercadoria",
                "disable_difal": false,
                "desconta_icms_pis_cofins": false
              }
            ]
          }
        }

GET /api/company/get_cep_detail

通过 CEP 查询地址

解析巴西 CEP（邮政编码），返回 UF、IBGE 自治市代码和地址数据。用于填写公司和客户地址。需要分销商（b2b）账户。

必需请求头

请求头	类型	说明
token	string	分销商令牌（b2b — 账户必须具有 `isb2b=true`）
sign	string	MD5 签名（path 包含查询字符串）
timestamp	string	秒级 Unix 时间戳

查询字符串

参数	类型	说明
cep *	string	巴西 CEP（8 位，可带或不带连字符）

* 必填字段。

调用示例

GET /api/company/get_cep_detail?cep=01001000

响应

        {
          "success": true,
          "data": {
            "cep": "01001-000",
            "uf": "SP",
            "ibge": 3550308,
            "logradouro": "Praça da Sé",
            "bairro": "Sé",
            "localidade": "São Paulo",
            "ddd": "11"
          }
        }

GET /api/company/get_export_invoice_month_files

列出已生成的每月导出文件

返回当前年度（时区 America/Sao_Paulo）该公司已生成的每月导出文件列表。每个月最多可以有 4 个文件：1 个 Excel 电子表格（仅 Success 状态）+ 3 个 XML（按 Success、Canceled、Voided 状态各一个）。仅显示实际已导出的文件 — 使用 /api/invoice/get_xml 生成新文件。

必需请求头

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

调用示例

GET /api/company/get_export_invoice_month_files

响应

字段	类型	说明
files[]	array	可用文件列表
files[].url	string	OSS 上的文件 URL
files[].year	int	期间年份
files[].month	string	月份（1–12）
files[].type	string	文件类型：`"xlsx"` 或 `"xml"`
files[].status	string	文件中发票的状态：`"Success"`、`"Canceled"` 或 `"Voided"`
files[].create	datetime	文件生成时间

响应示例

        {
          "success": true,
          "data": {
            "files": [
              {
                "url": "https://oss.example.com/.../2024_01_success.xlsx",
                "year": 2024,
                "month": "1",
                "type": "xlsx",
                "status": "Success",
                "create": "2024-02-01T03:15:00Z"
              },
              {
                "url": "https://oss.example.com/.../2024_01_success.zip",
                "year": 2024,
                "month": "1",
                "type": "xml",
                "status": "Success",
                "create": "2024-02-01T03:15:30Z"
              }
            ]
          }
        }

GET /api/category/get_list

列出产品类别

返回所有可用的税务分类类别。

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	发票总折扣
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/tax_info 对象（内联配置），二选其一。

字段	类型	说明
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	项目折扣
origem *	int	商品来源 (`0`=国产, `1`=进口—直接进口, 等)
indicador_total *	int	是否计入 NF-e 总额: `0`=否, `1`=是
category_id	string	预注册的税务类别 ID（若不传 `impostos`/`tax_info` 则必填）
impostos	object	内联税务配置（`category_id` 的替代）。结构见下
tax_info	object	`impostos` 别名（相同结构）
disable_difal	boolean	禁用此项的 DIFAL 计算
desconta_icms_pis_cofins	boolean	仅对此项目从 PIS/COFINS 计税基础中扣除 ICMS（覆盖类别设置）
ii	object	进口税 — CFOP 3.xxx 时必填。结构见下
import_declarations	array	进口报关单（DI） — 当 `transaction_type="2"` 时必填。结构见下
nItemPed	int	采购订单项目 (I61)。从根 `id` 取得的 `xPed` 所引用订单内的项目顺序号。有效范围: 1–999999。默认: 省略。

Body — `products[].impostos` / `products[].tax_info`

字段	类型	说明
industria	string	基准行业/税率（别名: `aliquota`）
icms
icms.codigo_cfop	string	CFOP
icms.situacao_tributaria	string	ICMS 的 CST/CSOSN
icms.industria	string	ICMS 行业
icms.tipo_pessoa	string	人员类型（PF/PJ）
icms.codigo_beneficio_fiscal	string	cBenef（税收优惠代码）
ipi
ipi.codigo_enquadramento	string	IPI 法律分类代码
ipi.situacao_tributaria	string	IPI 的 CST
ipi.aliquota	string	IPI 税率
ipi.tipo_pessoa	string	人员类型
pis
pis.situacao_tributaria	string	PIS 的 CST
pis.aliquota	string	PIS 税率
pis.tipo_pessoa	string	人员类型
cofins
cofins.situacao_tributaria	string	COFINS 的 CST
cofins.aliquota	string	COFINS 税率
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 税务分类
difal
difal.disable_difal	boolean	禁用项目的 DIFAL（产品级 `disable_difal` 的替代）

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	授权码

* 必填字段。

简化示例

{
  "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": "UN",
      "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.00,
  "troco": 0.00,
  "seguro": 0.00,
  "outras_despesas": 0.00,
  "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": "UN",
      "unit_price": 3500.00,
      "total_price": 7000.00,
      "discount_price": 0.00,
      "origem": 0,
      "indicador_total": 1,
      "category_id": "TF00001",
      "nItemPed": 1
    },
    {
      "codigo": "PROD002",
      "name": "Mouse sem fio",
      "ncm": "84716053",
      "count": 5,
      "unit": "UN",
      "unit_price": 80.00,
      "total_price": 400.00,
      "origem": 0,
      "indicador_total": 1,
      "nItemPed": 2,
      "impostos": {
        "icms": {
          "codigo_cfop": "5102",
          "situacao_tributaria": "00",
          "industria": "",
          "tipo_pessoa": "juridica",
          "codigo_beneficio_fiscal": ""
        },
        "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"
        }
      }
    }
  ],
  "transportation": {
    "transport_mode": "1",
    "freight_amount": 150.00,
    "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.500,
        "net_weight": 11.000,
        "packaging_type": "CAIXA",
        "number": "001-003",
        "mark": "FRAGIL",
        "seals": ["LACRE001", "LACRE002"]
      }
    ],
    "transport_tax_retention_info": {
      "freight_service_amount": 150.00,
      "tax_base": 150.00,
      "tax_rate": 12.00,
      "cfop": "5932",
      "cep": "11000000"
    }
  },
  "pag_info": [
    {
      "payment_indicator": "1",
      "payment_method": "03",
      "payment_value": 7400.00,
      "card_info": {
        "integration_type": "1",
        "brand_code": "01",
        "acquirer_cnpj": "01234567000189",
        "authorization_code": "AUTH987654"
      }
    }
  ]
}

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	按状态过滤（值: `"Authorized"`、`"Canceled"`、`"Processing"`、`"Rejected"` 等）

* 必填字段。

调用示例

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

响应

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35210112345678901234567890123456789012345678",
                "status": "Authorized",
                "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 返回特定 NF-e 的详情。包括 XML URL、DANFE URL（完整、简化、标签）和元数据。

必需请求头

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

查询字符串

参数	类型	说明
uuid *	string	NF-e UUID

* 必填字段。

调用示例

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

响应

        {
          "success": true,
          "data": {
            "id": "order-2024-0001",
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234567890123456789012345678",
            "serie": 1,
            "number": 100,
            "status": "Authorized",
            "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

更新发票状态

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

必需请求头

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

Body

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

* 必填字段。

载荷示例

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/cancel

取消发票

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

必需请求头

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

Body

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

* 必填字段。

载荷示例

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/invalid

作废编号范围

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

必需请求头

请求头	类型	说明
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	作废理由（SEFAZ 要求至少 15 个字符）

* 必填字段。

载荷示例

        {
          "modelo": "55",
          "ambiente": "2",
          "serie": 1,
          "start_number": 100,
          "end_number": 105,
          "motivo": "Falha no sistema durante a emissao do lote"
        }

POST /api/invoice/get_danfe

获取 NF-e 的 DANFE(PDF)

返回 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 二选一,必填。

请求示例

                {
                  "uuid": "abc123-def456-..."
                }

响应

                {
                  "success": true,
                  "data": {
                    "danfe": "https://storage.../uid/dd-MM-yyyy/companyId/.pdf",
                    "danfe_simples": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.pdf",
                    "danfe_simples_png": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.png"
                  }
                }

响应字段

字段	类型	说明
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

XML/Excel 批量导出(异步)

为用户发票启动异步批量导出任务,按时间段和状态过滤。可生成 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 时间戳,毫秒)
end_create_time	long	时间段结束(Unix 时间戳,毫秒)

* 必填字段。

请求示例

                {
                  "type": "xml",
                  "status": "Success",
                  "month": 5
                }

响应 — 处理中

                {
                  "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/.zip"
                  }
                }

响应字段

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

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

错误响应

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

POST /api/invoice/consultar_status

在 SEFAZ 查询 NF-e/NFC-e 状态

通过 NfeConsultaProtocolo4 服务,使用访问密钥(44 位)直接在 SEFAZ 查询 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)。

* 必填字段。

请求示例

        {
          "chave": "35260512345678000199550010000000011000000018"
        }

响应

        {
          "success": true,
          "message": "Sucesso",
          "data": {
            "chave": "35260512345678000199550010000000011000000018",
            "status": "autorizada",
            "cstat": 100,
            "motivo": "Autorizado o uso da NF-e"
          }
        }

响应字段

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

状态映射

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

错误响应

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

POST /api/category/create

创建税务类别

创建一个绑定到已认证公司的新税务类别（税务模板）。每个类别聚合 ICMS、IPI、PIS、COFINS 场景，并可选包含 IBS/CBS 和 IS。要编辑现有类别，请使用 /api/category/edit。

必需请求头

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

Body — 顶层

字段	类型	说明
descricao *	string	类别说明
category_id	string	自定义 ID。省略时自动生成为 `"TF"` + 递增数字
disable_difal	boolean	禁用此类别的 DIFAL 计算。默认值：`false`
desconta_icms_pis_cofins	boolean	从 PIS/COFINS 计税基础中扣除 ICMS（计税基础 = vProd − vICMS）。默认: `false`
icms[] *	array	ICMS 场景（结构见下）
ipi[] *	array	IPI 场景（结构见下）
pis[] *	array	PIS 场景（结构见下）
cofins[] *	array	COFINS 场景（结构见下）
ibs_cbs[]	array	IBS/CBS 场景 — 税制改革（结构见下）
is[]	array	IS 场景 — 选择税（结构见下）

Body — `icms[]`

字段	类型	说明
tipo_tributacao *	string	ICMS 课税类型
cenario *	string	场景（例如：`"saida_dentro_estado"`、`"saida_fora_estado"`、`"padrao"`）
tipo_pessoa *	string	`"fisica"` 或 `"juridica"`
codigo_cfop *	string	CFOP
situacao_tributaria *	string	ICMS 的 CST/CSOSN
nao_contribuinte	boolean	非纳税客户
aliquota_importacao	string	进口税率
aliquota_credito	decimal	信用税率（Simples Nacional 用百分比）
aliquota_diferimento	decimal	递延百分比
aliquota_diferimentoFcp	string	FCP 递延（注意：字段使用 camelCase `diferimentoFcp`）
aliquota_reducao	decimal	ICMS 基础减免百分比
aliquota_reducaoSt	decimal	ICMS-ST 基础减免百分比（注意：`reducaoSt` camelCase）
motivo_desoneracao	string	ICMS 免税理由代码
motivo_desoneracaoSt	string	ICMS-ST 免税理由代码（注意：camelCase）
按州税率 — 可选
aliquota_mva[]	array	按 UF 的 MVA — 项：`{ estado, aliquota }`
aliquota_icms[]	array	按 UF 的 ICMS 税率 — 项：`{ estado, aliquota }`
aliquota_icms_st[]	array	按 UF 的 ICMS-ST 税率 — 项：`{ estado, aliquota }`
aliquota_fcp[]	array	按 UF 的 FCP 税率 — 项：`{ estado, aliquota }`
aliquota_fcp_st[]	array	按 UF 的 FCP-ST 税率 — 项：`{ estado, aliquota }`
beneficio_fiscal[]	array	按 UF 的税收优惠代码 — 项：`{ estado, codigo }`

Body — `ipi[]`

字段	类型	说明
cenario *	string	场景
tipo_pessoa *	string	`"fisica"` 或 `"juridica"`
situacao_tributaria *	string	IPI 的 CST
codigo_enquadramento *	string	法律分类代码
aliquota *	string	IPI 税率

Body — `pis[]` 和 `cofins[]`（相同结构）

字段	类型	说明
cenario *	string	场景
tipo_pessoa *	string	`"fisica"` 或 `"juridica"`
situacao_tributaria *	string	PIS/COFINS 的 CST
aliquota *	string	税率

Body — `ibs_cbs[]`（税制改革）

字段	类型	说明
cenario *	string	场景
tipo_pessoa *	string	`"fisica"` 或 `"juridica"`
situacao_tributaria *	string	IBS/CBS 的 CST
classificacao_tributaria *	string	税务分类

Body — `is[]`（选择税）

字段	类型	说明
cenario *	string	场景
tipo_pessoa *	string	`"fisica"` 或 `"juridica"`
situacao_tributaria *	string	IS 的 CST
aliquota *	string	IS 税率

* 必填字段。

最小示例

        {
          "descricao": "Venda de mercadoria padrão",
          "icms": [{
            "tipo_tributacao": "normal",
            "cenario": "padrao",
            "tipo_pessoa": "juridica",
            "codigo_cfop": "5102",
            "situacao_tributaria": "00"
          }],
          "ipi":  [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "99", "codigo_enquadramento": "999", "aliquota": "0" }],
          "pis":  [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "0.65" }],
          "cofins":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "3" }]
        }

响应

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

GET /api/category/get_detail

税务类别详情

返回税务类别的完整配置：所有 ICMS、IPI、PIS、COFINS、IBS/CBS 场景，包括按 UF 的数组（MVA、税率、税收优惠）。

必需请求头

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

查询字符串

参数	类型	说明
category_id *	string	税务类别 ID

* 必填字段。

调用示例

GET /api/category/get_detail?category_id=TF123

响应

        {
          "success": true,
          "data": {
            "category_id": "TF123",
            "descricao": "Venda de mercadoria padrão",
            "disable_difal": false,
            "desconta_icms_pis_cofins": false,
            "icms": [{
              "tipo_tributacao": "normal",
              "cenario": "padrao",
              "tipo_pessoa": "juridica",
              "nao_contribuinte": false,
              "codigo_cfop": "5102",
              "situacao_tributaria": "00",
              "aliquota_importacao": "",
              "aliquota_credito": 0,
              "aliquota_reducao": 0,
              "aliquota_reducao_st": 0,
              "motivo_desoneracao": "",
              "motivo_desoneracao_st": "",
              "aliquota_icms": [{"estado":"SP","aliquota":18}]
            }],
            "ipi":    [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"99","codigo_enquadramento":"999","aliquota":"0"}],
            "pis":    [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"0.65"}],
            "cofins": [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"3"}],
            "ibs_cbs":[]
          }
        }

GET /api/category/get_list

列出税务类别

分页列出已认证公司的税务类别。每项仅返回 category_id 和 descricao — 使用 /api/category/get_detail 获取完整配置。

必需请求头

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

查询字符串

参数	类型	说明
page *	int	页码（≥ 1）
page_size *	int	每页大小（1–50）

* 必填字段。

调用示例

GET /api/category/get_list?page=1&page_size=20

响应

        {
          "success": true,
          "data": {
            "list": [
              { "category_id": "TF123", "descricao": "Venda de mercadoria padrão" },
              { "category_id": "TF124", "descricao": "Devolução de venda" }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST /api/category/edit

编辑税务类别

编辑现有的税务类别。请求体与 /api/category/create 相同，唯一区别是 category_id 必填且必须与现有类别匹配。Upsert 完全替换 icms、ipi、pis、cofins、ibs_cbs、is 数组 — 请发送所有更新后的场景（不会按场景合并）。

必需请求头

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

Body

完整的 body 结构记录在 /api/category/create。此处仅 category_id 处理不同：

字段	类型	说明
category_id *	string	要编辑的类别 ID（必须存在，否则返回错误）
descricao *	string	说明
icms[] *	array	ICMS 场景（完全替换）
ipi[] *	array	IPI 场景
pis[] *	array	PIS 场景
cofins[] *	array	COFINS 场景
ibs_cbs[]	array	IBS/CBS 场景（可选）
is[]	array	IS 场景（可选）
disable_difal	boolean	默认值：`false`
desconta_icms_pis_cofins	boolean	默认: `false`

* 必填字段。每个数组的内部字段（icms[].codigo_cfop 等），请参见 /api/category/create。

响应

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

POST /api/category/delete

删除税务类别

从公司中删除税务类别。不可逆的操作。绑定到此类别的产品仍会引用已删除的 category_id，因此 NFe 开票将失败 — 删除前请先更新产品。

必需请求头

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

Body

字段	类型	说明
category_id *	string	要删除的类别 ID

* 必填字段。

载荷示例

        {
          "category_id": "TF123"
        }

响应

        {
          "success": true
        }

POST /api/invoice/return

开具退货 NF-e

从原始 NF-e 开具退货 NF-e（型号 55，用途 4）。支持两种模式：全额退货（通过 uuid 或 chave 引用原始发票）或 部分／自定义退货（通过 return_detail 提供完整 body）。

必需请求头

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

Body — 顶层字段

字段	类型	说明
uuid	string	原始 NF-e 的 UUID（如果没有 `chave` 则必填；`return_detail` 模式不使用）
chave	string	原始 NF-e 的 44 位访问密钥（`return_detail` 模式必填；简易模式下作为 `uuid` 的替代）
cfop *	string	退货 CFOP（例如：`"1202"`、`"1411"`、`"2202"`、`"5202"`、`"5411"`、`"6202"`）
natureza_operacao	string	操作性质（例如："Devolução de venda"）。接受别名：`nature_of_operation`
return_detail	object	退货 NF-e 的完整 body。与 `/api/invoice/create` 结构相同，有 1 处差异：`return_detail.cliente` 中的地址门牌号字段是 `number`（英文），不是 `numero`。省略时为全额退货并克隆原始 NF-e。

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

示例 — 全额退货

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "cfop": "5202",
          "natureza_operacao": "Devolução de venda"
        }

示例 — 通过 return_detail 部分退货

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "5202",
          "natureza_operacao": "Devolução parcial",
          "return_detail": {
            "nature_of_operation": "Devolução parcial",
            "transaction_type": "1",
            "model": "55",
            "issuance_type": "1",
            "ambiente": "2",
            "cliente": { "cnpj": "12345678000199", "name": "Fornecedor", "endereco": "...", "bairro": "...", "city": "...", "uf": "SP", "cep": "01001000" },
            "products": [ { "name": "...", "ncm": "...", "count": 1, "unit": "UN", "unit_price": 100, "total_price": 100, "category_id": "...", "origem": 0, "indicador_total": 1 } ]
          }
        }

code 发票发行完整示例

带运输的完整示例

{
  "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": "UN",
      "unit_price": 1500.00,
      "total_price": 3000.00,
      "category_id": "SEU_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 为必填。

vpn_key 认证

所有请求必须包含以下标头：

标头	类型	必需	描述
Content-Type	string	是	application/json;charset=utf-8
sign	string	是	请求的数字签名
timestamp	string	是	请求的UTC时间戳
token	string	是	认证令牌

注意： 要创建公司和获取公司列表，请使用分销商令牌（b2b_token）。

签名算法（SIGN）

static string GetSign(string AppKey, string Path, string bodyString, string timestamp)
{
    string input = AppKey + Path + bodyString + timestamp;
    using (MD5 md5 = MD5.Create())
    {
        byte[] inputBytes = Encoding.UTF8.GetBytes(input);
        byte[] hashBytes = md5.ComputeHash(inputBytes);
        
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < hashBytes.Length; i++)
        {
            sb.Append(hashBytes[i].ToString("x2"));
        }
        return sb.ToString();
    }
}

重要： 计算 sign 时，GET 请求的 Path 需要包含查询字符串。例如：/api/nfce/category/get_detail?category_id=TF123。POST 请求的 Path 仅为路径（如：/api/company/create）。

percent 详细税务参数

scale_balance ICMS参数

征税场景

padrao saida_fora_estado saida_dentro_estado entrada_fora_estado entrada_dentro_estado

税务状況（CST）

00：全额征税

02：免税

10：带ICMS征税

20：降低计算基数

30：免税或非征税

40：免税

41：非征税

50：暂停

51：延期

60：先前已征收ICMS

70：降低和征收

90：其他

pie_chart PIS/COFINS参数

征税场景

padrao saida_fora_estado saida_dentro_estado entrada_fora_estado entrada_dentro_estado

税务状況（CST）

01：征税操作（正常税率）

02：征税操作（差别税率）

03：征税操作（免税）

04：征税操作（暂停）

05：征税操作（ST）

06：征税操作（零税率）

07：免税操作

08：非征税操作

09：暂停征税操作

49：其他输出操作

50：抵免权（自身操作）

51：抵免权（採购）

52：贷方记录

53：借方记录

54：贷方记录（逾期）

55：借方记录（逾期）

56：推定抵免

60：推定抵免（採购）

61：推定抵免（进口）

62：推定抵免（农业活动）

63：推定抵免（其他）

64：推定抵免（非生成）

65：推定抵免（替代）

66：推定抵免（替代）

67：推定抵免（出口）

70：无抵免权的採购操作

71：免税採购操作

72：暂停採购操作

73：零税率採购操作

74：非征税採购操作

75：替代採购操作

98：其他输入操作

99：其他操作

💡 信息： tipo_pessoa字段接受fisica（自然人）或juridica（法人）值。对于PIS/COFINS，aliquota字段应格式化为带两位小数的字符串（例如："1.65"）。

credit_card 支付参数

支付指示器

`0`	现金
`1`	信用

支付方式

`01`	现金
`02`	支票
`03`	信用卡
`04`	借记卡
`05`	商店信用
`10`	餐券
`11`	餐饮券
`12`	礼品券
`13`	燃油券
`15`	银行票据
`90`	无支付
`99`	其他

卡品牌

`01`	Visa
`02`	Mastercard
`03`	American Express
`04`	Sorocred
`05`	Diners Club
`06`	Elo
`07`	Hipercard
`08`	Aura
`09`	Cabal
`99`	其他

bug_report XML问题排查

warning 拒绝 225 - XML Schema失败

当尝试取消、下载XML、作廢号码或对未在SEFAZ数据库中成功注册的NF-e进行声明时发生。

验证NF-e是否已获得授权（状态"已授权"）

如果未授权，重新发行NF-e

如果未使用，作廢号码

lightbulb SEFAZ在线验证

使用官方验证器识别XML问题：


                  https://www.sefaz.rs.gov.br/nfe/nfe-val.aspx

常见问题： 地址不完整，NCM无效，值格式错误，缺少必填字段。

error SEFAZ错误代码

代码	描述	解決方案
`217`	发行日期过于滞后	在应急情況下发行或正规化
`404`	收件人CNPJ/CPF无效	验证客户文档
`563`	操作不允许的CFOP	审查操作CFOP

其他端点

4. 列出类别： GET /api/category/get_list

5. 类别详情： GET /api/category/get_detail

6. 编辑类别： POST /api/category/edit

7. 删除类别： POST /api/category/delete

CFOP（操作财政代码）示例：

5102： 从第三方购买的商品销售 - 州内

6102： 从第三方购买的商品销售 - 州际

6108： 从第三方购买的商品销售 - 州际（自然人）

1000： 商品入库

speed

限制和速率限制

API使用政策

按计划限制

免费计划	100次请求/天
基础计划	1,000次请求/天
专业计划	10,000次请求/天
企业计划	定制

`transport_mode`的值：

0： 发货人承担运费（CIF）

1： 收货人承担运费（FOB）

2： 第三方承担运费

3： 发货人自有运输

4： 收货人自有运输

9： 无运输发生

CFOP（操作财政代码）示例：

5102： 从第三方购买的商品销售 - 州内

6102： 从第三方购买的商品销售 - 州际

6108： 从第三方购买的商品销售 - 州际（自然人）

1000： 商品入库

assessment NFe 报告

生成已开具电子发票（NF-e）的详细报告，支持按期间、状态和操作类型进行篩选。适用于财务监控、审计和管理控制。

1. 已开具发票报告

GET /api/invoice/report

请求参数（Query）

参数	必填	类型	描述
company_id	是	String	公司ID
start_date	是	Date	期间开始日期（YYYY-MM-DD）
end_date	是	Date	期间结束日期（YYYY-MM-DD）
status	否	String	按状态篩选：`AUTHORIZED`、 `CANCELED`、`DENIED`、 `ALL`（默认）
model	否	String	文件模型：`nfe`、 `nfce`、`all`（默认）
format	否	String	输出格式：`json`（默认）、 `csv`、`pdf`
page	否	Integer	页码（默认：1）
per_page	否	Integer	每页记录数（默认：50，最大：200）

请求示例

GET /api/invoice/report?company_id=comp_123456&start_date=2024-01-01&end_date=2024-01-31&status=AUTHORIZED&format=json

响应示例

{
  "success": true,
  "data": {
    "summary": {
      "total_invoices": 152,
      "total_value": 458320.50,
      "authorized": 145,
      "canceled": 5,
      "denied": 2
    },
    "invoices": [
      {
        "invoice_id": "nf_789012",
        "number": 1045,
        "series": 1,
        "access_key": "35210112345678901234...",
        "status": "AUTHORIZED",
        "issue_date": "2024-01-10T10:30:00Z",
        "total_value": 3000.00,
        "customer_name": "Empresa Cliente Ltda",
        "customer_document": "12.345.678/0001-99",
        "nature_of_operation": "VENDA",
        "model": "nfe"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total_pages": 4,
      "total_records": 152
    }
  }
}

2. 期间摘要报告

GET /api/invoice/report/summary

返回按月分组的财务操作合併摘要，包含价值、数量和税务总计。

请求参数（Query）

参数	必填	类型	描述
company_id	是	String	公司ID
year	是	Integer	参考年份（例：2024）
group_by	否	String	分组方式：`month`（默认）、 `week`、`day`

响应示例

{
  "success": true,
  "data": {
    "company_id": "comp_123456",
    "year": 2024,
    "periods": [
      {
        "period": "2024-01",
        "total_invoices": 152,
        "total_value": 458320.50,
        "total_tax": 82497.69,
        "authorized": 145,
        "canceled": 5,
        "denied": 2
      },
      {
        "period": "2024-02",
        "total_invoices": 178,
        "total_value": 523180.75,
        "total_tax": 94172.54,
        "authorized": 170,
        "canceled": 6,
        "denied": 2
      }
    ]
  }
}

3. 导出报告

POST /api/invoice/report/export

生成并导出PDF或CSV格式的完整报告。导出以异步方式处理，完成后返回下载URL。

请求负载

{
  "company_id": "comp_123456",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "format": "pdf",
  "status": "ALL",
  "include_details": true,
  "include_taxes": true
}

响应示例

{
  "success": true,
  "message": "报告处理中",
  "data": {
    "report_id": "rpt_abc123",
    "status": "processing",
    "estimated_time": "30s",
    "callback_url": "https://api.tffiscal.com/v1/report/status/rpt_abc123"
  }
}

处理完成后的响应

{
  "success": true,
  "data": {
    "report_id": "rpt_abc123",
    "status": "completed",
    "download_url": "https://storage.tffiscal.com/reports/rpt_abc123.pdf",
    "expires_at": "2024-02-01T23:59:59Z",
    "file_size": "2.4 MB"
  }
}

💡 提示：使用 format=csv 参数将数据与ERP系统或电子表格集成。 PDF格式适用于演示和财务审计。

⚠️ 注意：每次查询允许的最大期间为12个月。对于完整的年度报告，请使用导出端点（/report/export）。大量数据的查询可能需要几秒钟来处理。

vpn_key TF Hub全局认证

TF Hub的所有API都使用统一的认证系统。

必需标头

标头	值	描述
X-API-Key	字符串	仪表板提供的API密钥
X-Timestamp	Unix时间戳	请求时间戳（毫秒）
X-Signature	字符串	HMAC-SHA256签名

point_of_sale NFC-e — 电子消费者发票

Base URL (生产环境)

https://api.tffiscal.com

认证

Headers: sign, timestamp, token

要求

有效的A1数字证书 (.pfx 或 .p12)
CSC (纳税人安全码)
CSC ID (SEFAZ中的CSC标识符)

NFC-e（模型65）是面向最终消费者的零售电子税务文件，适用于现场销售或送货上门。它取代了旧的税务收据（ECF）。

NFC-e 特点：

始终为州内交易 — 无 DIFAL
无 IPI（工业产品税）
现场销售时收件人可选（ind_pres: "1"）
送货上门时收件人必填（ind_pres: "4"）
需要 CSC（纳税人安全码）用于生成二维码

认证

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

请求头	类型	说明
token	string	企业令牌（注册时获取）
sign	string	MD5 签名：`MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒），5分钟有效窗口

重要： 计算 sign 时，GET 请求的 path 需要包含查询字符串。例如：/api/nfce/category/get_detail?category_id=TF123。POST 请求的 path 仅为路径（如：/api/nfce/company/create）。

compare_arrows NFe 与 NFC-e — 集成商需要了解什么？

如果您已经集成了 NFe（模型55），那么集成 NFC-e（模型65） 非常类似。以下是您需要了解的关键差异。

apartment 企业注册

方面	NFe `/api/company/create`	NFC-e `/api/nfce/company/create`
基本字段	cnpj、name、alias、ie、invoice_type、地址、数字证书	与 NFe 相同 — 相同的必填字段
CSC	不使用	必填 — `csc_id` 和 `csc`（从 SEFAZ 门户获取）
系列号 / 编号	`serie` 和 `number`	`serie_nfce` 和 `number_nfce` — 与 NFe 独立编号
返回的令牌	相同的 `token` — 如果企业已存在，NFC-e 字段将自动添加

提示： 如果企业已注册 NFe，只需使用相同的 CNPJ 调用 /api/nfce/company/create。系统会识别已有企业并添加 NFC-e 字段（CSC、系列号、编号）。token 保持不变。

receipt_long 发票开具

方面	NFe `/api/invoice/create`	NFC-e `/api/nfce/create`
收件人	始终必填（CNPJ/CPF、姓名、完整地址）	现场销售可选；仅送货上门时必填（`ind_pres: "4"`）
在场指示符	不使用	必填 — `ind_pres`：`"1"` 现场，`"4"` 送货上门
计算的税种	ICMS、PIS、COFINS、IPI、DIFAL（跨州）	ICMS、PIS、COFINS — 无 IPI、无 DIFAL（始终州内交易）
CFOP	不固定（5xxx 州内、6xxx 跨州）	始终为 5xxx（州内交易）— 例如：`5102`
支付信息	可选	必填 — `pag_info` 包含支付方式（现金、PIX、银行卡等）
产品字段	相同 — 相同结构（codigo、name、ncm、count、unit、unit_price、total_price、category_id、cfop、origem）
取消	24小时内	30分钟内（各州不同）
DANFE	A4 PDF	热敏小票（80mm纸卷）带二维码

总结： 如果您已集成 NFe，集成 NFC-e 只需：

注册企业的 CSC（/api/nfce/company/create）
将开票接口切换为 /api/nfce/create
在请求体中添加 ind_pres 和 pag_info
移除 IPI/DIFAL 相关数据（如有）

POST /api/nfce/company/create

必需请求头

请求头	类型	说明
token	string	分销商令牌（b2b）
sign	string	MD5 签名
timestamp	string	秒级 Unix 时间戳

Body

字段	类型	说明
cnpj *	string	开票公司 CNPJ
cert_file *	string	A1 数字证书（.pfx 或 .p12）的 HTTPS URL
cert_pwd *	string	证书密码
csc_id *	string	SEFAZ 的 CSC（纳税人安全代码）ID
csc *	string	CSC 令牌（与 SEFAZ 共享的密钥）
serie_nfce	int	NFC-e 系列
number_nfce	int	NFC-e 初始编号
telefone	string	公司电话

* 必填字段。其他数据（名称、IE、地址等）通过 SintegraWS 从 CNPJ 自动提取。

载荷示例

        {
          "cnpj": "12345678000199",
          "cert_file": "https://example.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "telefone": "11999999999"
        }

响应

        {
          "success": true,
          "message": "NFC-e 公司已注册",
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/nfce/company/update

更新 NFC-e 公司数据

更新由 token 请求头标识的 NFC-e 公司。Body 中所有字段都是可选的 — 只发送要修改的字段。更新 cep 时，系统自动解析 stateCode 和 ibge。当 cert_file 和 cert_pwd 一起发送时，证书在保存前会经过验证。

必需请求头

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

Body（所有字段可选 — 至少发送 1 个）

字段	类型	说明
标识
name	string	公司名称
alias	string	商号
ie	string	州注册号
invoice_type	string	税务制度
email	string	电子邮件
telefone	string	电话
地址
cep	string	邮政编码（自动更新 `stateCode` 和 `ibge`）
address	string	街道地址
house_number	string	门牌号
complemento	string	补充
town	string	街区
city	string	城市
state	string	UF
NFC-e
csc_id	string	CSC ID
csc	string	CSC 令牌
serie_nfce	int	系列
number_nfce	int	下一个编号
cert_file	string	新 A1 证书（.pfx 或 .p12）的 HTTPS URL
cert_pwd	string	证书密码

Body 中至少 1 个字段必填。CNPJ 不可修改。

载荷示例

        {
          "alias": "Centro Store - Branch 02",
          "telefone": "11988888888",
          "serie_nfce": 2,
          "number_nfce": 1
        }

响应

        {
          "success": true,
          "message": "NFC-e 公司已成功更新"
        }

POST /api/nfce/company/get

查询 NFC-e 公司

返回由 token 请求头标识的 NFC-e 公司数据。注意：方法是 POST，但 body 中无字段 — 公司仅通过令牌解析。

必需请求头

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

Body

为空。可以发送 {}。

响应

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "cnpj": "12345678000199",
            "name": "Empresa Exemplo LTDA",
            "alias": "Centro Store",
            "ie": "123456789",
            "invoice_type": "simples_nacional",
            "email": "contact@company.com",
            "telefone": "11999999999",
            "cep": "01001000",
            "address": "Example Street",
            "house_number": "100",
            "complemento": "Room 5",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "state_code": "SP",
            "cert_file": "https://example.com/cert.pfx",
            "csc_id": "000001",
            "csc": "ABCDEF0123456789",
            "serie_nfce": 1,
            "number_nfce": 42
          }
        }

NFC-e 税种管理

税种定义了NFC-e开票时应用于产品的税务规则。与NFe不同，NFC-e仅适用于州内销售，因此结构更加简化：每种税只需一个对象，无需多个场景。

注意： NFC-e税种与NFe税种分开存储。每个税种包含ICMS、PIS、COFINS和IBS/CBS配置。本节所有接口均需在header中传入 token、sign 和 timestamp。

POST /api/nfce/category/create

创建 NFC-e 税务类目

创建一个 NFC-e 税务类目。每个类目只有单一场景(州内出库),ICMS、PIS、COFINS 和 IBS/CBS 使用扁平对象(不是数组,因为 NFC-e 不允许单一类目下有多个场景)。不包含 IPI。

必需请求头

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

Body(根)

字段	类型	说明
descricao *	string	类目描述
codigo_cfop *	string	CFOP 代码(如 5102、5405)
icms *	object	ICMS 配置(扁平对象)
pis *	object	PIS 配置(扁平对象)
cofins *	object	COFINS 配置(扁平对象)
ibs_cbs	object	IBS/CBS 配置(税制改革,可选)

icms

字段	类型	说明
situacao_tributaria *	string	CST/CSOSN(如 102、500)
aliquota_reducao	decimal	计税基础减免百分比
motivo_desoneracao	string	免税理由代码
aliquota_icms	array	各州税率:`[{ "estado": "SP", "aliquota": 18.00 }]`
aliquota_fcp	array	各州 FCP:`[{ "estado": "SP", "aliquota": 0.00 }]`
beneficio_fiscal	array	各州税收优惠:`[{ "estado": "SP", "codigo": "SP800001" }]`

pis / cofins

字段	类型	说明
situacao_tributaria *	string	PIS/COFINS 的 CST
aliquota *	string	百分比税率(如 "0.00"、"1.65"、"7.60")

ibs_cbs(可选)

字段	类型	说明
situacao_tributaria *	string	IBS/CBS 的 CST
classificacao_tributaria *	string	税务分类代码

* 必填字段。

请求示例

        {
          "descricao": "Bebidas não alcoólicas",
          "codigo_cfop": "5102",
          "icms": {
            "situacao_tributaria": "102",
            "aliquota_icms": [
              { "estado": "SP", "aliquota": 18.00 }
            ]
          },
          "pis": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "cofins": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "ibs_cbs": {
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001"
          }
        }

响应

        {
          "success": true,
          "data": {
            "category_id": "TF00001"
          }
        }

GET /api/nfce/category/get_detail

获取 NFC-e 税务类目详情

返回 NFC-e 税务类目的完整数据(描述、CFOP、ICMS、PIS、COFINS 和 IBS/CBS)。

必需请求头

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

查询参数

字段	类型	说明
category_id *	string	NFC-e 类目 ID

* 必填字段。

请求示例

GET /api/nfce/category/get_detail?category_id=TF00001

响应

        {
          "success": true,
          "data": {
            "category_id": "TF00001",
            "descricao": "Bebidas não alcoólicas",
            "codigo_cfop": "5102",
            "icms": {
              "situacao_tributaria": "102",
              "aliquota_icms": [
                { "estado": "SP", "aliquota": 18.00 }
              ],
              "aliquota_fcp": [
                { "estado": "SP", "aliquota": 0.00 }
              ],
              "beneficio_fiscal": [
                { "estado": "SP", "codigo": "SP800001" }
              ]
            },
            "pis": {
              "situacao_tributaria": "99",
              "aliquota": "0.00"
            },
            "cofins": {
              "situacao_tributaria": "99",
              "aliquota": "0.00"
            },
            "ibs_cbs": {
              "situacao_tributaria": "000",
              "classificacao_tributaria": "000001"
            }
          }
        }

GET /api/nfce/category/get_list

NFC-e 税务类目列表

返回已认证企业下注册的 NFC-e 税务类目的分页列表。

必需请求头

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

查询参数

字段	类型	说明
page *	int	页码(最小 1)
page_size *	int	每页条数(1~50)

* 必填字段。

请求示例

GET /api/nfce/category/get_list?page=1&page_size=20

响应

        {
          "success": true,
          "data": {
            "list": [
              { "category_id": "TF00001", "descricao": "Bebidas não alcoólicas" },
              { "category_id": "TF00002", "descricao": "Alimentos industrializados" }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST /api/nfce/category/edit

编辑 NFC-e 税务类目

注意: 与 /api/nfce/category/create 端点结构相同,但增加了必填字段 category_id。icms、pis、cofins 和 ibs_cbs 字段会被整体替换(不合并)。

必需请求头

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

额外字段

字段	类型	说明
category_id *	string	待编辑的类目 ID

* 必填字段。

请求示例

        {
          "category_id": "TF00001",
          "descricao": "Bebidas não alcoólicas — atualizado",
          "codigo_cfop": "5102",
          "icms": {
            "situacao_tributaria": "102",
            "aliquota_icms": [
              { "estado": "SP", "aliquota": 18.00 }
            ]
          },
          "pis": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "cofins": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "ibs_cbs": {
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001"
          }
        }

响应

        {
          "success": true,
          "data": {
            "category_id": "TF00001"
          }
        }

POST /api/nfce/category/delete

删除 NFC-e 税务类别

删除 NFC-e 税务类别。不可逆操作。绑定到此类别的产品仍会引用已删除的 category_id — 请先更新它们。

必需请求头

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

Body

字段	类型	说明
category_id *	string	要删除的 NFC-e 类别 ID

* 必填字段。

载荷示例

        {
          "category_id": "TF123"
        }

响应

        {
          "success": true
        }

POST /api/nfce/create

开具 NFC-e

开具 NFC-e(模型 65,始终为州内出库,无运输)。与 NFe 端点的主要区别:消费者对象名为 client(不是 cliente);地址号为 client.number;消费者为可选;不存在 impostos.ipi、shipping_address、delivery_address 或 transportation。pag_info 中的金额字段名为 amount。

必需请求头

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

Body(根)

字段	类型	说明
nature_of_operation *	string	操作性质(如 "商品销售")
issuance_type *	string	开具类型:"1"(正常)、"9"(NFC-e 离线应急)
ambiente *	string	"1" 生产、"2" 同源
products *	array	商品列表(详见下文)
id	string	外部标识符
ind_pres	string	买家出席:"1" 现场(默认)、"4" 上门配送、"5" 经营场所外现场、"9" 不适用
ind_intermed	string	"0" 无中介、"1" 市场平台。当 `ind_pres` = 2、3、4 时必填
total_discount_amount	decimal	发票总折扣
troco	decimal	找零金额
seguro	decimal	保险金额
outras_despesas	decimal	其他附加费用
informacoes_complementares	string	给消费者的补充信息
informacoes_fisco	string	给税务机关的信息
client	object	消费者数据(可选 — 见表格)
pag_info	array	付款(默认:现金 — 见表格)

client(可选)

仅在消费者已识别时填写。CPF 或 CNPJ 仅传数字。

字段	类型	说明
cpf	string	CPF(设定为自然人)
cnpj	string	CNPJ(法人)
ie	string	州登记号
name	string	姓名 / 法人名称
endereco	string	街道
number	string	地址号 (注意:与 NFe 不同,NFe 使用 `numero`)
complemento	string	补充
bairro	string	街区
city	string	城市
uf	string	州(若提供 CEP 则验证)
cep	string	邮政编码(仅数字)
telefone	string	电话
email	string	电子邮箱

products[](每项)

字段	类型	说明
name *	string	商品名称(CJK 字符会被剥离)
ncm *	string	NCM(8 位)
count *	decimal	数量
unit *	string	商业单位(如 "UN"、"KG")
unit_price *	decimal	单价
total_price *	decimal	项目总金额
origem *	int	商品原产地(0..8)
indicador_total *	int	1 = 计入发票总额;0 = 不计入
category_id ⚠	string	NFC-e 税务类目 ID(未发送 `impostos` 时必填)
impostos ⚠	object	手动税(`category_id` 的替代,无 IPI)
tax_info ⚠	object	`impostos` 的别名(结构相同)。仅在 `impostos` 缺失时使用
codigo	string	内部商品代码
cest	string	CEST
gtin	string	商业 GTIN/EAN
gtin_tributavel	string	应税 GTIN
discount_price	decimal	项目折扣
nItemPed	int	采购订单项目 (I61)。从根 `id` 取得的 `xPed` 所引用订单内的项目顺序号。有效范围: 1–999999。默认: 省略。

pag_info[](每项)

字段	类型	说明
payment_indicator *	string	"0" 现付、"1" 赊账
payment_method *	string	付款方式(01=现金、03=信用卡、04=借记卡、17=PIX、99=其他等)
amount	decimal	此方式支付的金额
card_info.integration_type	string	"1" 集成、"2" 未集成(卡 03/04 时必填)
card_info.brand_code	string	卡品牌(卡 03/04 时必填)
card_info.acquirer_cnpj	string	收单方 CNPJ
card_info.authorization_code	string	授权代码

* 必填字段。⚠ category_id、impostos 或 tax_info 三选一,必填。

简化示例

{
  "nature_of_operation": "Venda de mercadoria",
  "issuance_type": "1",
  "ambiente": "2",
  "ind_pres": "1",
  "client": {
    "cpf": "12345678909",
    "name": "Consumidor Final"
  },
  "products": [
    {
      "name": "Refrigerante 2L",
      "ncm": "22021000",
      "count": 2,
      "unit": "UN",
      "unit_price": 10.50,
      "total_price": 21.00,
      "origem": 0,
      "indicador_total": 1,
      "category_id": "TF00001"
    }
  ],
  "pag_info": [
    {
      "payment_indicator": "0",
      "payment_method": "17",
      "amount": 21.00
    }
  ]
}

完整示例(所有字段)

{
  "id": "PEDIDO-2026-0001",
  "nature_of_operation": "Venda de mercadoria",
  "issuance_type": "1",
  "ambiente": "2",
  "ind_pres": "1",
  "ind_intermed": "0",
  "total_discount_amount": 0.00,
  "troco": 0.00,
  "seguro": 0.00,
  "outras_despesas": 0.00,
  "informacoes_complementares": "Pedido entregue na loja",
  "informacoes_fisco": "ICMS recolhido conforme legislação",
  "client": {
    "cpf": "12345678909",
    "cnpj": "",
    "ie": "",
    "name": "Consumidor Final",
    "endereco": "Rua das Flores",
    "number": "100",
    "complemento": "Sala 5",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01001000",
    "telefone": "11999998888",
    "email": "cliente@exemplo.com"
  },
  "products": [
    {
      "codigo": "PROD001",
      "name": "Refrigerante 2L",
      "ncm": "22021000",
      "cest": "0300100",
      "gtin": "7891234567890",
      "gtin_tributavel": "7891234567890",
      "count": 2,
      "unit": "UN",
      "unit_price": 10.50,
      "total_price": 21.00,
      "discount_price": 0.00,
      "origem": 0,
      "indicador_total": 1,
      "category_id": "TF00001",
      "nItemPed": 1
    },
    {
      "codigo": "PROD002",
      "name": "Salgadinho 100g",
      "ncm": "19053100",
      "count": 1,
      "unit": "UN",
      "unit_price": 8.00,
      "total_price": 8.00,
      "origem": 0,
      "indicador_total": 1,
      "impostos": {
        "icms": {
          "codigo_cfop": "5102",
          "situacao_tributaria": "102",
          "industria": "",
          "tipo_pessoa": "juridica"
        },
        "pis": {
          "situacao_tributaria": "99",
          "aliquota": "0.00",
          "tipo_pessoa": "juridica"
        },
        "cofins": {
          "situacao_tributaria": "99",
          "aliquota": "0.00",
          "tipo_pessoa": "juridica"
        },
        "ibs_cbs": {
          "situacao_tributaria": "000",
          "tipo_pessoa": "juridica",
          "classificacao_tributaria": "000001"
        }
      }
    }
  ],
  "pag_info": [
    {
      "payment_indicator": "0",
      "payment_method": "03",
      "amount": 24.00,
      "card_info": {
        "integration_type": "1",
        "brand_code": "01",
        "acquirer_cnpj": "01234567000189",
        "authorization_code": "AUTH123456"
      }
    }
  ]
}

响应

        {
          "success": true,
          "data": {
            "uuid": "abc123...",
            "chave": "35..."
          }
        }

POST /api/nfce/cancel

取消 NFC-e

取消已授权的 NFC-e。与 NFe 不同，这里取消原因由客户提供并转发给 SEFAZ。SEFAZ 取消窗口很短（通常授权后 15-30 分钟）。

必需请求头

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

Body

字段	类型	说明
chave *	string	NFC-e 的 44 位访问密钥（注意：这里是 `chave`，而非其他端点中的 `uuid`）
motivo *	string	取消理由（SEFAZ 要求最少 15 个字符）

* 必填字段。

载荷示例

        {
          "chave": "35210112345678901234650010000000051234567890",
          "motivo": "Cancelamento por erro de operacao do caixa"
        }

GET /api/nfce/get_detail

查询 NFC-e 详情

通过 UUID 返回特定 NFC-e 的详情。包括 XML 和 DANFE（热敏小票）的 URL，以及提供时的客户数据。

必需请求头

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

查询字符串

参数	类型	说明
uuid *	string	NFC-e UUID

* 必填字段。

调用示例

GET /api/nfce/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9

响应

        {
          "success": true,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234650010000000051234567890",
            "serie": 1,
            "number": 5,
            "status": "Authorized",
            "modelo": "nfce",
            "total_price": 145.90,
            "nprot": "135210000123456",
            "motivo": "",
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave_nfce.pdf",
            "client_cpf": "12345678909",
            "client_cnpj": "",
            "client_name": "Cliente",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST /api/nfce/get_danfe

生成 / 获取 NFC-e DANFE（热敏小票）

返回 NFC-e DANFE（电子财政小票）的 PDF URL，包含用于 SEFAZ 查询的 QR 码。按需生成并按哈希（访问密钥 + 状态）缓存；重复调用返回现有 URL。

必需请求头

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

Body

字段	类型	说明
uuid *	string	NFC-e UUID（注意：这里是 `uuid`，与 `cancel` 使用的 `chave` 不同）

* 必填字段。

载荷示例

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

响应

        {
          "success": true,
          "data": {
            "danfe": "https://oss.example.com/.../chave_nfce.pdf"
          }
        }

codeNFC-e 完整示例

示例 1 — 现场销售（无收件人）

{
  "nature_of_operation": "Venda de mercadoria", "ambiente": "2", "ind_pres": "1",
  "products": [{ "codigo": "001", "name": "Refrigerante 350ml", "ncm": "22021000", "count": 3,
    "unit": "UN", "unit_price": 5.50, "total_price": 16.50, "category_id": "BEVERAGES",
    "origem": "0", "indicador_total": "1", "cfop": "5102" }],
  "pag_info": [{ "payment_indicator": "0", "payment_method": "17" }]
}

示例 2 — 送货上门（含收件人）

{
  "nature_of_operation": "Venda de mercadoria", "ambiente": "2", "ind_pres": "4",
  "client": { "cpf": "12345678900", "name": "Maria Silva", "endereco": "Rua das Flores",
    "number": "456", "bairro": "Jardim Primavera", "city": "São Paulo", "uf": "SP", "cep": "04567000" },
  "products": [{ "codigo": "PIZZA01", "name": "Pizza Grande Marguerita", "ncm": "19059090", "count": 1,
    "unit": "UN", "unit_price": 45.90, "total_price": 45.90, "category_id": "FOOD",
    "origem": "0", "indicador_total": "1", "cfop": "5102" }],
  "pag_info": [{ "payment_indicator": "0", "payment_method": "03" }],
  "frete": 8.00, "informacoes_complementares": "Entrega em até 40 minutos"
}

tune 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分钟窗口）

description NFS-e - 电子服务发票

NFS-e API 允许开具、取消和查询电子服务发票。系统自动检测公司所在城市并路由到正确的 API：

圣保罗 (SP) - 通过 Nota Fiscal Paulistana (SOAP) 开具
其他城市 - 通过国家 API (ADN/SEFIN) 开具

集成方无需担心使用哪个 API - 只需发送数据，系统会根据公司注册的城市 IBGE 代码自动路由。

端点	方法	描述
`/api/nfse/create`	POST	开具 NFS-e
`/api/nfse/cancel`	POST	取消 NFS-e
`/api/nfse/get_danfse`	POST	获取 DANFSE (PDF)
`/api/nfse/get_xml`	POST	下载 XML

POST /api/nfs/company/create

注册企业以开具 NFS-e

必需请求头

请求头	类型	说明
token	string	集成商 B2B token
sign	string	MD5 签名
timestamp	string	Unix 时间戳(秒)

Body

字段	类型	说明
cnpj *	string	企业 CNPJ(仅数字)
name *	string	法人名称
cep *	string	邮政编码(仅数字)
address *	string	街道
house_number *	string	地址号
town *	string	街区
city *	string	城市
state *	string	州(2 位,如 "SP")
cert_file *	string	A1 数字证书(.pfx)的 URL
cert_pwd *	string	数字证书密码
im *	string	市政登记号(Inscrição Municipal)
codigo_municipio_nfse *	string	开具市政的 IBGE 代码
codigo_servico_nfse *	string	默认服务代码(LC 116)
alias	string	商号
ie	string	州登记号
invoice_type	string	税务体制
unit	string	单位 / 分支
email	string	联系邮箱
telefone	string	电话
complemento	string	地址补充
cnae_nfse	string	默认活动 CNAE
serie_nfse	int	NFS-e 初始序列
number_nfse	int	NFS-e 初始编号
regime_especial_tributacao	int	特殊税制代码
optante_simples_nacional	bool	是否加入 Simples Nacional

* 必填字段。

请求示例

        {
          "cnpj": "43649380000100",
          "name": "Empresa Exemplo LTDA",
          "alias": "示例",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contact@example.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "示例街",
          "house_number": "86",
          "complemento": "2 楼",
          "town": "中心",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://storage.example.com/cert.pfx",
          "cert_pwd": "senha-do-certificado",
          "im": "12345678",
          "codigo_municipio_nfse": "3550308",
          "codigo_servico_nfse": "07498",
          "cnae_nfse": "6201501",
          "serie_nfse": 1,
          "number_nfse": 1,
          "regime_especial_tributacao": 0,
          "optante_simples_nacional": true
        }

响应

        {
          "success": true,
          "message": "Empresa cadastrada para NFS-e",
          "data": {
            "company_id": 12345,
            "token": "token-dedicado-da-empresa"
          }
        }

注意: 返回的 token 必须在其他 NFS-e 调用(/api/nfse/create、/cancel、/get_danfse、/get_xml)中使用。如果企业已存在,消息将为 "Empresa atualizada para NFS-e",返回的 token 是现有 token。

POST /api/nfse/create

开具 NFS-e

必需请求头

请求头	类型	描述
token	string	公司令牌
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒）（5分钟窗口）

请求体

{
  "ambiente": "1",
  "id": "REF-001",
  "descricao_servico": "Desenvolvimento de sistemas",
  "valor_servico": 10000.00,
  "aliquota_iss": 2.90,
  "iss_retido": false,
  "codigo_servico": "",
  "cnae": "",
  "valor_deducoes": 0,
  "desconto_incondicionado": 0,
  "desconto_condicionado": 0,
  "valor_iss": 0,
  "valor_pis": 0,
  "valor_cofins": 0,
  "valor_inss": 0,
  "valor_ir": 0,
  "valor_csll": 0,
  "tomador": {
    "cnpj": "43649380000100",
    "cpf": "",
    "name": "EMPRESA TOMADORA LTDA",
    "email": "contato@empresa.com",
    "telefone": "11999999999",
    "inscricao_municipal": "",
    "cep": "03027020",
    "endereco": "Rua Exemplo",
    "numero": "86",
    "complemento": "Andar 2",
    "bairro": "Centro",
    "city": "Sao Paulo",
    "uf": "SP",
    "codigo_municipio": "3550308"
  }
}

主要字段

字段	类型	描述
ambiente	string	`"1"` = 生产环境, `"2"` = 测试环境
id	string	外部参考 ID（可选）
descricao_servico	string	服务描述（必填）
valor_servico	decimal	服务总金额（R$）（必填）
aliquota_iss	decimal	ISS 税率（%）（例：2.90）
iss_retido	boolean	`false` = 未代扣, `true` = 由付款方代扣
valor_iss	decimal	ISS 值覆盖。如果大于 0,覆盖自动计算 (base_calculo × aliquota_iss ÷ 100)。默认:自动计算
codigo_servico	string	服务代码。留空则使用公司默认值
cnae	string	CNAE。留空则使用公司默认值
tomador	object	服务接受方数据（必填）

付款方字段

字段	类型	描述
cnpj	string	付款方 CNPJ（仅数字）
cpf	string	付款方 CPF（使用 cnpj 或 cpf）
name	string	名称/公司名（必填）
email	string	付款方邮箱
telefone	string	电话
cep	string	邮编（必填）
endereco	string	地址（必填）
numero	string	门牌号（必填）
complemento	string	补充地址
bairro	string	街区（必填）
city	string	城市
uf	string	州（2位）
codigo_municipio	string	IBGE 城市代码

成功响应

{
  "success": true,
  "data": {
    "_id": "661234abcdef...",
    "uuid": "guid-unico",
    "status": "autorizada",
    "nfse": "48",
    "serie": 1,
    "chave": "Z685RI9C",
    "codigoVerificacao": "Z685RI9C",
    "modelo": "nfse",
    "tipoEmissao": "paulistana",
    "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
  }
}

POST /api/nfse/cancel

取消 NFS-e

必需请求头

请求头	类型	描述
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

请求体

{
  "chave": "Z685RI9C",
  "motivo": "Cancelamento da NFS-e por erro na emissao"
}

字段

字段	类型	描述
chave	string	NFS-e 验证码（必填）
motivo	string	取消原因（必填，最少15个字符）

成功响应

{
  "success": true,
  "message": "Nota de servico cancelada com sucesso"
}

POST /api/nfse/get_danfse

获取 DANFSE (PDF)

必需请求头

请求头	类型	描述
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

请求体

{
  "chave": "Z685RI9C"
}

字段

字段	类型	描述
chave	string	NFS-e 验证码（必填）

响应

{
  "success": true,
  "data": {
    "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
  }
}

注意： 对于 Paulistana (SP)，返回市政厅的 PDF 直接 URL。对于国家 API，返回 base64 格式的 PDF。

POST /api/nfse/get_xml

下载 NFS-e XML

必需请求头

请求头	类型	描述
token	string	公司令牌
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

请求体

{
  "chave": "Z685RI9C"
}

字段

字段	类型	描述
chave	string	NFS-e 验证码（必填）

响应

{
  "success": true,
  "data": {
    "dpsXml": "<PedidoEnvioRPS>...</PedidoEnvioRPS>",
    "nfseXml": "<RetornoEnvioRPS>...</RetornoEnvioRPS>"
  }
}

dpsXml: 发送到市政厅/ADN 的 XML。 nfseXml: 包含开具结果的返回 XML。

POST /api/invoice/create

开具补充NFe（finalidade = 2）

必填请求头

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

Payload

{
  "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": "UN",
      "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"
    }
  ]
}

特定字段

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

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

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

成功响应

{
  "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

开具调整NFe（finalidade = 3）

必填请求头

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

Payload

{
  "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": "UN",
      "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"
    }
  ]
}

特定字段

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

可用的 finalidade 值：

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

补充与调整的区别：

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

edit_note 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）

向 SEFAZ 发送 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	更正文本（SEFAZ 限制：15–1000 个字符）

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

载荷示例

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "correcao": "Corrigir nome do destinatario para Empresa XYZ LTDA"
        }

响应

        {
          "success": true,
          "data": {
            "nProt": "135210000123456",
            "nSeqEvento": 1,
            "xml": "https://oss.example.com/.../cce.xml"
          }
        }

POST /api/invoice/cce/get_list

列出 NF-e 的 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 至少一个必填。

载荷示例

        {
          "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）

* 必填字段。

载荷示例

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

响应

        {
          "success": true,
          "data": {
            "url": "https://oss.example.com/.../cce_seq1.pdf"
          }
        }

POST /api/invoice/cce/download_xml

下载 CC-e XML

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

必需请求头

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

Body

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

* 必填字段。

载荷示例

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

响应

        {
          "success": true,
          "data": {
            "url": "https://oss.example.com/.../cce.xml"
          }
        }

how_to_reg 收件人表明 (Manifestação do Destinatário)

收件人表明允许 NF-e 的收件人对针对其 CNPJ 开具的发票正式表明立场。 SEFAZ 定义了 4 种事件类型，每种都有其法律含义。

事件类型

代码	名称	含义	理由
210210	操作知悉	收件人确认 NF-e 存在但尚未确认或拒绝。通常是发送的第一个事件，是通过 DistDFe 下载完整 XML 的前提条件。	非必填
210200	操作确认	收件人确认交易已发生且商品/服务已收到。最终事件，证明已收到。	非必填
210220	操作否认	收件人声明不承认该交易（涉嫌欺诈、CNPJ 被滥用等）。	必填（15-255 字符）
210240	操作未执行	收件人承认该交易但声明实际并未发生（退货、拒收等）。	必填（15-255 字符）

顺序规则：发送知悉（210210）后，可以发送确认（210200）或否认（210220）或未执行（210240）。确认/否认/未执行是最终状态，无法覆盖。

注意：cnpj 字段中发送的 CNPJ 必须是 NF-e 的收件人（表明者），且必须在与所用令牌绑定的系统中注册。否则 SEFAZ 将返回拒绝信息"事件作者与 NF-e 收件人不符"。

cStat 返回码

cStat	含义
135	✅ 事件已成功登记
573	✅ 事件重复 — 已经登记（视为成功）
236	❌ 无效的访问密钥
491	❌ 表明已登记 — 无法覆盖最终状态
596	❌ 收件人 CNPJ 与提供的不符
656	❌ 不当使用（速率限制）

POST /api/invoice/manifest

发送收件人表明事件

必需的头部

头部	类型	说明
token	string	公司令牌
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒，5 分钟窗口）

Payload

{
  "chave": "35260514200166000187550010000000011000000018",
  "cnpj": "14200166000187",
  "tipo_evento": 210210,
  "justificativa": "Operação reconhecida pelo destinatário"
}

字段

字段	类型	必填	说明
chave	string	是	NF-e 访问密钥 — 44 位
cnpj	string	是	收件人 CNPJ（表明者）— 14 位，无格式。必须在系统中注册
tipo_evento	int	是	事件代码：`210200`、`210210`、`210220` 或 `210240`
justificativa	string	有条件	对于 `210220` 和 `210240` 必填。15-255 字符。对于 `210200` 和 `210210` 被忽略

序列（nSeqEvento）：自动计算。对于相同的组合（cnpj + chave + tipo_evento），每次调用都会递增 — 因此重复将返回 cStat: 573 并被无错误地保存。

成功响应

{
  "success": true,
  "message": "data",
  "data": {
    "id": "67341a8f5d4e1f2a3b4c5d6e",
    "chave": "35260514200166000187550010000000011000000018",
    "cnpj": "14200166000187",
    "tipo_evento": 210210,
    "desc_evento": "Ciencia da Operacao",
    "nProt": "135260000123456",
    "cStat": 135,
    "xMotivo": "Evento registrado e vinculado a NF-e",
    "nSeqEvento": 1,
    "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
  }
}

响应字段

字段	类型	说明
id	string	表明记录的内部 ObjectId（在 `/get_xml` 中使用）
chave	string	表明的 NF-e 访问密钥
cnpj	string	表明的收件人 CNPJ
tipo_evento	int	发送的事件代码（210200/210210/210220/210240）
desc_evento	string	事件文本说明（SEFAZ 原文）
nProt	string	SEFAZ 协议号 — 事件回执
cStat	int	SEFAZ 状态码。`135` = 已登记，`573` = 重复（也被接受）
xMotivo	string	SEFAZ 描述性返回消息
nSeqEvento	int	自动分配的事件序列
xml_url	string	存储在 OSS 中的 procEvento XML（已签名并附协议）的公共 URL

示例 — 带理由的否认（210220）

{
  "chave": "35260514200166000187550010000000011000000018",
  "cnpj": "14200166000187",
  "tipo_evento": 210220,
  "justificativa": "Operação desconhecida pelo destinatário, sem pedido vinculado ao fornecedor informado"
}

POST /api/invoice/manifest/list

列出已发送的表明（历史记录）

必需的头部

头部	类型	说明
token	string	公司令牌
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒，5 分钟窗口）

Payload

{
  "cnpj": "14200166000187",
  "chave": "",
  "start_create_time": "01/05/2026",
  "end_create_time": "31/05/2026",
  "page": 1,
  "page_size": 20
}

字段

字段	类型	必填	说明
cnpj	string	否	按收件人 CNPJ 筛选。如省略，将列出用户所有 CNPJ 的记录
chave	string	否	按特定 NF-e 密钥（44 位）筛选
start_create_time	string/long	否	开始日期。接受格式：`"dd/MM/yyyy"`、`"yyyy-MM-dd"`、`"dd/MM/yyyy HH:mm:ss"` 或 Unix 时间戳（秒）。仅日期时按 00:00:00 UTC 处理
end_create_time	string/long	否	结束日期。相同格式。仅日期时按 23:59:59.999 UTC 处理
page	int	否	页码（默认 `1`）
page_size	int	否	每页项目数（默认 `20`，最大 `100`）

成功响应

{
  "success": true,
  "message": "成功",
  "data": {
    "total": 2,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": "67341a8f5d4e1f2a3b4c5d6e",
        "chave": "35260514200166000187550010000000011000000018",
        "cnpj": "14200166000187",
        "tipo_evento": 210210,
        "desc_evento": "Ciencia da Operacao",
        "justificativa": "Operação reconhecida pelo destinatário",
        "nProt": "135260000123456",
        "nSeqEvento": 1,
        "cStat": 135,
        "xMotivo": "Evento registrado e vinculado a NF-e",
        "xml_url": "https://storage.../...210210_1.xml",
        "create": "2026-05-13 14:25:33"
      }
    ]
  }
}

响应字段

字段	类型	说明
total	int	符合筛选条件的记录总数（与分页无关）
page	int	返回的当前页
page_size	int	返回的页大小
list[].id	string	记录的内部 ObjectId
list[].chave	string	表明的 NF-e 访问密钥
list[].cnpj	string	表明的收件人 CNPJ
list[].tipo_evento	int	事件代码（210200/210210/210220/210240）
list[].desc_evento	string	事件文本说明
list[].justificativa	string	发送的理由（仅 210220/210240 填充）
list[].nProt	string	事件的 SEFAZ 协议号
list[].nSeqEvento	int	事件序列
list[].cStat	int	SEFAZ 状态码
list[].xMotivo	string	SEFAZ 描述性返回消息
list[].xml_url	string	OSS 中 procEvento XML 的公共 URL
list[].create	string	记录的 UTC 时间戳（格式 `yyyy-MM-dd HH:mm:ss`）

排序：记录按从新到旧排序返回（按 create 降序）。

POST /api/invoice/manifest/get_xml

获取特定表明的 XML URL

必需的头部

头部	类型	说明
token	string	公司令牌
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒，5 分钟窗口）

Payload

{
  "id": "67341a8f5d4e1f2a3b4c5d6e"
}

字段

字段	类型	必填	说明
id	string	是	表明的 ObjectId — 由 `/manifest` 或 `/manifest/list` 返回

成功响应

{
  "success": true,
  "message": "data",
  "data": {
    "id": "67341a8f5d4e1f2a3b4c5d6e",
    "chave": "35260514200166000187550010000000011000000018",
    "tipo_evento": 210210,
    "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
  }
}

常见错误

消息	原因
id inválido	该值不是有效的 ObjectId
manifestação não encontrada	ObjectId 存在但不属于令牌的用户，或已删除

cloud_download DistDFe 捕获 — 接收的 NFe

通过 SEFAZ（国家环境）的 NFeDistribuicaoDFe 服务，可以查询和下载发送到您的 CNPJ 的 NFe 和事件。捕获按 NSU（唯一顺序号）增量进行 — 每次调用仅下载尚未捕获的内容。

返回的文档类型

doc_type	是什么	内容
resNFe	NFe 摘要	基本元数据（密钥、金额、发行方、状态）。在发送知悉事件之前到达 — 不包含产品/税务信息
procNFe	完整授权 NFe	完整的 NF-e XML（含产品、税务、运输等）。仅在收件人对该密钥发送知悉（210210）之后才可获得
resEvento	事件摘要	事件元数据（密钥、类型、序列、原因）
procEvento	完整事件	完整的事件 XML（CC-e、取消、其他收件人的表明等）

推荐流程：

调用 /received/sync — 下载所有新文档
使用 /received/list 并以 doc_type: "resNFe" 筛选查看未知悉的发票
对感兴趣的每个密钥，使用 tipo_evento: 210210 调用 /invoice/manifest
再次调用 /received/sync — 现在 SEFAZ 返回已表明密钥的 procNFe（完整 XML）
使用 /received/get_xml 获取 XML URL 并下载/处理

SEFAZ 速率限制：SEFAZ 允许每个 CNPJ 每小时最多调用 1 次 DistDFe。超出则返回 cStat: 656（不当使用）。在测试环境中，此规则更宽松。

DistDFe 返回的 cStat 代码

cStat	含义
137	✅ 未找到文档（循环正常结束）
138	✅ 找到文档 — 循环继续
656	❌ 不当使用 — 等待 1 小时后重试
252	❌ 环境与告知的不同（生产 vs 测试）
280	❌ 证书过期或无效

POST /api/invoice/received/sync

同步 — 通过 DistDFe 从 SEFAZ 下载新的 NFe/事件

必需的头部

头部	类型	说明
token	string	公司令牌
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒，5 分钟窗口）

Payload

{
  "cnpj": "26638419000167",
  "max_iterations": 50
}

字段

字段	类型	必填	说明
cnpj	string	是	收件人公司 CNPJ — 14 位，无格式。必须在与令牌绑定的系统中注册
max_iterations	int	否	每次执行的 SEFAZ 最大调用次数。每次调用最多下载 50 个文档。默认 `50`（约 2,500 个文档），最大 `200`

工作原理：

读取为该 (uid + cnpj) 持久化的最新 ultNSU
循环调用 SEFAZ，直到 cStat ≠ 138 或达到 max_iterations
解压返回的 XML（gzip）
将每个文档持久化到 w_invoice_received 并将 XML 上传到 OSS
更新 w_invoice_received_sync 中的 ultNSU 和 maxNSU
按 (uid + cnpj + nsu) 去重 — 重复调用不会重复

成功响应

{
  "success": true,
  "message": "data",
  "data": {
    "cnpj": "26638419000167",
    "uf": "SP",
    "initial_nsu": 0,
    "ult_nsu": 2323,
    "max_nsu": 2323,
    "pending": 0,
    "iterations": 8,
    "last_cstat": 137,
    "last_motivo": "Nenhum documento localizado",
    "stats": {
      "resNFe": 3,
      "procNFe": 4,
      "resEvento": 336,
      "procEvento": 5,
      "skipped": 0
    }
  }
}

响应字段

字段	类型	说明
cnpj	string	查询的收件人 CNPJ
uf	string	查询中使用的收件人州代码
initial_nsu	long	起始 NSU — 本次运行前最后处理的 NSU
ult_nsu	long	同步后新的最后 NSU
max_nsu	long	查询时 SEFAZ AN 中可用的最大 NSU
pending	long	仍待处理的文档 (`max_nsu - ult_nsu`)。如果 > 0，请再次调用 `/sync` 下载其余
iterations	int	本次执行中调用 SEFAZ 的次数
last_cstat	int	SEFAZ 返回的最后一个 cStat。`137` 是正常结束，`656` 是速率限制
last_motivo	string	SEFAZ 最后一次返回的描述性消息
stats.resNFe	int	本次运行下载的 NFe 摘要数
stats.procNFe	int	下载的完整 NFe 数
stats.resEvento	int	下载的事件摘要数
stats.procEvento	int	下载的完整事件数
stats.skipped	int	跳过的文档（重复或单个解析错误）

初始量：从未同步过的公司可能有数百到数千个历史文档。首次运行可能耗时较长，并可能因 max_iterations 而中断。检查响应中的 pending — 如果 > 0，请再次调用（遵守速率限制）。

POST /api/invoice/received/list

列出已捕获的文档（NFe 和事件）

必需的头部

头部	类型	说明
token	string	公司令牌
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒，5 分钟窗口）

Payload

{
  "cnpj": "26638419000167",
  "doc_type": "resNFe",
  "chave": "",
  "emitente_cnpj": "",
  "start_create_time": "01/05/2026",
  "end_create_time": "31/05/2026",
  "page": 1,
  "page_size": 20
}

字段

字段	类型	必填	说明
cnpj	string	否	按收件人 CNPJ（您的 CNPJ）筛选。如省略，将列出用户所有记录
doc_type	string	否	按文档类型筛选：`resNFe`、`procNFe`、`resEvento` 或 `procEvento`
chave	string	否	按访问密钥（44 位）筛选
emitente_cnpj	string	否	按 NF-e 发行方 CNPJ（供应商）筛选
start_create_time	string/long	否	开始日期。接受 `"dd/MM/yyyy"`、ISO 或 Unix 时间戳
end_create_time	string/long	否	结束日期。相同格式
page	int	否	页码（默认 `1`）
page_size	int	否	每页项目数（默认 `20`，最大 `100`）

成功响应

{
  "success": true,
  "message": "成功",
  "data": {
    "total": 3,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": "6a04a70d3201b5a62f3ac2f8",
        "nsu": 2318,
        "doc_type": "resNFe",
        "schema": "resNFe_v1.01.xsd",
        "chave": "35260563845920000120550020000085471156822656",
        "cnpj_destinatario": "26638419000167",
        "emitente_cnpj": "63845920000120",
        "emitente_nome": "MEGA ONLINE LTDA",
        "valor": 1.00,
        "dh_emi": "2026-05-13 14:05:35",
        "serie": 0,
        "number": 0,
        "tp_nf": 1,
        "c_sit_nfe": 3,
        "tp_evento": 0,
        "desc_evento": "",
        "n_seq_evento": 0,
        "dh_evento": null,
        "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml",
        "create": "2026-05-13 16:30:05"
      }
    ]
  }
}

响应字段

字段	类型	说明
total	int	符合筛选条件的记录总数
page	int	当前页
page_size	int	页大小
list[].id	string	内部 ObjectId（在 `/received/get_xml` 中使用）
list[].nsu	long	SEFAZ 分配给此文档的 NSU
list[].doc_type	string	文档类型：`resNFe`、`procNFe`、`resEvento`、`procEvento`
list[].schema	string	文档架构（例如 `resNFe_v1.01.xsd`）
list[].chave	string	NF-e 访问密钥（44 位）
list[].cnpj_destinatario	string	收件人 CNPJ（您的 CNPJ）
list[].emitente_cnpj	string	NF-e 发行方 CNPJ（供应商）
list[].emitente_nome	string	发行方公司名称
list[].valor	decimal	NF-e 总金额 (`vNF`)
list[].dh_emi	string	NF-e 开具日期/时间
list[].serie	int	NF-e 系列（仅 `procNFe` 填充）
list[].number	long	NF-e 编号（仅 `procNFe` 填充）
list[].tp_nf	int	操作类型：`0`=入库，`1`=出库（从发行方角度）
list[].c_sit_nfe	int	NF-e 状态（在 `resNFe` 中）：`1`=已授权，`2`=已拒绝，`3`=已取消
list[].tp_evento	int	事件代码（在 `resEvento`/`procEvento` 中）。例如：`110110`=CC-e，`110111`=取消，`210210`=知悉
list[].desc_evento	string	事件文本说明
list[].n_seq_evento	int	事件序列
list[].dh_evento	string	事件日期/时间（仅事件）
list[].xml_url	string	OSS 中文档 XML 的公共 URL
list[].create	string	捕获的 UTC 时间戳

排序：记录按 NSU 降序返回（最新优先）。

POST /api/invoice/received/get_xml

获取特定接收文档的 XML URL

必需的头部

头部	类型	说明
token	string	公司令牌
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒，5 分钟窗口）

Payload

{
  "id": "6a04a70d3201b5a62f3ac2f8"
}

字段

字段	类型	必填	说明
id	string	是	文档的 ObjectId — 由 `/received/list` 返回

成功响应

{
  "success": true,
  "message": "data",
  "data": {
    "id": "6a04a70d3201b5a62f3ac2f8",
    "nsu": 2318,
    "doc_type": "resNFe",
    "chave": "35260563845920000120550020000085471156822656",
    "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml"
  }
}

关于返回的 XML：

resNFe — XML 仅为摘要，不包含产品/税务。用于知悉前的审计/分类
procNFe — 完整签名 XML，与开具时生成的相同。可直接导入客户的 ERP
procEvento — 带签名和协议的完整事件 XML

常见错误

消息	原因
id inválido	该值不是有效的 ObjectId
documento recebido não encontrado	ObjectId 存在但不属于令牌的用户

POST /api/invoice/received/get_sync_status

查询当前 DistDFe 同步状态（不调用 SEFAZ）

必需的头部

头部	类型	说明
token	string	公司令牌
sign	string	MD5 签名: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒，5 分钟窗口）

Payload

{
  "cnpj": "26638419000167"
}

字段

字段	类型	必填	说明
cnpj	string	是	收件人公司 CNPJ — 14 位，无格式

响应 — 已同步的公司

{
  "success": true,
  "message": "成功",
  "data": {
    "cnpj": "26638419000167",
    "uf": "SP",
    "ult_nsu": 2323,
    "max_nsu": 2323,
    "pending": 0,
    "last_sync": "2026-05-13 16:30:05"
  }
}

响应 — 从未同步过的公司

{
  "success": true,
  "message": "成功",
  "data": {
    "cnpj": "26638419000167",
    "ult_nsu": 0,
    "max_nsu": 0,
    "pending": 0,
    "last_sync": null
  }
}

响应字段

字段	类型	说明
cnpj	string	查询的 CNPJ
uf	string	上次同步中使用的收件人州代码（如从未同步，则不存在）
ult_nsu	long	最后处理的 NSU。`0` = 从未同步
max_nsu	long	上次同步时 SEFAZ 中可用的最大 NSU
pending	long	待处理文档 (`max_nsu - ult_nsu`)。如果 > 0，则 SEFAZ 中有新文档
last_sync	string	上次成功同步的 UTC 日期/时间。如从未同步，则为 `null`

典型用法：在调用 /received/sync 之前调用此端点，以决定是否需要调用 SEFAZ。此端点不消耗 SEFAZ 速率限制 — 它仅读取本地 MongoDB 状态。

local_shipping MDF-e — 电子税务文档清单

MDF-e API(模型 58,PL-MDFe 3.00 布局)支持运输清单的开具、查询、取消和关闭。MDF-e 聚合与运输操作关联的 NF-e 和/或 CT-e,支持 4 种模式:公路、航空、水路和铁路。所有运营信息(司机、车辆、承包商、CIOT、通行券、付款)都在 /create 主体中 — 开具后没有新增/修改事件。

端点	方法	说明
`/api/mdfe/create`	POST	开具 MDF-e
`/api/mdfe/consult`	POST	查询 MDF-e 状态
`/api/mdfe/cancel`	POST	取消 MDF-e(授权后 24 小时内)
`/api/mdfe/close`	POST	关闭 MDF-e(行程结束后)

POST /api/mdfe/create

开具 MDF-e

从提交的主体中开具 MDF-e。serie、nMDF、cMDF、cDV、cUF、dhEmi、mod、tpEmis、procEmi、verProc 字段由服务器自动计算。客户端仅发送业务字段。

必需请求头

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

Body — 根

字段	类型	说明
ide *	object	MDF-e 标识
emit *	object	发行者数据
infModal *	object	模式信息(四个中仅一个:`rodo`、`aereo`、`aquav`、`ferrov`)
infDoc *	object	关联税务文档
tot *	object	货物合计
prodPred	object	主要货物产品
seg	array	保险信息
lacres	array	MDF-e 封条
autXML	array	授权访问 XML 的 CNPJ/CPF
infAdic	object	附加信息(税务机关和纳税人)
infRespTec	object	技术负责人(CNPJ、联系人、邮箱等)

ide — 标识

字段	类型	说明
tpAmb *	int	环境:`1`=生产,`2`=同源
tpEmit *	int	发行者类型:`1`=承运商,`2`=自有货物,`3`=运输服务提供商
modal *	string	模式:`"1"`=公路,`"2"`=航空,`"3"`=水路,`"4"`=铁路
UFIni *	string	行程开始的 UF(2 个字母)
UFFim *	string	行程结束的 UF
infMunCarrega[] *	array	装载市:`[{ cMunCarrega, xMunCarrega }]`
infPercurso[]	array	路线的 UF:`[{ UFPer }]`
tpTransp	string	承运商类型(公路)
dhIniViagem	string	行程开始日期/时间(ISO 8601)
indCanalVerde	string	绿色通道指示器
indCarregaPosterior	string	后续装载指示器

emit — 发行者

字段	类型	说明
CNPJ ⚠	string	发行者 CNPJ(14 位)
CPF ⚠	string	发行者 CPF(11 位)
IE	string	州登记号
xNome *	string	法人名称
xFant	string	商号
enderEmit	object	地址:`{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone, email }`

infModal — 公路模式(modal="1")

字段	类型	说明
rodo.veicTracao *	object	牵引车辆:`{ placa, tara, RENAVAM, capKG, capM3, tpRod, tpCar, UF, condutor[], prop }`
rodo.veicTracao.condutor[] *	array	司机:`[{ xNome, CPF }]` — 最少 1
rodo.veicReboque[]	array	拖车(与 veicTracao 相同结构,无司机)
rodo.infANTT	object	ANTT 信息:`{ RNTRC, infCIOT[], valePed, infContratante[], infPag[] }`
rodo.codAgPorto	string	港口预约代码
rodo.lacRodo[]	array	模式封条:`[{ nLacre }]`

infModal — 航空模式(modal="2")

字段	类型	说明
aereo.nac *	string	飞机国籍标志
aereo.matr *	string	飞机注册号
aereo.nVoo *	string	航班号
aereo.cAerEmb *	string	登机机场 IATA 代码
aereo.cAerDes *	string	目的机场 IATA 代码
aereo.dVoo *	string	航班日期(YYYY-MM-DD)

infModal — 水路模式(modal="3")

字段	类型	说明
aquav.irin *	string	船舶 IRIN
aquav.tpEmb *	string	船舶类型(2 位)。使用 ≥ 10 的值以避免 Zeus 内部 `byte` 截断(例:`"10"`、`"11"`)
aquav.cEmbar *	string	船舶代码
aquav.xEmbar *	string	船舶名称
aquav.nViag *	string	航次号。不能以零开头(schema 验证) — 使用 `"1"`、`"100"` 等。
aquav.cPrtEmb *	string	登船港代码
aquav.cPrtDest *	string	目的港代码
aquav.prtTrans	string	转运港
aquav.tpNav	string	航行类型
aquav.infTermCarreg[]	array	装载码头:`[{ cTermCarreg, xTermCarreg }]`
aquav.infTermDescarreg[]	array	卸载码头
aquav.infEmbComb[]	array	船队船舶:`[{ cEmbComb, xBalsa }]`
aquav.infUnidCargaVazia[]	array	空货物单元
aquav.infUnidTranspVazia[]	array	空运输单元

infModal — 铁路模式(modal="4")

字段	类型	说明
ferrov.trem *	object	火车数据:`{ xPref, dhTrem, xOri, xDest, qVag }`
ferrov.vag[] *	array	车厢:`[{ pesoBC, pesoR, tpVag, serie, nVag, nSeq, TU }]` — 最少 1。Zeus/SEFAZ 约束: `serie` 必须正好 3 位(使用 100+,例:`"100"`);`nVag` 仅接受数字(内部为 `long`,例:`"100001"`);`nSeq` 可选 1-3 位。

infDoc — 关联文档

字段	类型	说明
infMunDescarga[] *	array	卸货市 — 最少 1
infMunDescarga[].cMunDescarga *	string	市 IBGE 代码
infMunDescarga[].xMunDescarga *	string	市名称
infMunDescarga[].infNFe[]	array	关联 NF-e:`[{ chNFe, SegCodBarras, indReentrega, infUnidTransp[], peri[] }]`
infMunDescarga[].infCTe[]	array	关联 CT-e
infMunDescarga[].infMDFeTransp[]	array	运输 MDF-e(转包)

prodPred — 主要产品

字段	类型	说明
tpCarga *	string	货物类型:`"01"`=散装固体,`"02"`=散装液体,`"03"`=冷藏,`"04"`=集装箱,`"05"`=一般货物,`"06"`=新散装,`"07"`=危险品,`"08"`=加压散装
xProd *	string	主要产品描述
cEAN	string	GTIN/EAN
NCM	string	NCM
infLotacao	object	批次:`{ infLocalCarrega{CEP,latitude,longitude}, infLocalDescarrega{...} }`

tot — 合计

字段	类型	说明
vCarga *	decimal	货物总值(> 0)
cUnid *	string	单位代码:`"01"`=KG,`"02"`=TON
qCarga *	decimal	货物总量(> 0)
qCTe	int	Quantidade de 关联 CT-e
qNFe	int	关联 NF-e 数量
qMDFe	int	关联 MDF-e 数量

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

简化示例 — 公路模式

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "1",
            "UFIni": "SP",
            "UFFim": "ES",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ],
            "infPercurso": [
              { "UFPer": "MG" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "rodo": {
              "veicTracao": {
                "placa": "ABC1D23",
                "tara": 8000,
                "condutor": [
                  { "xNome": "João da Silva", "CPF": "12345678909" }
                ],
                "tpRod": "01",
                "tpCar": "01"
              }
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3205200",
                "xMunDescarga": "Vila Velha",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL"
          },
          "tot": {
            "vCarga": 50000.00,
            "cUnid": "01",
            "qCarga": 1500.00
          }
        }

简化示例 — 航空模式

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "2",
            "UFIni": "SP",
            "UFFim": "RJ",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA AEREA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV AEROPORTO",
              "nro": "5000",
              "xBairro": "CUMBICA",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "aereo": {
              "nac": "PT",
              "matr": "ABC1234",
              "nVoo": "AB1234",
              "cAerEmb": "GRU",
              "cAerDes": "GIG",
              "dVoo": "2026-05-21"
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3304557",
                "xMunDescarga": "Rio de Janeiro",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL"
          },
          "tot": {
            "vCarga": 25000.00,
            "cUnid": "01",
            "qCarga": 500.00
          }
        }

简化示例 — 水路模式

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "3",
            "UFIni": "SP",
            "UFFim": "PA",
            "infMunCarrega": [
              { "cMunCarrega": "3548500", "xMunCarrega": "SANTOS" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "NAVEGACAO EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV PORTUARIA",
              "nro": "200",
              "xBairro": "PORTO",
              "cMun": "3548500",
              "xMun": "SANTOS",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "aquav": {
              "irin": "1234567",
              "tpEmb": "10",
              "cEmbar": "1234",
              "xEmbar": "EMBARCACAO EXEMPLO",
              "nViag": "1",
              "cPrtEmb": "BRSSZ",
              "cPrtDest": "BRBEL"
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "1501402",
                "xMunDescarga": "Belém",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "01",
            "xProd": "GRAOS DE SOJA"
          },
          "tot": {
            "vCarga": 500000.00,
            "cUnid": "02",
            "qCarga": 50.00
          }
        }

简化示例 — 铁路模式

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "4",
            "UFIni": "MG",
            "UFFim": "SP",
            "infMunCarrega": [
              { "cMunCarrega": "3106200", "xMunCarrega": "BELO HORIZONTE" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "FERROVIA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV FERROVIARIA",
              "nro": "300",
              "xBairro": "INDUSTRIAL",
              "cMun": "3106200",
              "xMun": "BELO HORIZONTE",
              "UF": "MG"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "ferrov": {
              "trem": {
                "xPref": "F123",
                "dhTrem": "2026-05-21T08:00:00-03:00",
                "xOri": "BELO HORIZONTE",
                "xDest": "SANTOS",
                "qVag": 2
              },
              "vag": [
                {
                  "pesoBC": 30.000,
                  "pesoR": 30.000,
                  "tpVag": "Gôndola",
                  "serie": "100",
                  "nVag": "100001",
                  "nSeq": "1",
                  "TU": 28.000
                },
                {
                  "pesoBC": 30.000,
                  "pesoR": 30.000,
                  "tpVag": "Gôndola",
                  "serie": "101",
                  "nVag": "100002",
                  "nSeq": "2",
                  "TU": 28.000
                }
              ]
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3548500",
                "xMunDescarga": "Santos",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "01",
            "xProd": "MINERIO DE FERRO"
          },
          "tot": {
            "vCarga": 800000.00,
            "cUnid": "02",
            "qCarga": 56.00
          }
        }

完整示例(所有字段) — 公路模式

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "tpTransp": "1",
            "modal": "1",
            "UFIni": "SP",
            "UFFim": "ES",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ],
            "infPercurso": [
              { "UFPer": "MG" }
            ],
            "dhIniViagem": "2026-05-21T08:00:00-03:00",
            "indCanalVerde": "1",
            "indCarregaPosterior": "0"
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA EXEMPLO LTDA",
            "xFant": "Exemplo Transportes",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xCpl": "GALPAO A",
              "xBairro": "CENTRO",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "01001000",
              "UF": "SP",
              "fone": "1133334444",
              "email": "contato@exemplo.com"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "rodo": {
              "infANTT": {
                "RNTRC": "12345678",
                "infCIOT": [
                  { "CIOT": "1234567890", "CNPJ": "12345678000199" }
                ],
                "valePed": {
                  "categCombVeic": "01",
                  "disp": [
                    {
                      "CNPJForn": "98765432000111",
                      "CNPJPg": "12345678000199",
                      "nCompra": "VP001",
                      "vValePed": 250.00,
                      "tpValePed": "01"
                    }
                  ]
                },
                "infContratante": [
                  {
                    "xNome": "EMPRESA CONTRATANTE LTDA",
                    "CNPJ": "11222333000144"
                  }
                ],
                "infPag": [
                  {
                    "xNome": "João da Silva",
                    "CPF": "12345678909",
                    "Comp": [
                      { "tpComp": "01", "vComp": 5000.00, "xComp": "Frete contratado" }
                    ],
                    "vContrato": 5000.00,
                    "indAltoDesemp": "1",
                    "indPag": "0",
                    "infBanc": {
                      "codBanco": "001",
                      "codAgencia": "1234",
                      "PIX": "12345678909"
                    }
                  }
                ]
              },
              "veicTracao": {
                "cInt": "VT001",
                "placa": "ABC1D23",
                "RENAVAM": "12345678901",
                "tara": 8000,
                "capKG": 25000,
                "capM3": 80,
                "prop": {
                  "CNPJ": "12345678000199",
                  "RNTRC": "12345678",
                  "xNome": "TRANSPORTADORA EXEMPLO LTDA",
                  "IE": "123456789012",
                  "UF": "SP",
                  "tpProp": "0"
                },
                "condutor": [
                  { "xNome": "João da Silva", "CPF": "12345678909" },
                  { "xNome": "Maria Souza", "CPF": "98765432100" }
                ],
                "tpRod": "01",
                "tpCar": "01",
                "UF": "SP"
              },
              "veicReboque": [
                {
                  "cInt": "VR001",
                  "placa": "DEF4G56",
                  "RENAVAM": "98765432109",
                  "tara": 3500,
                  "capKG": 30000,
                  "capM3": 90,
                  "tpCar": "02",
                  "UF": "SP"
                }
              ],
              "lacRodo": [
                { "nLacre": "LACRE001" },
                { "nLacre": "LACRE002" }
              ]
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3205200",
                "xMunDescarga": "Vila Velha",
                "infNFe": [
                  {
                    "chNFe": "35260512345678000199550010000000011000000018",
                    "SegCodBarras": "",
                    "indReentrega": "0",
                    "infUnidTransp": [
                      {
                        "tpUnidTransp": "1",
                        "idUnidTransp": "UT001",
                        "qtdRat": 100.000,
                        "lacUnidTransp": [{ "nLacre": "LACRE-UT-001" }],
                        "infUnidCarga": [
                          {
                            "tpUnidCarga": "1",
                            "idUnidCarga": "UC001",
                            "qtdRat": 100.000,
                            "lacUnidCarga": [{ "nLacre": "LACRE-UC-001" }]
                          }
                        ]
                      }
                    ],
                    "peri": []
                  }
                ]
              }
            ]
          },
          "seg": [
            {
              "infResp": {
                "respSeg": "1",
                "CNPJ": "12345678000199"
              },
              "infSeg": {
                "xSeg": "SEGURADORA EXEMPLO SA",
                "CNPJ": "55666777000188"
              },
              "nApol": "APOL-2026-001",
              "nAver": ["AV001", "AV002"]
            }
          ],
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL",
            "cEAN": "7891234567890",
            "NCM": "84713012",
            "infLotacao": {
              "infLocalCarrega": {
                "CEP": "01001000",
                "latitude": "-23.5505",
                "longitude": "-46.6333"
              },
              "infLocalDescarrega": {
                "CEP": "29100000",
                "latitude": "-20.3297",
                "longitude": "-40.2925"
              }
            }
          },
          "tot": {
            "qCTe": 0,
            "qNFe": 1,
            "qMDFe": 0,
            "vCarga": 50000.00,
            "cUnid": "01",
            "qCarga": 1500.00
          },
          "lacres": [
            { "nLacre": "LACRE-GERAL-001" }
          ],
          "autXML": [
            { "CNPJ": "11222333000144" }
          ],
          "infAdic": {
            "infAdFisco": "Documento emitido em conformidade com a legislação vigente",
            "infCpl": "Transporte com escolta armada"
          },
          "infRespTec": {
            "CNPJ": "12345678000199",
            "xContato": "Suporte Técnico",
            "email": "suporte@exemplo.com",
            "fone": "1133334444"
          }
        }

成功响应

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "nMDF": 1,
            "serie": 1,
            "protocolo": "135260000123456",
            "xml": "https://storage.../mdfe/2026-05-21/35260512345678000199580010000000011000000018.xml"
          }
        }

POST /api/mdfe/consult

查询 MDF-e 状态

使用访问密钥直接在 SEFAZ 查询 MDF-e 状态。

必需请求头

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

Body

字段	类型	说明
chMDFe *	string	MDF-e 访问密钥(44 位)

* 必填字段。

请求示例

        {
          "chMDFe": "35260512345678000199580010000000011000000018"
        }

响应

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 100,
            "xMotivo": "Autorizado o uso do MDF-e",
            "protocolo": "135260000123456",
            "dhRecbto": "2026-05-21T10:30:00-03:00",
            "encerrado": false,
            "cancelado": false
          }
        }

POST /api/mdfe/cancel

取消 MDF-e

取消已授权的 MDF-e。窗口: 授权后最多 24 小时。如果 MDF-e 已关闭,则不允许。

必需请求头

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

Body

字段	类型	说明
chMDFe *	string	MDF-e 访问密钥(44 位)
xJust *	string	取消理由(根据 SEFAZ 要求最少 15 个字符)

* 必填字段。

请求示例

        {
          "chMDFe": "35260512345678000199580010000000011000000018",
          "xJust": "Cancelamento por erro no preenchimento dos dados do veiculo"
        }

响应

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a MDF-e",
            "nProt": "135260000123457",
            "dhRegEvento": "2026-05-21T11:00:00-03:00"
          }
        }

POST /api/mdfe/close

关闭 MDF-e

在行程结束时关闭 MDF-e。关闭后,无法再取消。dtEnc、cUF 和 cMun 字段是可选的 — 省略时,系统将从原始 MDF-e 推断(当前日期、发行人的 UF 和市)。

必需请求头

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

Body

字段	类型	说明
chMDFe *	string	MDF-e 访问密钥(44 位)
dtEnc	string	关闭日期(YYYY-MM-DD)。默认:当前日期
cUF	int	关闭发生地 UF 的 IBGE 代码。默认:发行者的 UF
cMun	string	市 IBGE 代码 onde ocorreu o encerramento. Default: município do emitente

* 必填字段。

请求示例

        {
          "chMDFe": "35260512345678000199580010000000011000000018",
          "dtEnc": "2026-05-22",
          "cUF": 32,
          "cMun": "3205200"
        }

响应

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a MDF-e",
            "nProt": "135260000123458",
            "dhRegEvento": "2026-05-22T18:00:00-03:00"
          }
        }

vpn_key SSO — 通过令牌自动登录

基础 URL（生产）

https://api.tffiscal.com

认证

Headers: sign, timestamp, token

票据有效期

60 秒 — 一次性使用

SSO（单点登录）允许您的 ERP 为用户生成直接访问 TFiscal 的链接，用户无需输入凭据即可以所选语言自动登录到相应的公司。

工作原理：

ERP 调用 POST /api/sso/create_ticket 并发送公司令牌。
TFiscal 返回一个包含一次性不透明票据的 redirectUrl。
ERP 将用户浏览器重定向到该 URL。
页面消费票据后，用户自动登录到公司面板。

⚠️ 安全： 真实的公司令牌永远不会出现在 URL 中。仅将短期票据（有效期 60 秒，一次性）暴露给浏览器。

POST /api/sso/create_ticket

生成自动登录链接

生成一个一次性票据，可在 60 秒内使用，将用户自动登录到与该令牌对应的公司面板。

必需的 Headers

Header	类型	描述
token	string	公司令牌（与开具 NF-e 使用的相同）
sign	string	MD5 签名：`MD5(token + path + body + timestamp)`
timestamp	string	Unix 秒级时间戳（5 分钟窗口）

Payload

{
  "token": "TOKEN_DA_EMPRESA",
  "language": "br",
  "page": "emitir_nfe"
}

字段

字段	必填	类型	描述
token	是	string	公司令牌（`w_company.token`）— 与 `/api/invoice/create` 使用的相同
language	否	string	界面语言：`br`、`en`、`zh`、`es`、`ja`、`ko`。默认：`br`
page	否	string	登录后的着陆页。接受的值：`emitir_nfe`。为空或缺失时打开默认面板（`/company/kanban`）。

成功响应

{
  "success": true,
  "message": "ticket",
  "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
  "redirectUrl": "https://www.tffiscal.com/sso#ticket=nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
  "expiresInSeconds": 60,
  "expiresAt": "2026-04-24T18:34:56.0000000Z"
}

响应字段

字段	类型	描述
success	boolean	成功生成票据时为 `true`
ticket	string	不透明票据（随机，32 字节 base64url）
redirectUrl	string	ERP 应将用户浏览器重定向到的完整 URL
expiresInSeconds	number	有效期秒数（始终为 60）
expiresAt	string	UTC 过期时间（ISO 8601）

错误响应

消息	原因
`Token 为必填项`	body 中未发送 `token` 字段
`无效的 Token`	令牌与任何已注册的公司不匹配
`此令牌绑定了多家公司。请发送您要访问的特定公司令牌。`	集成商令牌绑定了多家公司 — 请发送具体公司的令牌
`Rate limit exceeded`	同一令牌每分钟调用超过 30 次

POST /api/sso/consume_ticket

消费票据并获取会话 JWT

将 /api/sso/create_ticket 生成的票据兑换为 TFiscal 会话 JWT。此端点由前端(路由 /sso)调用,不需要 sign/timestamp 请求头 — 不透明的票据本身就是凭证。每个票据只能消费一次,60 秒后过期。

Body

字段	类型	说明
ticket *	string	`create_ticket` 返回的票据

* 必填字段。

请求示例

        {
          "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg"
        }

成功响应

        {
          "success": true,
          "message": "Login succeeded",
          "access_token": "eyJhbGciOi...",
          "type": "user",
          "uid": 1234,
          "company_id": 5678,
          "language": "br",
          "page": "emitir_nfe"
        }

响应字段

字段	类型	说明
access_token	string	会话 JWT(有效期 365 天)。在 TFiscal 调用的 `Authorization` 请求头中使用
type	string	用户类型(`user`、`admin` 等)
uid	int	内部用户 ID
company_id	int	`create_ticket` 中选择的企业 ID
language	string	`create_ticket` 中选择的语言(始终规范化)
page	string	目标页面(未设置时为空字符串)

错误响应

消息	原因
`Ticket inválido`	Body 中没有 `ticket` 字段
`Ticket inválido ou expirado`	票据不存在、已被消费或超过 60 秒过期时间
`Rate limit exceeded`	同一 IP 每分钟消费超过 60 次
`Sessão inválida`	关联到该票据的用户不再存在

lock 限制与安全

票据特性

特性	值
有效期	生成后 60 秒
使用	一次性 — 消费后无法重用
速率限制	每个令牌每分钟 30 个票据 · 每个 IP 每分钟 60 次消费
存储	具有自动 TTL 的 MongoDB — 过期票据自动删除

导航限制

通过 SSO 认证的用户仅有权访问相应公司的页面（/invoice/company/*）。尝试访问其他区域（分销商面板、综合报表、管理）将自动重定向到公司面板。

登录后的会话

在将票据交换为 JWT 后，用户拥有 TFiscal 的正常会话（JWT 有效期 365 天，与传统登录相同）。60 秒仅是生成票据和打开链接之间的时间窗口 — 之后用户将保持正常登录直到注销。

⚠️ 重要： create_ticket 必须由 ERP 仅在服务器端调用。切勿直接从浏览器调用此端点 — 这会在前端暴露公司令牌。

badge 会计师(Contador)

用于查询与企业绑定的会计师注册数据的 API。适用于需要获取负责某企业会计师完整资料的外部财务系统。

POST /api/accountant/get_info

获取与企业绑定的会计师信息

返回与指定企业绑定的会计师的完整注册数据。会计师必须事先绑定到该企业(相同 CNPJ),且提供的邮箱必须与注册一致。

必需请求头

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

Body

字段	类型	说明
companyId *	int	绑定到 token 的企业 ID
accountantId *	string	会计师 ObjectId(24 位十六进制)
email *	string	会计师邮箱(必须与注册一致)

* 必填字段。

请求示例

      {
        "companyId": 12345,
        "accountantId": "5f3a8b9c1d2e4f5a6b7c8d9e",
        "email": "accountant@office.com"
      }

成功响应

      {
        "success": true,
        "data": {
          "email": "accountant@office.com",
          "officeDocumentType": "CNPJ",
          "officeDocument": "12345678000199",
          "officeName": "会计事务所 LTDA",
          "responsibleName": "张 三",
          "crc": "SP123456/O-7",
          "accountantCpf": "12345678909",
          "workAddress": "示例街 100 - 中心 - São Paulo/SP",
          "site": "https://office.com",
          "landline": "1133334444",
          "mobile": "11999998888",
          "assistantName": "李 四",
          "assistantEmail": "lisi@office.com",
          "assistantPhone": "11988887777",
          "observations": "周一至周五,9 点至 18 点"
        }
      }

响应字段

字段	类型	说明
email	string	会计师主邮箱
officeDocumentType	string	事务所证件类型:"CNPJ" 或 "CPF"
officeDocument	string	事务所证件(仅数字)
officeName	string	事务所法人名 / 名称
responsibleName	string	负责会计师姓名
crc	string	CRC 号(巴西地区会计委员会)
accountantCpf	string	会计师 CPF(仅数字)
workAddress	string	办公地址
site	string	事务所网站
landline	string	固定电话
mobile	string	手机
assistantName	string	助理姓名
assistantEmail	string	助理邮箱
assistantPhone	string	助理电话
observations	string	注册自由备注

错误响应

消息	原因
会计师ID参数异常或不存在	`accountantId` 缺失或不是有效的 ObjectId
该会计师邮箱异常或不存在	`email` 无效或未注册
发票账号{companyId}异常或不存在	`companyId` 不属于该 token 用户
该会计师未绑定该发票账号	会计师未绑定到指定企业

NFE API 文档

API重要字段

发票发行流程

1. 创建公司

2. 信息推送

3. 发行发票

4. 返回结果

5. 生成文件

税务验证

成功

失败

端点快速参考

成功

客户端错误

服务器错误

NFE API

sync_alt 系统流程

input 输入数据

settings 处理

download 输出

主要端点

必需请求头

Body

载荷示例

响应

必需请求头

Body

载荷示例

响应

必需请求头

Body

载荷示例

响应

必需请求头

查询字符串

调用示例

响应

必需请求头

调用示例

响应

必需请求头

查询字符串

调用示例

响应

必需请求头

调用示例

响应

响应示例

必需请求头

Body — 顶层字段

Body — cliente（对象，必填）

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

Body — products[].impostos / products[].tax_info

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

Body — products[].import_declarations[]

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

Body — transportation（对象，可选）

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

简化示例

完整示例(所有字段)

必需请求头

查询字符串

调用示例

响应

必需请求头

查询字符串

调用示例

响应

必需请求头

Body

载荷示例

必需请求头

Body

载荷示例

必需请求头

Body

载荷示例

必需请求头

Body

请求示例

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

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

Body — `products[].impostos` / `products[].tax_info`

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

Body — `products[].import_declarations[]`

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

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

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

Body — `icms[]`

Body — `ipi[]`

Body — `pis[]` 和 `cofins[]`（相同结构）

Body — `ibs_cbs[]`（税制改革）

Body — `is[]`（选择税）