NFS-e

Listar NFS-e recibidas

Lista las facturas de servicio en las que esta empresa es tomadora o intermediaria, paginadas por fecha de emisión.

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

Requiere las cabeceras de firma token, timestamp y sign, vea Autenticación.

Las facturas de servicio en las que esta empresa es tomadora o intermediaria llegan por la distribución nacional, tanto las emitidas por el emisor nacional como las compartidas por sistemas municipales como el de São Paulo, con un retraso de hasta 15 minutos. Una empresa de São Paulo recibe además las facturas obtenidas directamente del sistema municipal, con retrospectiva de 7 días. Los ítems tienen la misma forma que Consultar NFS-e recibida, sin el array eventos, que solo devuelve el detalle; la manifestación se registra en Manifestar sobre NFS-e recibida.

Parámetros de ruta

empresaId*

string

Identificador de la empresa

* Campo obligatorio

Parámetros de consulta

`dataInicio`	string	Inicio de la ventana
`dataFim`	string	Fin de la ventana
`prestadorCpfCnpj`	string	Documento del prestador
`chaveAcesso`	string	Clave de acceso
`status`	string	Filtro de estado
`manifestacao`	string	Filtro de manifestación
`pagina`	int	Página
`tamanho`	int	Tamaño de página

* Campo obligatorio

200

Una página de facturas recibidas, ordenada por fecha de emisión. Cada ítem tiene la forma de Consultar NFS-e recibida sin los eventos: eventos siempre es null en los ítems de la lista.

`pagina`	int	Página devuelta
`tamanho`	int	Tamaño de página aplicado
`total`	int	Total de facturas
`totalLimitado`	bool	Total limitado
	array	Facturas de la página

La sincronización con la distribución nacional corre cada 15 minutos por defecto; una factura recién emitida por la contraparte aparece en la ronda siguiente.
La llegada y los cambios de estado también pueden recibirse por webhook: nfse.inbound.received, nfse.inbound.canceled y nfse.inbound.substituted; el resultado de la manifestación de esta empresa por nfse.inbound.manifested y nfse.inbound.manifest_failed. Todos exigen suscripción explícita en Registrar webhook.
total es un conteo limitado: con totalLimitado=true, estreche la ventana en vez de paginar hasta el final.
Un ítem PrefeituraSP pasa a ADN por sí solo cuando llega la transcripción; no lo cuente como dos facturas. Concilie por prestador.cpfCnpj + numero, el identificador estable entre sincronizaciones.

`status`Filtro de estado

Un valor fuera de la lista se ignora, sin filtrar.

Valores	Significado
Autorizada	Válida en la autoridad
Cancelada	Cancelada
Substituida	Sustituida por otra nota

`manifestacao`Filtro de manifestación

Un valor fuera de la lista se ignora, sin filtrar.

Valores	Significado
Pendente	Todavía sin manifestación de esta empresa
Confirmada	Confirmada por esta empresa
Rejeitada	Rechazada por esta empresa
ConfirmacaoTacita	Confirmación tácita del municipio
RejeicaoAnulada	Rechazo anulado por el municipio

`itens[].status`Estado del documento

Valores	Significado
Autorizada	Válida en la autoridad
Cancelada	Cancelada por el prestador o de oficio por el municipio
Substituida	Sustituida por otra nota; `chaveSubstituta` trae la nueva clave

`itens[].papel`Papel de esta empresa

Valores	Significado
Tomador	Tomador del servicio; manifiesta con 203202 (confirmación) o 203206 (rechazo)
Intermediario	Intermediario del servicio; manifiesta con 204203 (confirmación) o 204207 (rechazo)

`itens[].origem`Origen de la fila

Valores	Significado
ADN	Distribuida por la distribución nacional
PrefeituraSP	Traída directamente del sistema municipal de São Paulo; solo empresas de São Paulo; pasa a `ADN` cuando llega la transcripción

`itens[].manifestacao.status`Estado de la manifestación

null en el campo significa sin manifestación; en el filtro de la lista ese caso es Pendente.

Valores	Significado
Confirmada	Confirmada por esta empresa (203202 / 204203); terminal
Rejeitada	Rechazada por esta empresa (203206 / 204207); el municipio todavía puede anularla
ConfirmacaoTacita	Confirmación tácita del municipio por falta de manifestación en el plazo (205204); terminal
RejeicaoAnulada	El municipio anuló el rechazo de esta empresa (205208); terminal

`itens[].manifestacao.codigoEvento`Código del evento de manifestación

Valores	Significado
203202	Confirmación por el tomador
204203	Confirmación por el intermediario
203206	Rechazo por el tomador
204207	Rechazo por el intermediario
205204	Confirmación tácita por el municipio
205208	Rechazo anulado por el municipio

`itens[].manifestacao.codigoMotivo`Código del motivo del rechazo

Valores	Significado
1	Nota duplicada
2	El tomador ya emitió la nota por su cuenta
3	El hecho imponible no ocurrió, el servicio no fue prestado
4	Parte responsable equivocada
5	Importe o datos incorrectos
9	Otros; explique en `motivo`

Código	HTTP
10001012	400	La ventana `dataInicio` / `dataFim` supera los 31 días. Estréchela y pagine por períodos.
10001001	400	`pagina` / `tamanho` fuera de rango, o un filtro por encima del tamaño máximo.
10003000	404	`empresaId` no existe o no pertenece a esta aplicación.

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 recibidas

Parámetros

Parámetros de ruta

Parámetros de consulta

Respuestas

Sincronización, webhooks y paginación

Enumeraciones8 tablas

statusFiltro de estado

manifestacaoFiltro de manifestación

itens[].statusEstado del documento

itens[].papelPapel de esta empresa

itens[].origemOrigen de la fila

itens[].manifestacao.statusEstado de la manifestación

itens[].manifestacao.codigoEventoCódigo del evento de manifestación

itens[].manifestacao.codigoMotivoCódigo del motivo del rechazo

Errores3 ítems