NFS-e
Consultar NFS-e
Devuelve estado, clave de acceso, eventos posteriores a la autorización, enlaces de XML / DANFSe y el eco de la solicitud.
/openapi/v2/empresas/{empresaId}/nfse/{nfseId}token, timestamp y sign, vea Autenticación.Consulta el documento por el id enviado en la emisión. La clave de acceso de la NFS-e tiene 50 dígitos y la genera la autoridad emisora, por lo que un documento que falló no tiene chaveAcesso y solo puede localizarse por identificacaoDps, el identificador de 45 caracteres de la DPS generado por la plataforma. Para la conciliación masiva use la lista de emitidas. Un documento inexistente devuelve 404.
Parámetros de ruta
empresaId* | string | Identificador de la empresa |
nfseId* | string | Id del documento |
* Campo obligatorio
id | string | Id del documento |
status | string | Estado del documento |
motivoStatus | string | Veredicto |
numero | int | Número de la NFS-e |
serie | string | Serie |
numeroDps | int | Número de la DPS |
chaveAcesso | string | Clave de acceso |
identificacaoDps | string | Identificador de la DPS |
codigoVerificacao | string | Código de verificación |
dataEmissao | string | Fecha de emisión |
dataAutorizacao | string | Fecha de autorización |
padraoMunicipal | string | Estándar municipal |
atualizadoEm | string | Último cambio de estado |
chaveSubstituida | string | Clave de la nota sustituida |
chaveSubstituta | string | Clave de la nota sustituta |
linkXml | string | Enlace del XML oficial |
linkDanfse | string | Enlace de la DANFSe |
| array | Eventos posteriores a la autorización |
nfse | object | Eco de la solicitud aceptada |
Los campos de hecho del documento (numero, chaveAcesso, enlaces, eventos) se van rellenando conforme avanza el estado. El ejemplo de respuesta de arriba es el caso Autorizada; abajo, los otros casos que cambian qué campos tienen valor.
Fallo antes de la numeración
La plataforma rechazó antes de numerar: parámetros inválidos o emisor no apto. No hay número, clave ni identificador de la DPS; concilie por el id y no espere encontrar el documento en la lista de emitidas.
{"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* | string | Estado |
motivoStatus* | string | Motivo del rechazo local |
* Campo obligatorio
Rechazada por la autoridad
La DPS fue numerada y enviada, y la autoridad la rechazó. Hay identificacaoDps pero no hay clave; motivoStatus trae el código y la descripción de la autoridad.
{"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* | string | Estado |
motivoStatus* | string | Veredicto de la autoridad |
identificacaoDps* | string | Identificador de la DPS |
* Campo obligatorio
Cancelada, con eventos
Tras una cancelación exitosa el estado es Cancelada y eventos trae el evento registrado; linkDanfse pasa a apuntar al PDF con marca de agua.
{"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* | string | Estado |
* | array | Eventos registrados |
* Campo obligatorio
- Un documento que falló antes de la numeración no tiene
chaveAcessoni número: concilie por eliddel integrador o poridentificacaoDps, y no espere encontrarlo en la lista de emitidas, que solo trae documentos ya numerados. - Si necesita los parámetros enviados, guárdelos de su lado en el momento de la emisión:
nfsese borra en el estado terminal. - Los enlaces de descarga llevan un token de corta duración y se vuelven a firmar en cada consulta; no los almacene como si fueran permanentes.
statusEstado del documento
| Valores | Significado |
|---|---|
| Pendente | Aceptado, todavía sin veredicto; cubre la cola, el envío y la conciliación |
| Autorizada | Emitida con éxito; puede cancelarse o sustituirse |
| Negada | Rechazada por la autoridad; motivoStatus trae el código y la descripción; terminal |
| Falha | Fallo del lado de la plataforma antes de la numeración, ningún documento creado; terminal |
| EmProcessoDeCancelamento | Solicitud de análisis de cancelación aceptada, a la espera del municipio; concedida pasa a Cancelada, denegada vuelve a Autorizada |
| Cancelada | Cancelada; terminal |
| Substituida | Sustituida por otra nota; chaveSubstituta trae la nueva clave; terminal |
padraoMunicipalEstándar municipal
| Valores | Significado |
|---|---|
| Nacional | Estándar nacional: emisor nacional y distribución nacional |
| Paulistana | Sistema propio del municipio de São Paulo |
eventos[].tipoTipo del evento
La lista acompaña los eventos oficiales y puede crecer.
| Valores | Significado |
|---|---|
| Cancelamento | Cancelación registrada por el prestador (101101) |
| CancelamentoPorSubstituicao | Cancelada por haber sido sustituida por otra nota (105102) |
| PedidoAnalise | Solicitud de análisis fiscal de cancelación (101103) |
| AnaliseDeferida | El municipio concedió la cancelación (105104) |
| AnaliseIndeferida | El municipio denegó la cancelación (105105) |
| CancelamentoDeOficio | Cancelación de oficio por el municipio (305101) |
| Bloqueio | Bloqueo de oficio por el municipio (305102) |
| Desbloqueio | Desbloqueo de oficio por el municipio (305103) |
| Confirmacao | Una de las partes confirmó la nota, o confirmación tácita del municipio (202201 / 203202 / 204203 / 205204) |
| Rejeicao | Una de las partes rechazó la nota (202205 / 203206 / 204207) |
| RejeicaoAnulada | El municipio anuló un rechazo (205208) |
| Outro | Evento oficial aún no modelado; el código real está en status |
eventos[].codigoCódigo oficial del evento
| Valores | Significado |
|---|---|
| 101101 | Cancelación por el prestador |
| 105102 | Cancelación por sustitución |
| 101103 | Solicitud de análisis fiscal de cancelación |
| 105104 | Análisis concedida |
| 105105 | Análisis denegada |
| 305101 | Cancelación de oficio |
| 305102 | Bloqueo de oficio |
| 305103 | Desbloqueo de oficio |
| 202201 | Confirmación por el prestador |
| 203202 | Confirmación por el tomador |
| 204203 | Confirmación por el intermediario |
| 205204 | Confirmación tácita por el municipio |
| 202205 | Rechazo por el prestador |
| 203206 | Rechazo por el tomador |
| 204207 | Rechazo por el intermediario |
| 205208 | Rechazo anulado por el municipio |
| 000000 | Evento oficial aún no modelado; el código real está en status |
| Código | HTTP | |
|---|---|---|
| 10018002 | 404 | Documento no encontrado: el nfseId no pertenece a este emisor. Verifique el nfseId y el empresaId. |
| 10018003 | 404 | Documento no encontrado: el nfseId no pertenece a este emisor. Verifique el nfseId y el empresaId. |