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方法	功能
business 公司管理
`/api/company/create`	POST	注册开票公司
`/api/company/get_detail`	GET	查询公司详情
`/api/company/edit`	POST	编辑公司数据
`/api/company/get_list`	GET	列出公司
`/api/company/v2/create`	POST	使用证书注册公司（简化版）
`/api/company/get_cep_detail`	GET	通过 CEP 查询地址
`/api/company/get_export_invoice_month_files`	GET	列出每月导出文件
category 税务类别
`/api/category/get_list`	GET	列出税务类别
`/api/category/create`	POST	创建税务类别
`/api/category/get_detail`	GET	查询税务类别详情
`/api/category/edit`	POST	编辑税务类别
`/api/category/delete`	POST	删除税务类别
receipt_long NF-e 发票管理
`/api/invoice/create`	POST	开具发票
`/api/invoice/get_list`	GET	列出发票
`/api/invoice/get_detail`	GET	查询发票详情
`/api/invoice/refresh`	POST	更新发票状态
`/api/invoice/cancel`	POST	取消发票
`/api/invoice/invalid`	POST	作废发票编号
`/api/invoice/return`	POST	开具退货发票
`/api/invoice/get_xml`	POST	导出发票 XML
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
`/api/nfce/get_list`	GET	列出NFC-e（分页）
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
`/api/nfse/get_list`	GET	列出NFS-e（分页）
`/api/nfs/company/create`	POST	注册用于开具NFS-e的公司
receipt_long NF-e — 事件与查询
`/api/invoice/get_danfe`	POST	获取NF-e的DANFE（PDF）
`/api/invoice/consultar_status`	POST	在SEFAZ查询NF-e/NFC-e状态
`/api/invoice/validar_cpf_cnpj`	POST	在联邦税务局数据库校验CPF/CNPJ
`/api/invoice/cce/send`	POST	发送更正函（CC-e）
`/api/invoice/cce/get_list`	POST	列出某张NF-e的CC-e
`/api/invoice/cce/download_pdf`	POST	下载CC-e的PDF
`/api/invoice/cce/download_xml`	POST	下载CC-e的XML
mark_email_read NF-e — 表明与接收的发票
`/api/invoice/manifest`	POST	发送收件人表明事件
`/api/invoice/manifest/list`	POST	列出已发送的表明
`/api/invoice/manifest/get_xml`	POST	获取某次表明的XML
`/api/invoice/received/sync`	POST	同步接收的NF-e/事件（DistDFe）
`/api/invoice/received/list`	POST	列出接收的文档
`/api/invoice/received/get_xml`	POST	获取接收文档的XML
`/api/invoice/received/get_sync_status`	POST	查询DistDFe同步状态
category NFC-e — 税务类别
`/api/nfce/category/create`	POST	创建NFC-e税务类别
`/api/nfce/category/edit`	POST	编辑NFC-e税务类别
`/api/nfce/category/delete`	POST	删除NFC-e税务类别
`/api/nfce/category/get_detail`	GET	获取NFC-e类别详情
`/api/nfce/category/get_list`	GET	列出NFC-e税务类别
local_shipping MDF-e（电子税务文档清单）
`/api/mdfe/create`	POST	开具MDF-e
`/api/mdfe/consult`	POST	查询MDF-e状态
`/api/mdfe/cancel`	POST	取消MDF-e
`/api/mdfe/close`	POST	关闭MDF-e
`/api/mdfe/get_list`	GET	列出MDF-e（分页）
inventory_2 DC-e（电子内容声明）
`/api/dce/create`	POST	开具DC-e
`/api/dce/consult`	POST	查询DC-e状态
`/api/dce/cancel`	POST	取消DC-e
`/api/dce/pdf`	POST	获取DC-e的DACE（PDF）
`/api/dce/get_list`	GET	列出DC-e（分页）
local_shipping CT-e（电子运输凭证）
`/api/cte/create`	POST	开具CT-e
`/api/cte/cancel`	POST	取消CT-e
`/api/cte/cce`	POST	更正函（CC-e）
`/api/cte/desacordo`	POST	服务异议
`/api/cte/consult`	POST	查询CT-e状态
`/api/cte/inutilize`	POST	作废编号区间
`/api/cte/get_list`	GET	列出CT-e（分页）
vpn_key SSO（自动登录）
`/api/sso/create_ticket`	POST	生成自动登录链接
`/api/sso/consume_ticket`	POST	消费票据并获取会话JWT
account_balance 会计师
`/api/accountant/get_info`	POST	获取与企业绑定的会计师信息

📋 重要说明：

所有端点都需要通过标头进行认证： 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	编号的初始值
运输 (MDF-e / CT-e / DC-e)
serie_mdfe	int	MDF-e 系列
number_mdfe	int	MDF-e 起始编号（编号从此处开始）
serie_cte	int	CT-e 系列
number_cte	int	CT-e 起始编号（编号从此处开始）
serie_dce	int	DC-e 系列
number_dce	int	DC-e 起始编号（编号从此处开始）
is_create_category_template	boolean	自动创建默认税务类别。默认值：`true`

* 必填字段。

