TF Fiscal
开发文档

NFS-e

查询 NFS-e

返回状态、访问密钥、授权后事件、XML / DANFSe 下载链接与入参回显。

GET/openapi/v2/empresas/{empresaId}/nfse/{nfseId}
需要 token、timestamp、sign 三个签名头，参见认证与签名。

按发行时传入的 id 查询单据。NFS-e 的访问密钥是 50 位、由发行方生成，所以发行失败的单据没有 chaveAcesso，只能用平台生成的 45 位 DPS 标识 identificacaoDps 定位。批量对账用销项列表。单据不存在返回 404。

路径参数

empresaId*
string主体标识
nfseId*
string单据 id

* 必填字段

200
单据存在。单据事实字段随状态推进逐步填充，见下方各情形。
id
string单据 id
status
string单据状态
motivoStatus
string结论说明
numero
int票号
serie
string序列号
numeroDps
intDPS 序号
chaveAcesso
string访问密钥
identificacaoDps
stringDPS 标识
codigoVerificacao
string核验码
dataEmissao
string开票时间
dataAutorizacao
string授权时间
padraoMunicipal
string市政标准
atualizadoEm
string最后变更时刻
chaveSubstituida
string被替代的旧票密钥
chaveSubstituta
string替代本票的新票密钥
linkXml
stringXML 原件下载链接
linkDanfse
stringDANFSe 下载链接
array授权后事件
nfse
object受理参数回显

单据事实字段（numero、chaveAcesso、下载链接、eventos）随状态推进逐步填充。上面的响应示例是 Autorizada 的情形；下面是会改变哪些字段有值的其他情形。

取号前失败

平台在取号前拒绝：参数错误或主体不可开票。没有票号、密钥与 DPS 标识；按 id 对账，也不要指望在销项列表里找到它。

json
{
  "id": "PED-20260918-002",
  "status": "Falha",
  "motivoStatus": "Empresa sem serie de DPS configurada",
  "numero": null,
  "chaveAcesso": null,
  "identificacaoDps": null,
  "dataEmissao": "2026-09-18T13:00:00Z",
  "atualizadoEm": "2026-09-18T13:00:01Z",
  "eventos": [],
  "nfse": null
}
status*
string单据状态
motivoStatus*
string本地拒绝原因

* 必填字段

发行方驳回

DPS 已取号并发送，发行方驳回。有 identificacaoDps 但没有密钥；motivoStatus 带发行方结论码与描述。

json
{
  "id": "PED-20260918-003",
  "status": "Negada",
  "motivoStatus": "E0143 - Codigo de tributacao nacional nao permitido para o municipio",
  "numero": null,
  "serie": "1",
  "numeroDps": 43,
  "chaveAcesso": null,
  "identificacaoDps": "DPS355030824067306100013400001000000000000043",
  "dataEmissao": "2026-09-18T13:05:00Z",
  "padraoMunicipal": "Nacional",
  "atualizadoEm": "2026-09-18T13:05:02Z",
  "eventos": [],
  "nfse": null
}
status*
string单据状态
motivoStatus*
string发行方结论
identificacaoDps*
stringDPS 标识

* 必填字段

已取消并带事件

取消成功后状态为 Cancelada，eventos 带登记的事件；linkDanfse 指向带水印的 PDF。

json
{
  "id": "PED-20260918-001",
  "status": "Cancelada",
  "numero": 1287,
  "chaveAcesso": "35503082406730610001340000000000000000000000000077",
  "atualizadoEm": "2026-09-19T10:00:00Z",
  "eventos": [
    {
      "tipo": "Cancelamento",
      "codigo": "101101",
      "sequencia": 1,
      "protocolo": "3550308000000000000000000000000000000000000000000001",
      "data": "2026-09-19T10:00:00Z",
      "linkXml": "https://api.v2.tffiscal.com/openapi/files/xml/9002?token=..."
    }
  ],
  "nfse": null
}
status*
string单据状态
*
array已登记事件

* 必填字段

上一页开具 NFS-e下一页销项 NFS-e 列表