# Listar Notas Fiscais
`GET /v1/invoices/notas`
**Área:** Notas Fiscais

**Scopes necessários:** `nota.fiscal/read`

Lista as notas fiscais da conta, da mais recente para a mais antiga.

Inclui todas as origens: notas geradas por cobranças e assinaturas e também as avulsas, emitidas por POST nesta mesma rota.

### O identificador da nota

O campo `invoiceId` é o identificador usado nas demais rotas — consultar, cancelar, reemitir, reenviar e emitir. Na nota avulsa ele é o `ref` que você informou na emissão; nas notas geradas por cobrança, é o identificador da própria cobrança.

Não o confunda com o `ref` da resposta, que traz o identificador interno da nota e serve apenas para suporte.

### Status

- `PROCESSING` — enviada, a prefeitura ainda não respondeu
- `ISSUED` ou `AUTHORIZED` — autorizada. Os dois valores são equivalentes: o primeiro vem da emissão síncrona, o segundo da confirmação assíncrona da prefeitura
- `FAILED` ou `ERROR` — recusada. `nf.errors` traz as mensagens da prefeitura
- `CANCELED` — cancelada
- `REPLACED` — substituída por uma reemissão

No filtro `status` os pares são intercambiáveis: `AUTHORIZED` traz também as `ISSUED`, e `ERROR` traz também as `FAILED`.

### Paginação

Por cursor: envie em `lastKey` o valor devolvido em `pagination.lastKey`. Enquanto `pagination.hasMore` for `true`, ainda há páginas.

`emissor` identifica de qual empresa a nota saiu, útil quando a conta tem mais de uma configuração fiscal. `feeAmount` e `feeStatus` descrevem a taxa de emissão cobrada pela ValidaPay, não um tributo da nota.

Case de uso:

_Como plataforma, quero conciliar as notas do mês e conferir quais foram autorizadas antes de fechar o faturamento._

### Query parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `lastKey` | **sim** | Cursor da próxima página, de pagination.lastKey - optional |
| `search` | **sim** | Busca parcial por nome do tomador ou documento - optional |
| `taxId` | **sim** | CPF/CNPJ exato do tomador, apenas dígitos - optional |
| `customerName` | **sim** | Nome do tomador - optional |
| `status` | **sim** | AUTHORIZED (ou ISSUED), PROCESSING, ERROR (ou FAILED), CANCELED ou REPLACED - optional |
| `startDate` | **sim** | Data inicial da emissão, ISO 8601 - optional |
| `endDate` | **sim** | Data final da emissão, ISO 8601 - optional |
| `limit` | não | Itens por página (default 20) - optional |

### Resposta 200 — 200

```json
{
  "items": [
    {
      "emissor": {
        "configId": "unc_1788193720141_65g0zh12p",
        "cnpj": "99988877000108",
        "nome": "EMPRESA EXEMPLO LTDA"
      },
      "type": "NFSE",
      "invoiceId": "nf_1788101026585_uqaspo7bn",
      "chargeId": null,
      "customerId": null,
      "customerName": "Alexandre Souza",
      "taxId": "11144477735",
      "amount": 150.00,
      "emitidaEm": "2026-08-30T14:43:49.719Z",
      "ref": "2109541",
      "status": "AUTHORIZED",
      "feeStatus": "COMPLETED",
      "feeAmount": 0.37,
      "nf": {
        "id": "2109541",
        "number": "7814",
        "status": "AUTHORIZED",
        "url": "https://…",
        "pdfUrl": "https://…",
        "xmlPath": "/arquivos/…-nfse.xml",
        "xmlUrl": "https://…",
        "verificationCode": "PGRW-2TFA",
        "rpsNumber": "5053",
        "rpsSeries": "1",
        "cnpj": "99988877000108",
        "issuedAt": "2026-08-30T14:43:49.719Z",
        "errors": null
      }
    }
  ],
  "pagination": {
    "total": 1,
    "totalPages": 1,
    "limit": 20,
    "hasMore": false,
    "lastKey": null
  }
}
```

### Resposta 404 — 404

```json
{
    "error": {
        "message": "Conta não encontrada",
        "code": "ACCOUNT_NOT_FOUND",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

---
Página: https://docs.validapay.com.br/documentacao-validapay2/get-listar-notas-fiscais
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json