载荷示例

        {
          "cnpj": "12345678000199",
          "name": "Empresa Exemplo LTDA",
          "ie": "123456789",
          "invoice_type": "simples_nacional",
          "unit": "UN",
          "email": "contato@empresa.com",
          "cep": "01001000",
          "address": "Rua Exemplo",
          "house_number": "100",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://exemplo.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "serie": 1,
          "number": 1,
          "serie_mdfe": 2,
          "number_mdfe": 1,
          "serie_cte": 3,
          "number_cte": 1,
          "serie_dce": 4,
          "number_dce": 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://exemplo.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 一起发送时，证书在保存前会经过验证。

公司是以 NF-e 配置创建的（通过 /api/company/create）。要启用其他单证，请在此处完善登记：本接口还接受 NFC-e、NFS-e、MDF-e、CT-e 和 DC-e 字段（见下方各节）。只需发送公司将要开具的单证所对应的字段。

必需请求头

请求头	类型	说明
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	新初始编号
alias	string	商号
telefone	string	电话
complemento	string	地址补充
NFC-e
csc_id	string	SEFAZ 的 CSC（纳税人安全代码）ID
csc	string	CSC 令牌（与 SEFAZ 共享的密钥）
serie_nfce	int	NFC-e 系列
number_nfce	int	NFC-e 下一个编号
NFS-e
im	string	市政登记号(Inscrição Municipal)
codigo_municipio_nfse	string	开具市政的 IBGE 代码
codigo_servico_nfse	string	默认服务代码(LC 116)
cnae_nfse	string	默认活动 CNAE
serie_nfse	int	NFS-e 系列
number_nfse	int	NFS-e 下一个编号
regime_especial_tributacao	int	特殊税制代码
optante_simples_nacional	bool	是否加入 Simples Nacional
运输 (MDF-e / CT-e / DC-e)
serie_mdfe	int	MDF-e 系列
number_mdfe	int	MDF-e 起始编号（编号从此处开始）
serie_cte	int	CT-e 系列
number_cte	int	CT-e 起始编号（编号从此处开始）
serie_dce	int	DC-e 系列
number_dce	int	DC-e 起始编号（编号从此处开始）

* 必填字段。发送 cnpj 会返回错误。其他所有字段均为可选 — 只需发送您想要更改的字段。

载荷示例

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

示例 — 为公司启用 NFC-e 和 CT-e

        {
          "company_id": "comp_789012",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "serie_cte": 1,
          "number_cte": 1
        }

响应

        {
          "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": "contato@empresa.com",
                "cep": "01001000",
                "address": "Rua Exemplo",
                "house_number": "100",
                "town": "Centro",
                "city": "São Paulo",
                "state": "SP",
                "cert_file": "https://exemplo.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": "contato@empresa.com",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "cert_file": "https://exemplo.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	按状态过滤（值: `"Success"`（已授权）、`"Canceled"`（已取消）、`"Voided"`（已作废）、`"Processing"`（处理中）、`"InvoicingFailed"`（开票失败）、`"Failed"`（失败）、`"Contingencia"`（离线应急）、`"Unknown"`（未知））

* 必填字段。

调用示例

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

响应

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

GET /api/invoice/get_detail

查询 NF-e 详情

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

必需请求头

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

查询字符串

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

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

调用示例

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

响应

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

POST /api/invoice/refresh

更新发票状态

查询 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" }],
          "ibs_cbs":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "000", "classificacao_tributaria": "000001" }]
        }

响应

        {
          "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 引用原始发票 — 退货票为原始 NF-e 的完整克隆）或 部分／自定义退货（在 body 根级直接发送 chave + 发票完整字段，与 /api/invoice/create 结构相同）。

必需请求头

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

Body — 顶层字段

字段	类型	说明
uuid	string	原始 NF-e 的 UUID（全额退货用；如果没有 `chave` 则必填）。传了 uuid 就始终按全额退货处理，部分退货字段会被忽略
chave	string	原始 NF-e 的 44 位访问密钥（部分退货必填；全额退货时作为 `uuid` 的替代）
cfop *	string	退货 CFOP（例如：`"1202"`、`"1411"`、`"2202"`、`"5202"`、`"5411"`、`"6202"`）
natureza_operacao	string	操作性质（例如："Devolução de venda"）。接受别名：`nature_of_operation`
transaction_type	string	交易类型：`"0"`=入库，`"1"`=出库（部分退货必填）。退货票始终按入库（`tpNF=0`）开具
model	string	单据型号：`"55"`（部分退货必填）
issuance_type	string	开具类型：`"1"`=正常（部分退货必填）
ambiente	string	环境：`"1"`=生产，`"2"`=测试（部分退货必填）
cliente	object	收件方数据，与 `/api/invoice/create` 结构相同（部分退货必填）。注意：地址门牌号字段是 `number`（英文），不是 `numero`。不传 `number` 时地址以 nro "S/N" 输出；IBGE 代码、城市和州由 `cep` 解析
products	array	退货商品，与 `/api/invoice/create` 结构相同（部分退货必填）。`codigo` 可选 — 缺省时 cProd 使用 `name`

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

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

示例 — 全额退货

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

示例 — 部分退货（body 根级完整字段）

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "5202",
          "natureza_operacao": "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": "YOUR_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1"
            }
          ],
          "transportation": {
            "transport_mode": "0",
            "freight_amount": 30.00,
            "carrier_info": {
              "cnpj": "12345678000188",
              "name": "Transportadora Expressa",
              "endereco": "Rua da Transportadora",
              "city": "São Paulo",
              "uf": "SP"
            },
            "vehicle_info": {
              "plate": "ABC1234",
              "uf": "SP",
              "rntc": "123456"
            },
            "packages": [
              {
                "qty": 1,
                "packaging_type": "CX",
                "gross_weight": 2.500,
                "net_weight": 2.000
              }
            ]
          },
          "shipping_address": {
            "cnpj": "12345678000199",
            "name": "Remetente Ltda",
            "endereco": "Rua do Remetente",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000"
          },
          "delivery_address": {
            "cnpj": "98765432000111",
            "name": "Destinatário Ltda",
            "endereco": "Rua do Destinatário",
            "number": "200",
            "bairro": "Centro",
            "city": "Rio de Janeiro",
            "uf": "RJ",
            "cep": "20040020"
          },
          "pag_info": [
            {
              "payment_method": "03",
              "payment_indicator": "0",
              "card_info": {
                "integration_type": "1",
                "brand_code": "01"
              }
            }
          ],
          "informacoes_complementares": "Sem informações adicionais",
          "informacoes_fisco": "ICMS recolhido conforme legislação"
        }

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

进口完整示例

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

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

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

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

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://exemplo.com/cert.pfx",
          "cert_pwd": "senha_certificado",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "telefone": "11999999999"
        }

