> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar faturas
> Lista paginada das faturas da conta, com filtros por estado, assinatura, cliente, valor e data.
`GET /invoices`
Faz parte do recurso [Faturas](/pt-BR/subscriptions/invoices) — o conceito, os oito estados e os
links hospedados estão lá.
Devolve as faturas da sua conta em páginas de 20 por padrão, da mais recente para a mais antiga. Os
filtros são opcionais e se somam: quem envia mais de um recebe só as faturas que atendem a todos.
**A listagem não traz os itens.** Cada linha é a fatura — estado, totais, datas —, sem `items`.
Para saber o que compõe o valor, use
[`GET /invoices/{id}`](/pt-BR/subscriptions/invoices/get).
**Cada linha traz um `publicAccessToken`.** Ele é a credencial de pagamento daquela fatura, e uma
página inteira devolve vários de uma vez. Não registre o corpo desta resposta em log de aplicação
nem o envie a ferramenta de terceiro. Ver
[Os dois links](/pt-BR/subscriptions/invoices).
**`dateFrom` e `dateTo` exigem `dateField`.** É ele que diz qual data o período filtra —
`issued`, `due`, `paid`, `created` ou `charge`. Sem ele, o intervalo não tem sobre o que incidir.
É a diferença entre perguntas parecidas: `due` no passado lista o que venceu; `paid` no mês lista
o que entrou; `charge` amanhã lista o que o motor vai tentar cobrar.
**`scheduled` também aparece.** Sem filtro de estado, a resposta traz faturas que ainda nem
ficaram pagáveis, junto com as pagas e as canceladas. Para o que está em aberto de verdade, filtre
`?status=open,past_due`.
**Em fatura não paga, `paymentMethods` filtra o que está oferecido**, não o que foi usado — o
método só se define no pagamento. Na fatura paga, filtra o que efetivamente pagou.
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/invoices \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-d status=open,past_due \
-d dateField=due \
-d dateTo=2026-08-10T23:59:59-03:00 \
-d limit=20
```
```json Resposta 200 theme={null}
{
"data": [
{
"id": "inv_wkiu3z9t8e97or7aygbiyxah9",
"number": { "year": 2026, "sequence": 7 },
"subscriptionId": "sub_e3ga045sifx4s5yj3gaadlap8",
"customerId": "cust_rd89e9ywte9u1r0685iifg23v",
"customerName": "Maria Souza",
"customerEmail": "maria@exemplo.com",
"status": "open",
"kind": "recurring",
"currency": "BRL",
"chargeAt": "2026-08-05T09:00:00.000Z",
"dueAt": "2026-08-10T00:00:00.000Z",
"subtotal": 18990,
"taxTotal": 0,
"total": 18990,
"amountPaid": 0,
"amountRemaining": 18990,
"amountRefunded": 0,
"installments": 1,
"createdAt": "2026-07-29T09:00:00.000Z"
}
],
"pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
```
O exemplo está abreviado e omite o `publicAccessToken` de propósito — o playground ao lado mostra
o corpo inteiro.
## OpenAPI
````yaml openapi/billing.json GET /invoices
openapi: 3.0.3
info:
title: Z2Pay Billing API
version: 1.0.0
description: Cobrança recorrente da Z2Pay — planos, assinaturas e faturas
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Invoices
description: Faturas emitidas pelas assinaturas
- name: Plans
description: Planos de cobrança e versões de preço
- name: Subscriptions
description: Assinaturas recorrentes
paths:
/invoices:
get:
tags:
- Invoices
summary: Listar faturas
description: 'Lista paginada com filtros opcionais: status, subscriptionId, customerId'
operationId: InvoiceController_list
parameters:
- name: page
in: query
required: false
description: 'Página da listagem. Padrão: 1.'
schema:
type: integer
minimum: 1
default: 1
description: 'Página da listagem. Padrão: 1.'
- name: limit
in: query
required: false
description: 'Itens por página. Padrão: 20. Máximo: 100.'
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: 'Itens por página. Padrão: 20. Máximo: 100.'
- name: status
in: query
required: false
description: >-
Situação da fatura. Aceita vários valores, separados por vírgula ou
repetindo o parâmetro. Um valor inválido responde 400 com a lista
dos aceitos.
schema:
type: array
items:
type: string
enum:
- scheduled
- suspended
- open
- paid
- past_due
- unpaid
- canceled
- refunded
description: >-
Situação da fatura. Aceita vários valores, separados por vírgula
ou repetindo o parâmetro. Um valor inválido responde 400 com a
lista dos aceitos.
- name: subscriptionId
in: query
required: false
description: Faturas de uma assinatura (`sub_`). Correspondência exata.
schema:
type: string
description: Faturas de uma assinatura (`sub_`). Correspondência exata.
- name: customerId
in: query
required: false
description: Faturas de um cliente (`cust_`). Correspondência exata.
schema:
type: string
description: Faturas de um cliente (`cust_`). Correspondência exata.
- name: paymentMethods
in: query
required: false
description: >-
Forma de pagamento. Na fatura paga, a que foi usada; na não paga, a
do contrato. Aceita vários valores, separados por vírgula ou
repetindo o parâmetro.
schema:
type: array
items:
type: string
enum:
- card
- pix
- boleto
- other
description: >-
Forma de pagamento. Na fatura paga, a que foi usada; na não paga,
a do contrato. Aceita vários valores, separados por vírgula ou
repetindo o parâmetro.
- name: code
in: query
required: false
description: >-
Número da fatura, como aparece no painel (`2026-0007`).
Correspondência **parcial**: `7` encontra `2026-0007`.
schema:
type: string
maxLength: 20
description: >-
Número da fatura, como aparece no painel (`2026-0007`).
Correspondência **parcial**: `7` encontra `2026-0007`.
- name: totalMin
in: query
required: false
description: Valor total mínimo, em centavos.
schema:
type: integer
minimum: 0
description: Valor total mínimo, em centavos.
- name: totalMax
in: query
required: false
description: Valor total máximo, em centavos.
schema:
type: integer
minimum: 0
description: Valor total máximo, em centavos.
- name: dateField
in: query
required: false
description: >-
Qual data o período `dateFrom`/`dateTo` filtra: `issued` (emissão),
`due` (vencimento), `paid` (pagamento), `created` (criação) ou
`charge` (cobrança). Sem ele, o período não é aplicado.
schema:
type: string
enum:
- issued
- due
- paid
- created
- charge
description: >-
Qual data o período `dateFrom`/`dateTo` filtra: `issued`
(emissão), `due` (vencimento), `paid` (pagamento), `created`
(criação) ou `charge` (cobrança). Sem ele, o período não é
aplicado.
- name: dateFrom
in: query
required: false
description: Início do período, em ISO 8601. Exige `dateField`.
schema:
type: string
oneOf:
- type: string
format: date-time
- type: string
description: Início do período, em ISO 8601. Exige `dateField`.
- name: dateTo
in: query
required: false
description: Fim do período, em ISO 8601. Exige `dateField`.
schema:
type: string
oneOf:
- type: string
format: date-time
- type: string
description: Fim do período, em ISO 8601. Exige `dateField`.
- name: sortBy
in: query
required: false
description: >-
Campo de ordenação: `createdAt` (emissão), `dueAt` (vencimento),
`code` (número), `paidAt` (pagamento) ou `value` (total). Default:
`createdAt`.
schema:
type: string
enum:
- createdAt
- dueAt
- code
- paidAt
- value
description: >-
Campo de ordenação: `createdAt` (emissão), `dueAt` (vencimento),
`code` (número), `paidAt` (pagamento) ou `value` (total). Default:
`createdAt`.
- name: sortDir
in: query
required: false
description: 'Direção da ordenação: `asc` ou `desc`. Default: `desc`.'
schema:
type: string
enum:
- asc
- desc
description: 'Direção da ordenação: `asc` ou `desc`. Default: `desc`.'
responses:
'200':
description: Lista paginada
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
number:
type: object
properties:
year:
type: integer
description: Ano de referência da numeração da fatura.
sequence:
type: integer
description: >-
Número sequencial do documento dentro da
numeração (assinatura ou fatura).
description: Número do endereço.
customerId:
type: string
description: ID do cliente associado ao registro.
customerEmail:
type: string
description: E-mail do cliente.
customerName:
type: string
description: Nome do cliente.
customerDocument:
type: string
description: Documento do cliente (CPF ou CNPJ).
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
subscriptionId:
type: string
description: ID da assinatura relacionada ao registro.
kind:
type: string
enum:
- enrollment
- recurring
- manual
description: >-
Origem da fatura: `enrollment` (adesão), `recurring`
(ciclo da assinatura) ou `manual` (avulsa).
billingGroupId:
nullable: true
description: >-
ID do grupo de cobrança ao qual o registro pertence;
nulo se não agrupado.
status:
type: string
enum:
- scheduled
- suspended
- open
- paid
- past_due
- unpaid
- canceled
- refunded
description: >-
Status atual do registro (assinatura, fatura, plano
ou slip de pagamento).
periodStart:
type: string
format: date-time
description: >-
Início do período coberto pela fatura ou pela linha
(ISO 8601).
periodEnd:
type: string
format: date-time
description: >-
Fim do período coberto pela fatura ou pela linha
(ISO 8601).
chargeAt:
type: string
format: date-time
description: Data e hora em que a fatura será cobrada (ISO 8601).
dueAt:
type: string
format: date-time
description: Data e hora de vencimento da fatura (ISO 8601).
issuedAt:
type: string
format: date-time
description: Data e hora de emissão da fatura (ISO 8601).
nullable: true
paidAt:
type: string
format: date-time
description: >-
Data e hora em que a fatura foi paga; nula se não
paga (ISO 8601).
nullable: true
canceledAt:
nullable: true
description: >-
Data e hora do cancelamento; nula se não cancelado
(ISO 8601).
subtotal:
type: integer
description: >-
Soma dos itens da fatura antes de impostos, em
centavos.
taxTotal:
type: integer
description: Total de impostos da fatura, em centavos.
total:
type: integer
description: Valor total da fatura, em centavos.
amountPaid:
type: integer
description: Valor já pago da fatura, em centavos.
amountRemaining:
type: integer
description: Valor ainda em aberto da fatura, em centavos.
amountRefunded:
type: integer
description: Valor reembolsado da fatura, em centavos.
taxLines:
type: array
items: {}
description: Detalhamento dos impostos aplicados à fatura.
adjustments:
type: array
items: {}
description: >-
Multa e juros lançados por fora do principal. Vem
vazio quando não há encargo — é por isso que a soma
dos itens pode dar menos que o `total` de uma fatura
vencida.
collectionMethod:
type: string
enum:
- charge_automatically
description: >-
Como a fatura é cobrada. Hoje só a cobrança
automática na forma de pagamento padrão.
installments:
type: integer
description: Número de parcelas da cobrança da fatura.
splitConfig:
nullable: true
description: >-
Configuração de divisão (split) dos valores entre
recebedores; nula se sem split.
paidWithPaymentMethodRef:
type: object
properties:
id:
type: string
description: Identificador único do registro.
nullable: true
type:
type: string
description: >-
Tipo da referência: meio da forma de pagamento
(card, pix, boleto) ou natureza da linha da
fatura.
description: >-
Referência da forma de pagamento com que a fatura
foi paga.
nullable: true
metadata:
type: object
properties: {}
description: >-
Metadados livres (pares chave-valor) para uso do
integrador; não afeta o processamento.
publicAccessToken:
type: string
description: >-
Token de acesso público para o cliente visualizar e
pagar a fatura.
allowedPaymentMethods:
nullable: true
description: Formas de pagamento aceitas para quitar a fatura.
installmentsConfig:
nullable: true
description: >-
Configuração de parcelamento da fatura (máximo de
parcelas, parcelas sem juros e taxa de juros).
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Data e hora da última atualização do registro (ISO
8601).
description: Lista de registros retornados na página atual.
pagination:
type: object
properties:
page:
type: integer
description: Página atual retornada.
limit:
type: integer
description: Quantidade de itens por página.
total:
type: integer
description: Total de itens que atendem ao filtro.
totalPages:
type: integer
description: Total de páginas disponíveis.
description: Dados de paginação do resultado.
example:
data:
- id: inv_c3qahi4qnkc258lfc14gplupt
number:
year: 2025
sequence: 128
customerId: cust_c72q6ogr9iko0we85mqal04te
customerEmail: maria.silva@example.com
customerName: Maria Silva
customerDocument: '12345678909'
currency: BRL
subscriptionId: sub_hsm2kigu74htdxj3nw2z6f9xw
kind: recurring
billingGroupId: null
status: paid
periodStart: '2025-06-01T03:00:00.000Z'
periodEnd: '2025-07-01T03:00:00.000Z'
chargeAt: '2025-06-01T03:00:00.000Z'
dueAt: '2025-06-01T03:00:00.000Z'
issuedAt: '2025-06-01T03:00:00.000Z'
paidAt: '2025-06-01T13:46:12.000Z'
canceledAt: null
subtotal: 9990
taxTotal: 0
total: 9990
amountPaid: 9990
amountRemaining: 0
amountRefunded: 0
taxLines: []
adjustments: []
collectionMethod: charge_automatically
installments: 1
splitConfig: null
paidWithPaymentMethodRef:
id: crd_tsj66oabsygc9kwvvzt8189f9
type: card
metadata: {}
publicAccessToken: itk_qv8n3pk2wsd7ryf5htzc9x4bm
allowedPaymentMethods: null
installmentsConfig: null
createdAt: '2025-06-01T03:00:00.000Z'
updatedAt: '2025-06-01T13:46:12.000Z'
pagination:
page: 1
limit: 20
total: 1
totalPages: 1
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````