TF Fiscal
Documentação

NFS-e

Consultar NFS-e

Devolve status, chave de acesso, eventos pós-autorização, links de XML / DANFSe e o eco da requisição.

GET/openapi/v2/empresas/{empresaId}/nfse/{nfseId}
Requer os cabeçalhos de assinatura token, timestamp e sign, veja Autenticação.

Consulta o documento pelo id enviado na emissão. A chave de acesso da NFS-e tem 50 dígitos e é gerada pela autoridade emissora, então um documento que falhou não tem chaveAcesso e só pode ser localizado pelo identificacaoDps, o identificador de 45 caracteres da DPS gerado pela plataforma. Para conciliação em lote use a lista de emitidas. Um documento inexistente devolve 404.

Parâmetros de caminho

empresaId*
stringIdentificador da empresa
nfseId*
stringId do documento

* Campo obrigatório

200
Documento encontrado. Os campos de fato do documento vão sendo preenchidos conforme o status avança; veja os cenários abaixo.
id
stringId do documento
status
stringStatus do documento
motivoStatus
stringVeredito
numero
intNúmero da NFS-e
serie
stringSérie
numeroDps
intNúmero da DPS
chaveAcesso
stringChave de acesso
identificacaoDps
stringIdentificador da DPS
codigoVerificacao
stringCódigo de verificação
dataEmissao
stringData de emissão
dataAutorizacao
stringData de autorização
padraoMunicipal
stringPadrão municipal
atualizadoEm
stringÚltima mudança de status
chaveSubstituida
stringChave da nota substituída
chaveSubstituta
stringChave da nota substituta
linkXml
stringLink do XML oficial
linkDanfse
stringLink da DANFSe
arrayEventos pós-autorização
nfse
objectEco da requisição aceita

Os campos de fato do documento (numero, chaveAcesso, links, eventos) vão sendo preenchidos conforme o status avança. O exemplo da resposta acima é o caso Autorizada; abaixo, os outros casos que mudam quais campos têm valor.

Falha antes da numeração

A plataforma recusou antes de numerar: parâmetros inválidos ou emitente inapto. Não há número, chave nem identificador da DPS; concilie pelo id e não espere encontrar o documento na lista de emitidas.

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*
stringStatus
motivoStatus*
stringMotivo da recusa local

* Campo obrigatório

Recusada pela autoridade

A DPS foi numerada e enviada, e a autoridade recusou. Há identificacaoDps mas não há chave; motivoStatus traz o código e a descrição da autoridade.

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*
stringStatus
motivoStatus*
stringVeredito da autoridade
identificacaoDps*
stringIdentificador da DPS

* Campo obrigatório

Cancelada, com eventos

Depois de um cancelamento bem-sucedido o status é Cancelada e eventos traz o evento registrado; linkDanfse passa a apontar para o PDF com marca d'água.

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*
stringStatus
*
arrayEventos registrados

* Campo obrigatório

AnteriorEmitir NFS-ePróximoListar NFS-e emitidas