响应

        {
          "success": true,
          "message": "Empresa cadastrada para 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": "Loja Centro - Filial 02",
          "telefone": "11988888888",
          "serie_nfce": 2,
          "number_nfce": 1
        }

响应

        {
          "success": true,
          "message": "Empresa NFC-e atualizada com sucesso"
        }

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": "Loja Centro",
            "ie": "123456789",
            "invoice_type": "simples_nacional",
            "email": "contato@empresa.com",
            "telefone": "11999999999",
            "cep": "01001000",
            "address": "Rua Exemplo",
            "house_number": "100",
            "complemento": "Sala 5",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "state_code": "SP",
            "cert_file": "https://exemplo.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": "Success",
            "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"
          }
        }

GET /api/nfce/get_list

NFC-e 列表（分页）

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

必需请求头

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

查询字符串

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

* 必填字段。

调用示例

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

响应

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

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": "BEBIDAS_PADRAO",
              "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": "ALIMENTOS",
              "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": "Exemplo",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contato@empresa.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "Rua Exemplo",
          "house_number": "86",
          "complemento": "Andar 2",
          "town": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://storage.exemplo.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": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_dps.xml",
            "nfseXml": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_nfse.xml"
          }
        }

dpsXml: 发送到市政厅/ADN 的 XML 链接（OSS URL）。 nfseXml: 包含开具结果的返回 XML 链接。XML 在首次请求时上传到 OSS，URL 会被缓存。

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 状态。

GET /api/nfse/get_list

NFS-e 列表（分页）

分页列出公司的 NFS-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	按状态过滤。值: `"autorizada"`、`"cancelada"`、`"pendente"`、`"rejeitada"`

* 必填字段。

调用示例

GET /api/nfse/get_list?page=1&page_size=20&status=autorizada

响应

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "31250112345678000190000000000012345678901234",
                "codigo_verificacao": "ABCD-1234",
                "serie": 1,
                "number": 1,
                "status": "autorizada",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

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。cMDF、cDV、cUF、dhEmi、mod、tpEmis、procEmi、verProc 字段由服务器自动计算。客户端仅发送业务字段。serie 和 nMDF 为可选字段——省略（或为 0）时由服务器自动分配，发送时则予以采用（适用于跳过编号，例如在 SEFAZ 出现重复后）。

必需请求头

请求头	类型	说明
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	后续装载指示器
serie	int	MDF-e 系列号（访问密钥的 3 位）。可选——省略或为 `0` 时自动分配（公司的 MDF-e 系列）；发送时则按发送值使用
nMDF	int	MDF-e 编号（构成访问密钥）。可选——省略或为 `0` 时由服务器自动递增；发送时则按发送值使用（便于跳过编号，例如：发生重复后）

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	关联 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"
          }
        }

GET /api/mdfe/get_list

MDF-e 列表（分页）

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

必需请求头

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

查询字符串

参数	类型	说明
page *	int	页码（≥ 1）
page_size *	int	每页大小（1–50）
start_create_time	long	Unix 时间戳（毫秒） — 起始（需要 `end_create_time`）
end_create_time	long	Unix 时间戳（毫秒） — 结束
status	string	按状态过滤。值: `"Success"`（已授权）、`"Canceled"`（已取消）、`"Voided"`（已关闭）、`"Processing"`（处理中）、`"Failed"`（失败）、`"Unknown"`（未知）

* 必填字段。

调用示例

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

响应

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190580010000000011000000015",
                "serie": 1,
                "number": 1,
                "modal": "1",
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

inventory_2 DC-e — 电子内容声明

DC-e API（型号 99，布局 1.00）支持开具、查询、取消电子内容声明并获取其 PDF（DACE）。DC-e 是在无须开具发票时为货物或商品运输提供凭证的税务文档——例如涉及 ICMS 非纳税人的发货。开具方始终为法人（CNPJ）；收件方可以是法人（CNPJ）或自然人（CPF）。业务数据放在 /create 的请求体中；访问密钥的技术字段（cDC、cDV、cUF、dhEmi、mod）由服务器自动计算。

端点	方法	说明
`/api/dce/create`	POST	开具 DC-e
`/api/dce/consult`	POST	查询 DC-e 状态
`/api/dce/cancel`	POST	取消已授权的 DC-e
`/api/dce/pdf`	POST	获取 DC-e 的 DACE（PDF）

DC-e 被路由到开具方所在 UF 的授权方。字段 ide.cUF 必须与 emit.enderEmit.UF 中填写的 UF 一致——两者不一致时 SEFAZ 会以 cStat=220 拒绝；若省略，则从该 UF 推导出 cUF。

POST /api/dce/create

开具 DC-e

根据发送的请求体开具一张 DC-e。客户端只发送业务数据；访问密钥的技术识别字段由服务器计算（见 ide 表下方的说明）。仅在生产环境（tpAmb=1）且 DC-e 被授权时才扣除额度。

必需请求头

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

Body — 根

字段	类型	说明
ide *	object	DC-e 的标识
emit *	object	开具方/发件方数据（CNPJ，或通过电商平台的 CPF——见下文）
dest *	object	收件方数据
det *	array	声明的项目/货物——至少 1 项
total *	object	声明的合计
transp	object	运输数据
marketplace	object	电商平台数据（仅当 `ide.tpEmit=1` 时）
fisco	object	税务机关数据（仅当 `ide.tpEmit=0` 时）
autXML	array	被授权访问 XML 的 CNPJ/CPF
infAdic	object	附加信息

请求中的必填字段： ide.tpAmb；emit.CNPJ（14 位）或 emit.CPF（11 位，通过电商平台的个人发件方——见 emit 中的注记）、emit.xNome 和 emit.enderEmit（xLgr、nro、xBairro、cMun、xMun、CEP 为 8 位、UF）；dest 含 CNPJ 或 CPF、dest.xNome 和 dest.enderDest（同样的地址字段）；det 中至少 1 项，含 xProd、NCM（2 或 8 位）、qCom > 0 和 vProd > 0；以及 total.vDC > 0。其余所有字段均为可选。

