进项凭证与 DistDFe · TF Fiscal API

说明

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

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

事件类型

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

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

注意：cnpj 字段中发送的 CNPJ 必须是 NF-e 的收件人（表明者），且必须在与所用令牌绑定的系统中注册。否则税务局将返回拒绝信息"事件作者与 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 分钟窗口）

字段

字段	类型	必填	说明
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 并被无错误地保存。

响应字段

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

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

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

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

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

字段

字段	类型	必填	说明
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`）

响应字段

字段	类型	说明
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	事件的税务局协议号
list[].nSeqEvento	int	事件序列
list[].cStat	int	税务局状态码
list[].xMotivo	string	税务局描述性返回消息
list[].xml_url	string	OSS 中 procEvento XML 的公共 URL
list[].create	string	记录的 UTC 时间戳（格式 `yyyy-MM-dd HH:mm:ss`）

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

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

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

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

POST/api/invoice/manifest/get_xml

获取表明事件 XML

必需的头部

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

字段

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

常见错误

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

说明

DistDFe 捕获 — 接收的 NFe

通过税务局（国家环境）的 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 — 现在税务局返回已表明密钥的 procNFe（完整 XML）
使用 /received/get_xml 获取 XML URL 并下载/处理

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

DistDFe 返回的 cStat 代码

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

POST/api/invoice/received/sync

同步进项凭证

必需的头部

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

字段

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

工作原理：

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

响应字段

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

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

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

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

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

POST/api/invoice/received/list

进项凭证列表

必需的头部

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

字段

字段	类型	必填	说明
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`）

响应字段

字段	类型	说明
total	int	符合筛选条件的记录总数
page	int	当前页
page_size	int	页大小
list[].id	string	内部 ObjectId（在 `/received/get_xml` 中使用）
list[].nsu	long	税务局分配给此文档的 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 降序返回（最新优先）。

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

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

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

POST/api/invoice/received/get_xml

获取进项凭证 XML

必需的头部

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

字段

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

关于返回的 XML：

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

常见错误

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

POST/api/invoice/received/get_prod

查询进项发票商品明细

必需的头部

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

字段

字段	类型	必填	说明
chave	string	是	NF-e 的 44 位访问密钥（55 型）。校验位在请求 SEFAZ 之前本地校验
ciencia_nota	bool	否	默认 `false`。为 `true` 时，若 SEFAZ 尚未放开完整 XML，接口会用企业证书登记知悉声明（事件 210210）并重新查询
ambiente	int	否	`1` 生产（默认）或 `2` 测试

响应字段

字段	类型	说明
chave	string	本次查询的访问密钥
total_itens	number	发票商品行数量
itens	array	每个发票商品行（`det`）一个对象
itens[].nItem	number	商品行在发票中的序号
itens[].prod	object	NF-e 布局中的 `prod` 组，保留原始标签名。数量与金额为数字；`cProd`、`NCM`、`cEAN` 等代码为字符串，保留前导零。布局中可重复的标签（`NVE`、`DI`、`detExport`、`rastro`）一律为数组
itens[].infAdProd	string	商品行附加信息（如有）

SEFAZ 如何下发 XML

收票企业来自 token，请求体中无需传 CNPJ。
查询走全国环境的单据分发（DistDFe），使用企业本身的数字证书。
未做任何声明时，SEFAZ 只返回摘要，不含商品明细。传 ciencia_nota: true 可解锁完整 XML。
知悉声明仅表示知道该发票存在：既不确认收货，也不阻止开票方取消。
刚授权的发票可能需要数小时才会被全国环境分发，在此之前返回「未找到发票」。
企业自己开具的发票不会分发给自己，请用收票企业的 token 查询。
查询本身不写入任何数据；只有触发知悉声明时才会在 SEFAZ 登记事件。

常见错误

消息	原因
Chave inserida inválida / 发票密钥无效	密钥不足 44 位、含非数字字符，或校验位不正确
Apenas NF-e modelo 55 pode ser consultada pela chave	该密钥属于 NFC-e（65 型），SEFAZ 不分发此类单据
empresa não encontrada para este token	该 token 未关联任何已登记的公司
empresa não possui certificado configurado	公司档案中没有有效的 A1 证书
nenhum documento localizado para esta chave e este CNPJ...	全国环境尚未分发该发票、环境不符，或该公司不是收票方
esta nota foi emitida por este CNPJ e a SEFAZ não a distribui ao próprio emitente	用开票方自己的 token 查询销项发票（SEFAZ 641）
SEFAZ devolveu apenas o resumo da nota (sem itens)...	该发票尚未提交知悉声明，请传 `ciencia_nota=true`
consumo indevido: a SEFAZ bloqueou consultas repetidas	SEFAZ 按 CNPJ 限流，请稍后重试

当 ciencia_nota 触发事件或发现已登记的知悉声明时，错误响应会带上 data.ciencia，其中是事件结果。其他错误只返回 success 与 message。

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

        {
          "chave": "35260912345678000195550010000012341000012345",
          "ciencia_nota": false
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "chave": "35260912345678000195550010000012341000012345",
            "total_itens": 1,
            "itens": [
              {
                "nItem": 1,
                "prod": {
                  "cProd": "PROD-A",
                  "cEAN": "SEM GTIN",
                  "xProd": "Produto exemplo",
                  "NCM": "84733011",
                  "CFOP": 5102,
                  "uCom": "UN",
                  "qCom": 1.0000,
                  "vUnCom": 1.0000000000,
                  "vProd": 1.00,
                  "cEANTrib": "SEM GTIN",
                  "uTrib": "UN",
                  "qTrib": 1.0000,
                  "vUnTrib": 1.0000000000,
                  "indTot": 1,
                  "xPed": "PED-77"
                }
              }
            ]
          }
        }

POST/api/invoice/received/get_sync_status

查询同步状态

必需的头部

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

字段

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

响应字段

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

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

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

        {
          "cnpj": "26638419000167"
        }

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