Notas Fiscais

Listar Notas Fiscais

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.

GET/v1/invoices/notas

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

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

Authorizations

bearer

Authorization

string · header · required

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

Escopos requeridos

nota.fiscal/read

Query Parameters

Name	Type	Value	Required	Description
limit	-	20	Optional	Itens por página (default 20) - optional
lastKey	-	-	Required	Cursor da próxima página, de pagination.lastKey - optional
search	-	-	Required	Busca parcial por nome do tomador ou documento - optional
taxId	-	-	Required	CPF/CNPJ exato do tomador, apenas dígitos - optional
customerName	-	-	Required	Nome do tomador - optional
status	-	-	Required	AUTHORIZED (ou ISSUED), PROCESSING, ERROR (ou FAILED), CANCELED ou REPLACED - optional
startDate	-	-	Required	Data inicial da emissão, ISO 8601 - optional
endDate	-	-	Required	Data final da emissão, ISO 8601 - optional

← Anterior

Calcular Pro Rata

Resumo de Notas Fiscais

const url = 'https://sandbox.validapay.com.br/v1/invoices/notas?limit=20&lastKey=&search=&taxId=&customerName=&status=&startDate=&endDate=?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

200200

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

404404

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

← Anterior

Calcular Pro Rata

Resumo de Notas Fiscais