ide — 标识

字段	类型	说明
tpAmb *	int	环境：`1`=生产，`2`=测试。`ide` 中唯一真正必填的字段。
tpEmit	int	开具方类型：`0`=税务机关应用，`1`=电商平台，`2`=自主开具方。可选——默认：`2`
cUF	int	开具方 UF 的 IBGE 代码（2 位）。可选——省略时从 `emit.enderEmit.UF` 推导。如发送，必须与该 UF 一致（不一致时 SEFAZ 会以 `cStat=220` 拒绝）
serie	int	税务文档系列号（访问密钥的 3 位）——标识 DC-e 的编号序列。可选——默认：公司中登记的 DC-e 系列
nDC	long	DC-e 的顺序号（构成访问密钥）。可选——省略或为 `0` 时由服务器自动递增
nSiteAutoriz	int	处理该 DC-e 的授权站点标识（访问密钥的 1 位）。通常为 `0`（主站点）。可选——默认：`0`
tpEmis	int	开具方式：`1`=正常，`9`=应急。可选——默认：`1`

由服务器自动填充——无须发送： mod（固定为 99）和 cDV（密钥校验位）始终由服务器设定；cDC（6 位数字代码）、dhEmi（开具日期时间）和 verProc（处理程序版本）在省略时生成。上表中的 serie、nDC 和 cUF 字段在省略时也会自动填充。

emit — 开具方 / 发件方

字段	类型	说明
CNPJ ⚠	string	开具方 CNPJ（14 位）。省略时填充为 token 对应公司的 CNPJ
CPF ⚠	string	个人发件方的 CPF（11 位）。仅允许通过电商平台开具——见下方注记
xNome *	string	开具方/发件方的姓名或公司名称
enderEmit *	object	开具方地址（见下方结构）

个人发件方（CPF）：根据 SEFAZ 规则，CPF 不能作为自主开具方（tpEmit=2 要求 CNPJ）。如需以 CPF 作为发件方开具，只需发送 emit.CPF（不含 emit.CNPJ）：服务器会自动设置 tpEmit=1（电商平台），在访问密钥中使用贵公司的 CNPJ（token 对应公司）作为授权开具方，并以公司数据填充 marketplace 块。所填的 CPF 将在 emit 中显示为发件方。

dest — 收件方

字段	类型	说明
CNPJ ⚠	string	收件方 CNPJ（14 位）
CPF ⚠	string	收件方 CPF（11 位）
xNome *	string	收件方的姓名或公司名称
enderDest *	object	收件方地址（见下方结构）

enderEmit / enderDest — 地址

字段	类型	说明
xLgr *	string	街道
nro *	string	门牌号
xCpl	string	补充信息
xBairro *	string	街区
cMun *	long	自治市 IBGE 代码（7 位）
xMun *	string	自治市名称
CEP *	string	邮政编码（8 位）
UF *	string	UF 简称（2 个字母）
cPais	int	国家代码。默认：`1058`（巴西）
xPais	string	国家名称。默认：`BRASIL`
fone	string	电话
email	string	电子邮箱

det[] — 声明的项目

字段	类型	说明
nItem	int	项目顺序号
xProd *	string	声明的货物/商品描述
NCM *	string	NCM 代码（2 或 8 位）
qCom *	decimal	数量（> 0）
vUnCom	decimal	单价
vProd *	decimal	项目总金额（> 0）
infAdProd	string	项目附加信息

total — 合计

字段	类型	说明
vDC *	decimal	声明的总金额（> 0）

transp — 运输

字段	类型	说明
modTrans	int	运输方式：`0`=邮政，`1`=自有，`2`=承运商。默认：`2`
CNPJTransp	string	承运商 CNPJ

marketplace — 电商平台（仅 `tpEmit=1`）

字段	类型	说明
CNPJ	string	电商平台 CNPJ
xNome	string	电商平台名称
Site	string	电商平台网站

fisco — 税务机关（仅 `tpEmit=0`）

字段	类型	说明
CNPJ	string	机关 CNPJ
xOrgao	string	机关名称
UF	string	机关所在 UF

autXML[] — XML 授权对象

字段	类型	说明
CNPJ	string	被授权查询/下载 XML 的 CNPJ
CPF	string	被授权查询/下载 XML 的 CPF

infAdic — 附加信息

字段	类型	说明
infAdFisco	string	税务机关关注的信息
infCpl	string	纳税人关注的补充信息
infAdMarketPlace	string	电商平台附加信息

* 必填字段。⚠ 开具方和收件方中，CNPJ 或 CPF 至少须填一个。

简化示例（最少字段）

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2
          },
          "emit": {
            "CNPJ": "12345678000199",
            "xNome": "EMPRESA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": 4106902,
              "xMun": "CURITIBA",
              "CEP": "80010000",
              "UF": "PR"
            }
          },
          "dest": {
            "CPF": "12345678909",
            "xNome": "JOAO DA SILVA",
            "enderDest": {
              "xLgr": "AVENIDA DESTINO",
              "nro": "500",
              "xBairro": "JARDIM",
              "cMun": 4113700,
              "xMun": "LONDRINA",
              "CEP": "86010000",
              "UF": "PR"
            }
          },
          "det": [
            {
              "nItem": 1,
              "xProd": "LIVROS DIVERSOS",
              "NCM": "49019900",
              "qCom": 3,
              "vUnCom": 50.00,
              "vProd": 150.00
            }
          ],
          "total": {
            "vDC": 150.00
          }
        }

