Endpoint utilizado para consultar as notas fiscais cadastradas na conta.

Essa operação retorna uma lista paginada de notas fiscais e permite aplicar filtros para localizar registros específicos por período de emissão, cliente, vínculo financeiro, referência externa ou situação da nota.

Diferente da recuperação de uma nota fiscal específica, este endpoint é indicado para consultas em lote, monitoramento operacional e geração de relatórios.

Quando utilizar

Este endpoint é recomendado para:

• monitoramento das notas fiscais emitidas;
• conciliação financeira;
• geração de relatórios;
• acompanhamento do processamento das notas;
• localização de notas vinculadas a cobranças, parcelamentos ou clientes específicos;
• sincronização periódica de informações entre sistemas.

Parâmetros mais importantes

Além dos parâmetros exibidos automaticamente pela referência da API, alguns filtros são especialmente úteis:

• status — permite consultar notas fiscais em estados específicos;
• effectiveDate[ge] e effectiveDate[le] — recomendados para consultas por período;
• customer — localiza notas vinculadas a um cliente específico;
• payment — localiza a nota relacionada a uma cobrança;
• externalReference — facilita a conciliação com identificadores internos do sistema.

Situações possíveis

O filtro status aceita os seguintes valores:

• SCHEDULED
• AUTHORIZED
• PROCESSING_CANCELLATION
• CANCELED
• CANCELLATION_DENIED
• ERROR

Comportamento da paginação

A listagem é paginada através dos parâmetros offset e limit.

Por padrão, recomenda-se utilizar paginação incremental para evitar consultas excessivamente grandes.

Exemplo:

GET /v3/invoices?offset=0&limit=100

Próxima página:

GET /v3/invoices?offset=100&limit=100

📘

Boas práticas

Para sincronizações em massa, prefira realizar consultas por período e utilizar paginação em vez de recuperar grandes volumes em uma única chamada.

Exemplos de filtros

Filtrar por data de emissão:

GET https://api.asaas.com/v3/invoices?effectiveDate%5Bge%5D=2018-06-03&effectiveDate%5Ble%5D=2018-06-10

Filtrar por situação:

GET https://api.asaas.com/v3/invoices?status=SCHEDULED

Filtrar por cliente:

GET https://api.asaas.com/v3/invoices?customer=cus_000005913227

Combinar filtros:

GET https://api.asaas.com/v3/invoices?status=AUTHORIZED&effectiveDate%5Bge%5D=2026-01-01&effectiveDate%5Ble%5D=2026-01-31

📘

Importante

Os filtros podem ser combinados para consultas mais específicas.

Essa estratégia é especialmente útil para conciliação financeira e geração de relatórios.

Comportamentos importantes

• Caso nenhum registro seja encontrado, a resposta retornará uma lista vazia.
• Os filtros podem ser utilizados simultaneamente.
• Consultas muito amplas podem resultar em múltiplas páginas de resposta.
• O endpoint é indicado para consultas em lote, enquanto a recuperação individual é mais adequada quando o identificador da nota já é conhecido.

Erros comuns

403 Forbidden

Chamadas GET devem ser realizadas sem body.

Caso a requisição contenha informações no corpo, será retornado:

Forbidden. Ocorre quando o body da requisição está preenchido, chamadas de método GET precisam ter um body vazio.

401 Unauthorized

Indica falha de autenticação ou utilização de uma chave de API inválida.

400 Bad Request

Ocorre quando algum parâmetro enviado possui formato inválido.

Impactos operacionais

Para ambientes com grande volume de emissão, recomenda-se:

• utilizar filtros por período;
• paginar os resultados;
• evitar consultas muito abrangentes;
• armazenar localmente os identificadores das notas fiscais para reduzir a necessidade de consultas frequentes.

Casos de uso

Esse endpoint é útil para:

• monitoramento das notas fiscais emitidas;
• conciliação financeira;
• geração de relatórios;
• acompanhamento do ciclo de emissão;
• validação do status de processamento das notas fiscais;
• sincronização entre sistemas externos.

Conteúdos relacionados

• Recuperar uma nota fiscal.
• Criar nota fiscal.
• Cancelar nota fiscal.
• Listar serviços municipais.
• Configurações para emissão de notas fiscais.