NFS-e

Consultar NFS-e emitida por chave

Busca um documento emitido pela chave de acesso de 50 dígitos; a resposta é idêntica à consulta por `id`.

GET/openapi/v2/empresas/{empresaId}/nfse/emitidas/{chaveAcesso}

Requer os cabeçalhos de assinatura token, timestamp e sign, veja Autenticação.

Para conciliação a partir da chave: quando você tem a chave de acesso (do XML, da DANFSe ou de uma contraparte) mas não o id do integrador. A resposta é exatamente a mesma de Consultar NFS-e, que busca pelo id; só não aparece o status Falha, porque uma tarefa que falhou antes da numeração não tem chave. Documentos antigos de São Paulo não têm chave de 50 dígitos e não são encontrados por aqui: concilie por id ou identificacaoDps, ou percorra a lista de emitidas.

Parâmetros de caminho

`empresaId*`	string	Identificador da empresa
`chaveAcesso*`	string	Chave de acesso

* Campo obrigatório

200

Documento encontrado. Os campos de fato vão sendo preenchidos conforme o status avança; os cenários por status estão em Consultar NFS-e.

`id`	string	Id do documento
`status`	string	Status do documento
`motivoStatus`	string	Veredito
`numero`	int	Número da NFS-e
`serie`	string	Série
`numeroDps`	int	Número da DPS
`chaveAcesso`	string	Chave de acesso
`identificacaoDps`	string	Identificador da DPS
`codigoVerificacao`	string	Código de verificação
`dataEmissao`	string	Data de emissão
`dataAutorizacao`	string	Data de autorização
`padraoMunicipal`	string	Padrão municipal
`atualizadoEm`	string	Última mudança de status
`chaveSubstituida`	string	Chave da nota substituída
`chaveSubstituta`	string	Chave da nota substituta
`linkXml`	string	Link do XML oficial
`linkDanfse`	string	Link da DANFSe
	array	Eventos pós-autorização
`nfse`	object	Eco da requisição aceita

`status`Status do documento

Valores	Significado
Pendente	Aceito, ainda sem veredito; cobre a fila, o envio e a conciliação
Autorizada	Emitida com sucesso; pode ser cancelada ou substituída
Negada	Recusada pela autoridade; `motivoStatus` traz o código e a descrição; terminal
EmProcessoDeCancelamento	Pedido de análise de cancelamento aceito, aguardando o município; deferido vira `Cancelada`, indeferido volta a `Autorizada`
Cancelada	Cancelada; terminal
Substituida	Substituída por outra nota; `chaveSubstituta` traz a nova chave; terminal

`padraoMunicipal`Padrão municipal

Valores	Significado
Nacional	Padrão nacional: emissor nacional e distribuição nacional
Paulistana	Sistema próprio do município de São Paulo

`eventos[].tipo`Tipo do evento

A lista acompanha os eventos oficiais e pode crescer.

Valores	Significado
Cancelamento	Cancelamento registrado pelo prestador (101101)
CancelamentoPorSubstituicao	Cancelada por ter sido substituída por outra nota (105102)
PedidoAnalise	Pedido de análise fiscal de cancelamento (101103)
AnaliseDeferida	Município deferiu o cancelamento (105104)
AnaliseIndeferida	Município indeferiu o cancelamento (105105)
CancelamentoDeOficio	Cancelamento de ofício pelo município (305101)
Bloqueio	Bloqueio de ofício pelo município (305102)
Desbloqueio	Desbloqueio de ofício pelo município (305103)
Confirmacao	Uma das partes confirmou a nota, ou confirmação tácita do município (202201 / 203202 / 204203 / 205204)
Rejeicao	Uma das partes rejeitou a nota (202205 / 203206 / 204207)
RejeicaoAnulada	Município anulou uma rejeição (205208)
Outro	Evento oficial ainda não modelado; o código real fica em `status`

`eventos[].codigo`Código oficial do evento

Valores	Significado
101101	Cancelamento pelo prestador
105102	Cancelamento por substituição
101103	Pedido de análise fiscal de cancelamento
105104	Análise deferida
105105	Análise indeferida
305101	Cancelamento de ofício
305102	Bloqueio de ofício
305103	Desbloqueio de ofício
202201	Confirmação pelo prestador
203202	Confirmação pelo tomador
204203	Confirmação pelo intermediário
205204	Confirmação tácita pelo município
202205	Rejeição pelo prestador
203206	Rejeição pelo tomador
204207	Rejeição pelo intermediário
205208	Rejeição anulada pelo município
000000	Evento oficial ainda não modelado; o código real fica em `status`

Código	HTTP
10018003	404	Documento não encontrado: a chave não pertence a esta empresa. Verifique `chaveAcesso` e `empresaId`. Documentos antigos de São Paulo não têm chave de 50 dígitos e não são encontrados por aqui.
10003000	404	`empresaId` não existe ou não pertence a esta aplicação.

APP_SECRET='<APP_SECRET>'

API_PATH='/openapi/v2/empresas/{empresaId}/nfse/emitidas/{chaveAcesso}'

TIMESTAMP=$(date +%s)

SIGN=$(printf '%s%s%s' "$APP_SECRET" "$API_PATH" "$TIMESTAMP" | md5sum | cut -d' ' -f1)

curl -sS -X GET "https://api.v2.tffiscal.com${API_PATH}" \

-H "token: $APP_SECRET" -H "timestamp: $TIMESTAMP" -H "sign: $SIGN"

{

"id": "PED-20260918-001",

"status": "Autorizada",

"numero": 1287,

"serie": "1",

"numeroDps": 42,

"chaveAcesso": "35503082406730610001340000000000000000000000000077",

"identificacaoDps": "DPS355030824067306100013400001000000000000042",

"codigoVerificacao": null,

"dataEmissao": "2026-09-18T13:00:00Z",

"dataAutorizacao": "2026-09-18T13:00:03Z",

"padraoMunicipal": "Nacional",

"atualizadoEm": "2026-09-18T13:00:03Z",

"chaveSubstituida": null,

"chaveSubstituta": null,

"linkXml": "https://api.v2.tffiscal.com/openapi/files/xml/9001?token=...",

"linkDanfse": "https://api.v2.tffiscal.com/openapi/files/danfse/35503082406730610001340000000000000000000000000077?token=...",

"eventos": [],

"nfse": null

}

Consultar NFS-e emitida por chave

Parâmetros

Parâmetros de caminho

Respostas

Enumerações4 tabelas

statusStatus do documento

padraoMunicipalPadrão municipal

eventos[].tipoTipo do evento

eventos[].codigoCódigo oficial do evento

Erros2 itens

`status`Status do documento

`padraoMunicipal`Padrão municipal

`eventos[].tipo`Tipo do evento

`eventos[].codigo`Código oficial do evento