完整示例（所有字段）

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "cUF": 41,
            "serie": 1,
            "nSiteAutoriz": 0
          },
          "emit": {
            "CNPJ": "12345678000199",
            "xNome": "EMPRESA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xCpl": "SALA 2",
              "xBairro": "CENTRO",
              "cMun": 4106902,
              "xMun": "CURITIBA",
              "CEP": "80010000",
              "UF": "PR",
              "cPais": 1058,
              "xPais": "BRASIL",
              "fone": "4133334444",
              "email": "contato@exemplo.com"
            }
          },
          "dest": {
            "CNPJ": "98765432000188",
            "xNome": "DESTINATARIO EXEMPLO LTDA",
            "enderDest": {
              "xLgr": "AVENIDA DESTINO",
              "nro": "500",
              "xCpl": "GALPAO 3",
              "xBairro": "JARDIM",
              "cMun": 4113700,
              "xMun": "LONDRINA",
              "CEP": "86010000",
              "UF": "PR",
              "cPais": 1058,
              "xPais": "BRASIL",
              "fone": "4333335555",
              "email": "destino@exemplo.com"
            }
          },
          "autXML": [
            { "CNPJ": "11222333000144" },
            { "CPF": "98765432100" }
          ],
          "det": [
            {
              "nItem": 1,
              "xProd": "LIVROS DIVERSOS",
              "NCM": "49019900",
              "qCom": 3,
              "vUnCom": 50.00,
              "vProd": 150.00,
              "infAdProd": "Caixa 1 de 2"
            },
            {
              "nItem": 2,
              "xProd": "MATERIAL DE ESCRITORIO",
              "NCM": "48201000",
              "qCom": 10,
              "vUnCom": 8.00,
              "vProd": 80.00,
              "infAdProd": "Caixa 2 de 2"
            }
          ],
          "total": {
            "vDC": 230.00
          },
          "transp": {
            "modTrans": 2,
            "CNPJTransp": "55666777000188"
          },
          "infAdic": {
            "infAdFisco": "Operacao nao sujeita a emissao de nota fiscal",
            "infCpl": "Remessa de bens entre filiais"
          }
        }

成功响应

        {
          "success": true,
          "message": "DC-e autorizada",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "serie": 1,
            "number": 1,
            "cStat": "100",
            "xMotivo": "Autorizado o uso do DC-e",
            "nProt": "141250000123456",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

拒绝响应

        {
          "success": false,
          "message": "DC-e rejeitada: Rejeicao: ...",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "serie": 1,
            "number": 1,
            "cStat": "225",
            "xMotivo": "Rejeicao: Falha no Schema XML",
            "nProt": "",
            "xml": "",
            "dace": ""
          }
        }

POST /api/dce/consult

查询 DC-e 状态

根据访问密钥查询 DC-e 在 SEFAZ 上的当前状态。当 DC-e 已取消时，响应反映取消的数据（本地库是取消信息的事实来源）。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chDCe *	string	DC-e 访问密钥（44 位）

* 必填字段。

载荷示例

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

响应 — DC-e 有效

        {
          "success": true,
          "message": "Autorizado o uso do DC-e",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "status": "Success",
            "cStat": "100",
            "xMotivo": "Autorizado o uso do DC-e",
            "nProt": "141250000123456",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

响应 — DC-e 已取消

        {
          "success": true,
          "message": "DC-e Cancelada",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "status": "Canceled",
            "cStat": "101",
            "xMotivo": "Cancelamento de DCe homologado",
            "nProt": "141250000123457",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "xmlCancel": "https://storage.../dce/41250612345678000199990010000000011201234564-110111-01.xml",
            "dhEventoCancel": "2026-06-11T11:00:00-03:00"
          }
        }

POST /api/dce/cancel

取消 DC-e

取消一张已授权的 DC-e（事件 110111）。要求 DC-e 已被授权（已有协议号）且尚未取消。每张 DC-e 只允许取消一次。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chDCe *	string	DC-e 访问密钥（44 位）
xJust *	string	取消理由（按 SEFAZ 要求至少 15 个字符）
nProt	string	授权协议号。可选：省略时使用开具时登记的协议号

* 必填字段。

载荷示例

        {
          "chDCe": "41250612345678000199990010000000011201234564",
          "xJust": "Cancelamento por erro no preenchimento dos dados da declaracao"
        }

成功响应

        {
          "success": true,
          "message": "DC-e cancelada",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "cStat": "135",
            "xMotivo": "Evento registrado e vinculado a DC-e",
            "nProtCancel": "141250000123457",
            "xmlCancel": "https://storage.../dce/41250612345678000199990010000000011201234564-110111-01.xml"
          }
        }

遇到拒绝时，响应返回 success=false、拒绝的 cStat/xMotivo 以及附加字段 xmlEnviadoDebug（含已发送的 XML），用于诊断。

POST /api/dce/pdf

获取 DC-e 的 DACE（PDF）

返回 DACE 的 URL——即 DC-e 的 PDF 表现形式。当 PDF 在存储中尚不存在时，会按需生成并发送。如存储不可用，则 PDF 以 base64 形式直接在响应体中返回。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chDCe *	string	DC-e 访问密钥（44 位）

* 必填字段。

载荷示例

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

响应 — PDF 的 URL

        {
          "success": true,
          "message": "DACE disponível",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

响应 — base64 回退（存储不可用）

        {
          "success": true,
          "message": "DACE disponível",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "pdfBase64": "JVBERi0xLjcKJ...",
            "pdfSize": 84213
          }
        }

GET /api/dce/get_list

DC-e 列表（分页）

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

必需请求头

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

查询字符串

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

* 必填字段。

调用示例

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

响应

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190990010000000011000000013",
                "serie": 1,
                "number": 1,
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

local_shipping CT-e — 电子运输凭证

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

端点	方法	说明
`/api/cte/create`	POST	开具 CT-e
`/api/cte/cancel`	POST	取消 CT-e（事件 110111）
`/api/cte/cce`	POST	更正函 — CC-e（事件 110110）
`/api/cte/desacordo`	POST	服务异议（事件 610110，由服务承接方登记）
`/api/cte/consult`	POST	查询 CT-e 状态
`/api/cte/inutilize`	POST	作废编号区间

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

