curl --request GET \
--url https://api.sandbox.z2pay.com/v1/invoices \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/invoices', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/invoices"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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
}
}{
"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)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}Listar faturas
Lista paginada das faturas da conta, com filtros por estado, assinatura, cliente, valor e data.
curl --request GET \
--url https://api.sandbox.z2pay.com/v1/invoices \
--header 'x-api-key: <api-key>'const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/invoices', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/invoices"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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
}
}{
"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)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}GET /invoices
Faz parte do recurso Faturas — 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.
items.
Para saber o que compõe o valor, use
GET /invoices/{id}.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.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.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
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
{
"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 }
}
publicAccessToken de propósito — o playground ao lado mostra
o corpo inteiro.Authorizations
API Key da Credential (gerada no Backoffice)
Query Parameters
Página da listagem. Padrão: 1.
x >= 1Itens por página. Padrão: 20. Máximo: 100.
1 <= x <= 100Situaçã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.
scheduled, suspended, open, paid, past_due, unpaid, canceled, refunded Faturas de uma assinatura (sub_). Correspondência exata.
Faturas de um cliente (cust_). Correspondência exata.
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.
card, pix, boleto, other Número da fatura, como aparece no painel (2026-0007). Correspondência parcial: 7 encontra 2026-0007.
20Valor total mínimo, em centavos.
x >= 0Valor total máximo, em centavos.
x >= 0Qual 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.
issued, due, paid, created, charge Início do período, em ISO 8601. Exige dateField.
Fim do período, em ISO 8601. Exige dateField.
Campo de ordenação: createdAt (emissão), dueAt (vencimento), code (número), paidAt (pagamento) ou value (total). Default: createdAt.
createdAt, dueAt, code, paidAt, value Direção da ordenação: asc ou desc. Default: desc.
asc, desc