NFS-e

Listar NFS-e recebidas

Lista as notas de serviço em que esta empresa é tomadora ou intermediária, paginadas por data de emissão.

GET/openapi/v2/empresas/{empresaId}/nfse/recebidas

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

As notas de serviço em que esta empresa é tomadora ou intermediária chegam pela distribuição nacional, tanto as emitidas pelo emissor nacional quanto as compartilhadas por sistemas municipais como o de São Paulo, com atraso de até 15 minutos. Uma empresa de São Paulo recebe ainda as notas buscadas direto no sistema municipal, com retrospectiva de 7 dias. Os itens têm a mesma forma de Consultar NFS-e recebida, sem o array eventos, que só o detalhe devolve; a manifestação é registrada em Manifestar sobre NFS-e recebida.

Parâmetros de caminho

empresaId*

string

Identificador da empresa

* Campo obrigatório

Parâmetros de consulta

`dataInicio`	string	Início da janela
`dataFim`	string	Fim da janela
`prestadorCpfCnpj`	string	Documento do prestador
`chaveAcesso`	string	Chave de acesso
`status`	string	Filtro de status
`manifestacao`	string	Filtro de manifestação
`pagina`	int	Página
`tamanho`	int	Tamanho da página

* Campo obrigatório

200

Página de notas recebidas, ordenada por data de emissão. Cada item tem a forma de Consultar NFS-e recebida sem os eventos: eventos é sempre null nos itens da lista.

`pagina`	int	Página devolvida
`tamanho`	int	Tamanho da página aplicado
`total`	int	Total de notas
`totalLimitado`	bool	Total limitado
	array	Notas da página

A sincronização com a distribuição nacional corre a cada 15 minutos por padrão; uma nota recém-emitida pela contraparte aparece na rodada seguinte.
A chegada e as mudanças de status também podem ser recebidas por webhook: nfse.inbound.received, nfse.inbound.canceled e nfse.inbound.substituted; o resultado da manifestação desta empresa por nfse.inbound.manifested e nfse.inbound.manifest_failed. Todos exigem assinatura explícita em Registrar webhook.
total é uma contagem limitada: com totalLimitado=true, estreite a janela em vez de paginar até o fim.
Um item PrefeituraSP vira ADN sozinho quando a transcrição chega; não conte isso como duas notas. Concilie por prestador.cpfCnpj + numero, o identificador estável entre sincronizações.

`status`Filtro de status

Um valor fora da lista é ignorado, sem filtrar.

Valores	Significado
Autorizada	Válida na autoridade
Cancelada	Cancelada
Substituida	Substituída por outra nota

`manifestacao`Filtro de manifestação

Um valor fora da lista é ignorado, sem filtrar.

Valores	Significado
Pendente	Ainda sem manifestação desta empresa
Confirmada	Confirmada por esta empresa
Rejeitada	Rejeitada por esta empresa
ConfirmacaoTacita	Confirmação tácita do município
RejeicaoAnulada	Rejeição anulada pelo município

`itens[].status`Status do documento

Valores	Significado
Autorizada	Válida na autoridade
Cancelada	Cancelada pelo prestador ou de ofício pelo município
Substituida	Substituída por outra nota; `chaveSubstituta` traz a nova chave

`itens[].papel`Papel desta empresa

Valores	Significado
Tomador	Tomador do serviço; manifesta com 203202 (confirmação) ou 203206 (rejeição)
Intermediario	Intermediário do serviço; manifesta com 204203 (confirmação) ou 204207 (rejeição)

`itens[].origem`Origem da linha

Valores	Significado
ADN	Distribuída pela distribuição nacional
PrefeituraSP	Buscada direto no sistema municipal de São Paulo; só empresas de São Paulo; vira `ADN` quando a transcrição chega

`itens[].manifestacao.status`Estado da manifestação

null no campo significa sem manifestação; no filtro da lista esse caso é Pendente.

Valores	Significado
Confirmada	Confirmada por esta empresa (203202 / 204203); terminal
Rejeitada	Rejeitada por esta empresa (203206 / 204207); o município ainda pode anular
ConfirmacaoTacita	Confirmação tácita do município por falta de manifestação no prazo (205204); terminal
RejeicaoAnulada	O município anulou a rejeição desta empresa (205208); terminal

`itens[].manifestacao.codigoEvento`Código do evento de manifestação

Valores	Significado
203202	Confirmação pelo tomador
204203	Confirmação pelo intermediário
203206	Rejeição pelo tomador
204207	Rejeição pelo intermediário
205204	Confirmação tácita pelo município
205208	Rejeição anulada pelo município

`itens[].manifestacao.codigoMotivo`Código do motivo da rejeição

Valores	Significado
1	Nota em duplicidade
2	O tomador já emitiu a nota por conta própria
3	O fato gerador não ocorreu, o serviço não foi prestado
4	Parte responsável errada
5	Valor ou dados incorretos
9	Outros; explique em `motivo`

Código	HTTP
10001012	400	A janela `dataInicio` / `dataFim` passa de 31 dias. Estreite a janela e pagine por períodos.
10001001	400	`pagina` / `tamanho` fora do intervalo, ou um filtro acima do tamanho máximo.
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/recebidas'

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"

{

"pagina": 1,

"tamanho": 20,

"total": 48,

"totalLimitado": false,

"itens": [

{

"chaveAcesso": "35503082406730610001340000000000000000000000000077",

"numero": 77,

"codigoVerificacao": null,

"status": "Autorizada",

"papel": "Tomador",

"origem": "ADN",

"dataEmissao": "2026-09-21T12:00:00Z",

"dataAutorizacao": "2026-09-21T12:00:03Z",

"competencia": "2026-09-01",

"prestador": { "cpfCnpj": "40673061000134", "nome": "PRESTADOR LTDA", "inscricaoMunicipal": "12345678", "codigoMunicipio": "3550308" },

"tomador": { "cpfCnpj": "66500544000120" },

"intermediario": null,

"codigoTributacaoNacional": "010701",

"discriminacao": "Servico de consultoria",

"valorServico": 1000.00,

"valorLiquido": 980.00,

"valorIss": 20.00,

"issRetido": false,

"chaveSubstituida": null,

"chaveSubstituta": null,

"dataUltimoEvento": null,

"dataRecebimento": "2026-09-21T12:15:41Z",

"manifestacao": null,

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

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

}

]

}

Listar NFS-e recebidas

Parâmetros

Parâmetros de caminho

Parâmetros de consulta

Respostas

Sincronização, webhooks e paginação

Enumerações8 tabelas

statusFiltro de status

manifestacaoFiltro de manifestação

itens[].statusStatus do documento

itens[].papelPapel desta empresa

itens[].origemOrigem da linha

itens[].manifestacao.statusEstado da manifestação

itens[].manifestacao.codigoEventoCódigo do evento de manifestação

itens[].manifestacao.codigoMotivoCódigo do motivo da rejeição

Erros3 itens