POST /api/cte/create

开具 CT-e

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

必需请求头

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

请求中的必填字段： ide（tpAmb、CFOP、natOp、modal、tpCTe、toma、cMunIni、UFIni、cMunFim、UFFim）；emit 含 CNPJ 或 CPF 和 xNome；rem 含 CNPJ 或 CPF；dest 含 CNPJ 或 CPF；vPrest.vTPrest > 0；imp（含一个 ICMS 变体）。对于 tpCTe=0（正常）：infCTeNorm 含 infCarga（proPred + 至少 1 个 infQ）和 infModal（与 ide.modal 对应的运输方式；对于 modal=01，rodo.RNTRC 为必填）。其余字段均为可选。

Body — 根

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

ide — 标识

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

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

toma4 — 承接方“其他”（当 `ide.toma=4` 时）

字段	类型	说明
CNPJ ⚠ / CPF ⚠	string	承接方证件（二者之一）
IE	string	州登记号
xNome	string	公司名称/姓名
xFant, fone, email	string	商号、电话、电子邮箱
enderToma	object	地址：`{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, cPais, xPais }`

emit — 开具方（承运人）

字段	类型	说明
CNPJ ⚠	string	开具方 CNPJ（14 位）
CPF ⚠	string	开具方 CPF（11 位）
IE	string	州登记号
IEST	string	税务代扣代缴义务人的州登记号
xNome *	string	公司名称
xFant	string	商号
CRT	int	税收制度代码：`1`=简易税制，`2`=超出子上限的简易税制，`3`=常规税制，`4`=个体微型企业（MEI）。默认：`3`
enderEmit	object	地址：`{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone }`

rem — 发件方

字段	类型	说明
CNPJ ⚠ / CPF ⚠	string	发件方证件（二者之一）
IE	string	州登记号（或 `"ISENTO"`）
xNome	string	公司名称/姓名
xFant, fone, email	string	商号、电话、电子邮箱
enderReme	object	发件方地址（结构见下方）
locColeta	array	收件地点（可选）：`[{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }]`

dest — 收件方

字段	类型	说明
CNPJ ⚠ / CPF ⚠	string	收件方证件（二者之一）
IE	string	州登记号（或 `"ISENTO"`）
xNome	string	公司名称/姓名
fone, email, ISUF	string	电话、电子邮箱、SUFRAMA 登记号
enderDest	object	收件方地址（结构见下方）
locEnt	object	交付地点（可选）：`{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }`

exped / receb — 发货方 / 收货方（可选）

字段	类型	说明
CNPJ / CPF	string	证件（二者之一）
IE, xNome, fone, email	string	州登记号、名称、电话、电子邮箱
enderExped / enderReceb	object	地址（与下方通用结构相同）

地址（enderEmit / enderReme / enderExped / enderReceb / enderDest）

字段	类型	说明
xLgr	string	街道
nro	string	门牌号
xCpl	string	补充信息
xBairro	string	街区
cMun	string	自治市 IBGE 代码（7 位）
xMun	string	自治市名称
CEP	string	邮政编码（8 位）— 在 `enderEmit` 中不使用
UF	string	UF 简称（2 个字母）
cPais	string	国家代码（可选，默认 1058 巴西）
xPais	string	国家名称（可选）
fone	string	电话（仅在 `enderEmit` 中）

vPrest — 服务提供的金额

字段	类型	说明
vTPrest *	decimal	服务提供的总金额（> 0）
vRec	decimal	应收金额
Comp	array	金额构成项：`[{ xNome, vComp }]` — 例如：`"FRETE PESO"`、`"PEDÁGIO"`、`"GRIS"`

imp — 税费

字段	类型	说明
ICMS *	object	ICMS 课税 — 仅填写一个变体（见下方）
vTotTrib	decimal	税费近似总额
infAdFisco	string	税务机关关注的附加信息
ICMSUFFim	object	DIFAL（跨州分摊，可选）：`{ vBCUFFim, pFCPUFFim, pICMSUFFim, pICMSInter, vFCPUFFim, vICMSUFFim, vICMSUFIni }`
infTribFed	object	联邦税（可选）：`{ vPIS, vCOFINS, vIR, vINSS, vCSLL }`

ICMS — 变体（仅填写一个）

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

infCTeNorm — 正常 CT-e（`tpCTe=0`/`3` 时必填）

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

infCTeNorm.infCarga — 货物

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

infCTeNorm.infDoc — 所运输的单据

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

infCTeNorm.infModal — 运输方式（仅填写与 `ide.modal` 对应的一项）

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

整个 infModal 块都接受 versaoModal（默认 "4.00"）。

compl — 补充数据（可选）

字段	类型	说明
xCaracAd, xCaracSer, xEmi	string	运输的附加特征 / 服务的附加特征 / 开票人姓名
origCalc, destCalc	string	用于计算运费的起始 / 终止自治市
xObs	string	一般备注
ObsCont / ObsFisco	array	纳税人 / 税务机关的自由备注：`[{ xCampo, xTexto }]`
fluxo, Entrega	object	货物流向（起点/中转/终点/路线）和预计交付

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

