Notas Fiscais

Listar Notas Fiscais

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

GET/v1/invoices/notas

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

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.

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

nota.fiscal/read

Query Parameters

limitopcional

Itens por página (default 20)

lastKeyopcional

Cursor da próxima página, de pagination.lastKey

searchopcional

Busca parcial por nome do tomador ou documento

taxIdopcional

CPF/CNPJ exato do tomador, apenas dígitos

customerNameopcional

Nome do tomador

statusopcional

AUTHORIZED (ou ISSUED), PROCESSING, ERROR (ou FAILED), CANCELED ou REPLACED

startDateopcional

Data inicial da emissão, ISO 8601

endDateopcional

Data final da emissão, ISO 8601

← Anterior

Churn

Resumo de Notas Fiscais

const url = 'https://sandbox.validapay.com.br/v1/invoices/notas?limit=20';

const options = {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer {{token}}'
  },
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

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
  }
}

404▾

JSON

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

← Anterior

Churn

Resumo de Notas Fiscais