TF Fiscal
开发文档

NF-e

查询 NF-e

返回状态、票面与 DANFE / XML 下载链接。

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

nfeId 即开票时传入的 id。响应按开票请求的结构回显，外加 SEFAZ 返回的数据。鉴权错误（10009xxx）见认证。

路径参数

empresaId*
string开票主体标识
nfeId*
string发票标识

* 必填字段

200
查询成功。
id
string请求标识
tipo
string单据类型
status
string发票状态
motivoStatus
string驳回原因
ambienteEmissao
string开票环境
enviadaPorEmail
bool是否已邮件发送
dataCriacao
string受理时刻
dataUltimaAlteracao
string最后更新时刻
forcarEmissaoContingencia
bool是否强制应急开票
object订单信息
object买方信息
numero
string票号
serie
string系列号
dataEmissao
string开票时刻
chaveAcesso
string访问密钥
object运输信息
dataAutorizacao
string授权时刻
linkDanfe
stringDANFE 下载链接
linkDownloadXml
string授权 XML 下载链接
linkConsultaPorChaveAcesso
string公开查询地址
object授权协议
emitidaEmContingencia
bool是否应急开出
finalidade
string开票目的
naturezaOperacao
string操作性质描述
object原票引用
array商品行
valorTotal
number发票总额
informacoesAdicionais
string票面备注
informacoesAdicionaisFisco
string给税务机关的备注

发票在 SEFAZ 应答前为 AguardandoAutorizacao，之后进入 Autorizada、Negada 或 Cancelada 终态。终态后平台释放请求参数：pedido、备注、naturezaOperacao 以及税码税率以外的税参不再返回。

AguardandoAutorizacao：处理中

受理后到 SEFAZ 应答前。没有票号、密钥、协议与链接；pedido、cliente 与全部税参按传入回显。再查一次或等回调。

json
{
  "id": "NFe-000014553",
  "status": "AguardandoAutorizacao",
  "numero": null,
  "chaveAcesso": null,
  "dataAutorizacao": null,
  "linkDanfe": null,
  "linkDownloadXml": null,
  "pedido": { "presencaConsumidor": "OperacaoPelaInternet", "pagamento": { "tipo": "PagamentoAVista", "formas": [ { "tipo": "CartaoDeCredito", "valor": 28.47 } ] } },
  "itens": [ { "cfop": "6102", "codigo": "000068", "origem": 0, "impostos": { "icms": { "situacaoTributaria": "102" }, "pis": { "situacaoTributaria": "49", "aliquota": 0 }, "cofins": { "situacaoTributaria": "49", "aliquota": 0 } } } ]
}

Autorizada：已授权

票号、密钥、dataAutorizacao、protocolo 与两个链接都有值。每次查询都重新签发链接。

json
{
  "id": "NFe-000014553",
  "status": "Autorizada",
  "numero": "262",
  "serie": "2",
  "chaveAcesso": "35241104893402000113550020000002621202427463",
  "dataAutorizacao": "2024-11-27T20:56:55Z",
  "protocolo": { "numero": "135240009194753" },
  "linkDanfe": "https://api.v2.tffiscal.com/openapi/files/danfe/35241104893402000113550020000002621202427463?token=…",
  "linkDownloadXml": "https://api.v2.tffiscal.com/openapi/files/xml/8801?token=…"
}

Negada：已驳回

motivoStatus 给出 SEFAZ 返回码与原因。没有 DANFE；已分配的票号会回收，后续开票按先后补上，不会跳号。修正请求后重新开票。

json
{
  "id": "NFe-000014553",
  "status": "Negada",
  "motivoStatus": "778 - Rejeicao: NCM inexistente",
  "linkDanfe": null,
  "linkDownloadXml": null
}

Cancelada：已取消

取消 NF-e 之后。票号、密钥与协议保留；DANFE 链接不再返回，XML 仍可下载。

json
{
  "id": "NFe-000014553",
  "status": "Cancelada",
  "numero": "262",
  "chaveAcesso": "35241104893402000113550020000002621202427463",
  "protocolo": { "numero": "135240009194753" },
  "linkDanfe": null,
  "linkDownloadXml": "https://api.v2.tffiscal.com/openapi/files/xml/8801?token=…"
}

上一页开具 NF-e下一页取消 NF-e