简化示例 — 公路运输方式，简易税制

        {
          "ide": {
            "CFOP": 5353,
            "natOp": "PRESTACAO DE SERVICO DE TRANSPORTE",
            "tpAmb": 2,
            "tpCTe": 0,
            "modal": "01",
            "tpServ": 0,
            "cMunEnv": 3550308,
            "xMunEnv": "SAO PAULO",
            "UFEnv": "SP",
            "cMunIni": 3550308,
            "xMunIni": "SAO PAULO",
            "UFIni": "SP",
            "cMunFim": 3304557,
            "xMunFim": "RIO DE JANEIRO",
            "UFFim": "RJ",
            "retira": 1,
            "indIEToma": 9,
            "toma": 0
          },
          "emit": {
            "CNPJ": "26638419000167",
            "IE": "141507411110",
            "CRT": 1,
            "xNome": "TF COMERCIO DE PRESENTES LTDA",
            "enderEmit": {
              "xLgr": "RUA QUINTANA",
              "nro": "34",
              "xBairro": "CIDADE MONCOES",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "04571010",
              "UF": "SP",
              "fone": "1133334444"
            }
          },
          "rem": {
            "CNPJ": "11111111000111",
            "IE": "ISENTO",
            "xNome": "EMPRESA REMETENTE LTDA",
            "fone": "1122223333",
            "enderReme": {
              "xLgr": "AV PAULISTA",
              "nro": "1500",
              "xBairro": "BELA VISTA",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "01310200",
              "UF": "SP"
            }
          },
          "dest": {
            "CNPJ": "22222222000122",
            "IE": "ISENTO",
            "xNome": "EMPRESA DESTINATARIA LTDA",
            "fone": "2133334444",
            "enderDest": {
              "xLgr": "AV RIO BRANCO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": "3304557",
              "xMun": "RIO DE JANEIRO",
              "CEP": "20040002",
              "UF": "RJ"
            }
          },
          "vPrest": {
            "vTPrest": 1500.00,
            "vRec": 1500.00,
            "Comp": [
              { "xNome": "FRETE PESO", "vComp": 1500.00 }
            ]
          },
          "imp": {
            "ICMS": {
              "ICMSSN": { "CST": "90", "indSN": 1 }
            },
            "vTotTrib": 0
          },
          "infCTeNorm": {
            "infCarga": {
              "vCarga": 10000.00,
              "proPred": "PRODUTOS DIVERSOS",
              "infQ": [
                { "cUnid": "01", "tpMed": "PESO BRUTO", "qCarga": 1000.0000 }
              ]
            },
            "infDoc": {
              "infNFe": [
                { "chave": "35260526638419000167550030000006561341688760" }
              ]
            },
            "infModal": {
              "versaoModal": "4.00",
              "rodo": {
                "RNTRC": "12345678"
              }
            }
          }
        }

成功响应

        {
          "success": true,
          "message": "Autorizado o uso do CT-e",
          "data": {
            "cStat": "100",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123456",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml",
            "dacte": "https://storage.../cte/35260626638419000167570010000000011123456780.pdf"
          }
        }

拒绝响应

        {
          "success": false,
          "message": "Rejeicao: ...",
          "data": {
            "cStat": "539",
            "chCTe": "",
            "nProt": "",
            "xml": ""
          }
        }

POST /api/cte/cancel

取消 CT-e

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

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chCTe *	string	CT-e 访问密钥（44 位）
xJust *	string	取消理由（按 SEFAZ 要求最少 15 个字符）
nProt	string	授权协议号。可选：省略时使用开具时登记的协议号

* 必填字段。

载荷示例

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "xJust": "Cancelamento por erro no preenchimento dos dados da prestacao"
        }

成功响应

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123457",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml"
          }
        }

POST /api/cte/cce

更正函（CC-e）

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

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chCTe *	string	CT-e 访问密钥（44 位）
infCorrecao[] *	array	更正项（最少 1 项，最多 20 项）
infCorrecao[].grupoAlterado *	string	被更改的组（例如：`"ide"`、`"rem"`、`"dest"`）
infCorrecao[].campoAlterado *	string	被更改的字段（例如：`"xNome"`）
infCorrecao[].valorAlterado *	string	新值
infCorrecao[].nroItemAlterado	int	被更改项的编号（当该组为列表时）

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

载荷示例

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "infCorrecao": [
            {
              "grupoAlterado": "compl",
              "campoAlterado": "xObs",
              "valorAlterado": "OBSERVACAO CORRIGIDA"
            }
          ]
        }

成功响应

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123458",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml"
          }
        }

POST /api/cte/desacordo

服务异议

登记服务提供异议（事件 610110）— 由服务承接方用于声明 CT-e 中所述的服务提供与所约定的内容不符。登记该事件的 CNPJ（即承接方）为 token 对应公司；无须是 CT-e 的开具方。

必需请求头

请求头	类型	说明
token	string	公司（承接方）的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chCTe *	string	CT-e 访问密钥（44 位）
xObs *	string	异议描述（最少 15 个字符）

* 必填字段。异议操作指示符始终为 1（PL-CTe v4.00）。

载荷示例

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "xObs": "Valor do frete cobrado diverge do contratado entre as partes"
        }

成功响应

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123459"
          }
        }

POST /api/cte/consult

查询 CT-e 状态

根据访问密钥在 SEFAZ 查询 CT-e 的状态。当 CT-e 已取消（本地记录）时，响应会反映该取消。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chCTe *	string	CT-e 访问密钥（44 位）

* 必填字段。

载荷示例

        {
          "chCTe": "35260626638419000167570010000000011123456780"
        }

响应

        {
          "success": true,
          "message": "Autorizado o uso do CT-e",
          "data": {
            "cStat": "100",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123456",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml",
            "dacte": "https://storage.../cte/35260626638419000167570010000000011123456780.pdf"
          }
        }

POST /api/cte/inutilize

作废编号区间

作废一段将不会使用的 CT-e 编号区间（例如发生编号序列断档后）。作废为最终操作，不可撤销。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
tpAmb *	int	环境：`1`=生产，`2`=测试
CNPJ *	string	开具方 CNPJ（14 位）
ano *	int	编号年份（2 位，例如 2026 为 `26`）
serie *	int	编号系列
nCTIni *	long	区间起始编号
nCTFin *	long	区间结束编号（≥ `nCTIni`）
xJust *	string	理由（最少 15 个字符）
mod	int	型号。默认：`57`

* 必填字段。

载荷示例

        {
          "tpAmb": 2,
          "CNPJ": "26638419000167",
          "ano": 26,
          "serie": 1,
          "nCTIni": 51,
          "nCTFin": 55,
          "xJust": "Quebra de sequencia na numeracao por falha no sistema emissor"
        }

