NFS-e
List received NFS-e
Lists the service invoices in which this company is the recipient or intermediary, paged by issue time.
GET
/openapi/v2/empresas/{empresaId}/nfse/recebidasRequires the
token, timestamp and sign signature headers, see Authentication.The service invoices in which this company is the recipient or intermediary arrive through the national distribution, both those issued by the national issuer and those shared by municipal systems such as São Paulo, with a delay of up to 15 minutes. A São Paulo company also receives invoices pulled directly from the municipal system, with a 7-day look-back. Items are shaped like Query received NFS-e, without the eventos array, which only the detail returns; manifestations are registered with Manifest on received NFS-e.
Path parameters
empresaId* | string | Company identifier |
* Required field
Query parameters
dataInicio | string | Window start |
dataFim | string | Window end |
prestadorCpfCnpj | string | Provider document |
chaveAcesso | string | Access key |
status | string | Status filter |
manifestacao | string | Manifestation filter |
pagina | int | Page |
tamanho | int | Page size |
* Required field
200
A page of received invoices ordered by issue time. Each item is shaped like Query received NFS-e without the events:
eventos is always null on list items.pagina | int | Page returned |
tamanho | int | Page size applied |
total | int | Total invoices |
totalLimitado | bool | Total capped |
| array | Invoices on the page |
- The sync with the national distribution runs every 15 minutes by default; an invoice the counterparty has just issued shows up on the next round.
- Arrival and status changes can also be pushed by webhook:
nfse.inbound.received,nfse.inbound.canceledandnfse.inbound.substituted; the manifestation outcome for this company bynfse.inbound.manifestedandnfse.inbound.manifest_failed. All of them require an explicit subscription in Register webhook. totalis a capped count: withtotalLimitado=true, narrow the window instead of paging to the end.- A
PrefeituraSPitem switches toADNon its own once the transcription arrives; do not count that as two invoices. Reconcile onprestador.cpfCnpj+numero, the identifier that is stable across syncs.
statusStatus filter
A value outside the list is ignored, no filter applied.
| Values | Meaning |
|---|---|
| Autorizada | Valid at the authority |
| Cancelada | Cancelled |
| Substituida | Replaced by another invoice |
manifestacaoManifestation filter
A value outside the list is ignored, no filter applied.
| Values | Meaning |
|---|---|
| Pendente | Not manifested by this company yet |
| Confirmada | Confirmed by this company |
| Rejeitada | Rejected by this company |
| ConfirmacaoTacita | Tacit confirmation by the municipality |
| RejeicaoAnulada | Rejection annulled by the municipality |
itens[].statusDocument status
| Values | Meaning |
|---|---|
| Autorizada | Valid at the authority |
| Cancelada | Cancelled by the provider or of record by the municipality |
| Substituida | Replaced by another invoice; chaveSubstituta carries the new key |
itens[].papelRole of this company
| Values | Meaning |
|---|---|
| Tomador | Service recipient; manifests with 203202 (confirmation) or 203206 (rejection) |
| Intermediario | Service intermediary; manifests with 204203 (confirmation) or 204207 (rejection) |
itens[].origemRow origin
| Values | Meaning |
|---|---|
| ADN | Delivered by the national distribution |
| PrefeituraSP | Pulled straight from the São Paulo municipal system; São Paulo companies only; becomes ADN once the transcription arrives |
itens[].manifestacao.statusManifestation state
null in the field means not manifested; in the list filter that case is Pendente.
| Values | Meaning |
|---|---|
| Confirmada | Confirmed by this company (203202 / 204203); terminal |
| Rejeitada | Rejected by this company (203206 / 204207); the municipality may still annul it |
| ConfirmacaoTacita | Tacit confirmation by the municipality for lack of manifestation within the deadline (205204); terminal |
| RejeicaoAnulada | The municipality annulled this company rejection (205208); terminal |
itens[].manifestacao.codigoEventoManifestation event code
| Values | Meaning |
|---|---|
| 203202 | Confirmation by the recipient |
| 204203 | Confirmation by the intermediary |
| 203206 | Rejection by the recipient |
| 204207 | Rejection by the intermediary |
| 205204 | Tacit confirmation by the municipality |
| 205208 | Rejection annulled by the municipality |
itens[].manifestacao.codigoMotivoRejection reason code
| Values | Meaning |
|---|---|
| 1 | Duplicate invoice |
| 2 | The recipient already issued the invoice itself |
| 3 | The taxable event did not occur, the service was not provided |
| 4 | Wrong responsible party |
| 5 | Wrong amount or data |
| 9 | Other; explain in motivo |
| Code | HTTP | |
|---|---|---|
| 10001012 | 400 | The dataInicio / dataFim window is longer than 31 days. Narrow it and page period by period. |
| 10001001 | 400 | pagina / tamanho out of range, or a filter over its maximum length. |
| 10003000 | 404 | empresaId does not exist or does not belong to this application. |