成功响应

        {
          "success": true,
          "message": "Inutilizacao de numero homologado",
          "data": {
            "cStat": "102",
            "chCTe": "",
            "nProt": "135260000123460"
          }
        }

GET /api/cte/get_list

CT-e 列表（分页）

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

必需请求头

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

查询字符串

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

* 必填字段。

调用示例

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

响应

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190570010000000011000000019",
                "serie": 1,
                "number": 1,
                "modal": "01",
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

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": "contador@escritorio.com"
        }

成功响应

        {
          "success": true,
          "data": {
            "email": "contador@escritorio.com",
            "officeDocumentType": "CNPJ",
            "officeDocument": "12345678000199",
            "officeName": "Escritório Contábil LTDA",
            "responsibleName": "João da Silva",
            "crc": "SP123456/O-7",
            "accountantCpf": "12345678909",
            "workAddress": "Rua Exemplo, 100 - Centro - São Paulo/SP",
            "site": "https://escritorio.com",
            "landline": "1133334444",
            "mobile": "11999998888",
            "assistantName": "Maria Souza",
            "assistantEmail": "maria@escritorio.com",
            "assistantPhone": "11988887777",
            "observations": "Atendimento de segunda a sexta, 9h às 18h"
          }
        }

响应字段

字段	类型	说明
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 用户
该会计师未绑定该发票账号	会计师未绑定到指定企业

verified_user CPF 和 CNPJ 验证

用于在巴西联邦税务局 (Receita Federal) 官方数据库中验证 CPF 和 CNPJ 的 API。对于 CPF，返回姓名、登记状态、年龄以及未成年人自动拦截 (符合 LGPD 规定)。对于 CNPJ，返回企业名称、商号、地址、股东信息及完整的登记状态。建议在开具税务文件前用于核对登记信息，以及识别状态异常 (暂停、注销、停业) 的纳税人。

POST /api/invoice/validar_cpf_cnpj

将 CPF (含出生日期) 或 CNPJ 与巴西联邦税务局官方数据库进行验证

接受 CPF 或 CNPJ，无论是否带格式。文档类型会自动识别。对于 CPF，dataNascimento 为必填。

必需的请求头

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

Body

字段	类型	说明
cpfCnpj *	string	CPF (11 位数字) 或 CNPJ (14 个字符)。接受格式化字符。
dataNascimento	string	出生日期 — 仅 CPF 必填。接受的格式：`dd/MM/yyyy`、`dd-MM-yyyy` 或 `ddMMyyyy`。

* 必填字段。

请求示例 — CPF

        {
          "cpfCnpj": "407.105.368-28",
          "dataNascimento": "09/01/1997"
        }

请求示例 — CNPJ

        {
          "cpfCnpj": "03.354.151/0001-36"
        }

响应 — CPF 已找到，状态正常

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "40710536828",
            "nome": "FULANO DE TAL",
            "situacao_codigo": "0",
            "situação_descricao": "REGULAR",
            "menor_de_idade_lgpd": false,
            "idade": 29,
            "data_nascimento": "1997-01-09"
          }
        }

响应 — 未成年人 CPF (LGPD)

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "12345678901",
            "situação_descricao": "Menor de idade",
            "menor_de_idade_lgpd": true
          }
        }

响应 — CPF 未找到

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "12345678901",
            "Situação": "CPF não encontrado"
          }
        }

响应 — 出生日期与 CPF 不匹配

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "40710536828",
            "Situação": "Data de nascimento não confere com o CPF"
          }
        }

响应 — CNPJ 已找到

        {
          "success": true,
          "data": {
            "tipo_doc": "CNPJ",
            "documento": "03354151000136",
            "nome": "EMPRESA EXEMPLO LTDA",
            "situacao_codigo": "2",
            "situação_descricao": "Ativo",
            "nome_empresarial": "EMPRESA EXEMPLO LTDA",
            "nome_fantasia": "EXEMPLO",
            "data_situacao": "20180515",
            "motivo_situacao": ""
          }
        }

响应 — CNPJ 未找到

        {
          "success": true,
          "data": {
            "tipo_doc": "CNPJ",
            "documento": "12345678000199",
            "Situação": "Não encontrado"
          }
        }

CPF 状态码

代码	说明
0	正常 (REGULAR)
2	暂停
3	持有人已故
4	待规范化
5	因重复而取消
8	无效
9	依职权取消

CNPJ 状态码

代码	说明
1	无效
2	活动
3	暂停
4	不适宜
8	注销

错误响应

消息	原因
cpfCnpj é obrigatório	`cpfCnpj` 字段缺失或为空
CPF inválido, verifique a quantidade de dígitos	提供的 CPF 不是 11 位数字
CPF inválido	提供的 CPF 校验位无效或包含字母
CNPJ inválido, verifique a quantidade de dígitos	提供的 CNPJ 不是 14 个字符
CNPJ inválido	提供的 CNPJ 校验位无效
é necessário informar a data de nascimento	发送 CPF 但未提供 `dataNascimento`
dataNascimento inválida (use dd/MM/yyyy)	日期格式与任何接受的模式都不匹配

NFE API 文档

API重要字段

发票发行流程

1. 创建公司

2. 信息推送

3. 发行发票

4. 返回结果

5. 生成文件

税务验证

成功

失败

端点快速参考

成功

客户端错误

服务器错误

NFE API

sync_alt 系统流程

input 输入数据

settings 处理

download 输出

主要端点

必需请求头

Body

载荷示例

响应

必需请求头

Body

载荷示例

响应

必需请求头

Body

载荷示例

示例 — 为公司启用 NFC-e 和 CT-e

响应

必需请求头

查询字符串

调用示例

响应

必需请求头

调用示例

响应

必需请求头

查询字符串

调用示例

响应

必需请求头

调用示例

响应

响应示例

必需请求头

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[]`（选择税）