Listar faturas

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));

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

Listar faturas

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));

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

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

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.

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

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

Resposta 200

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

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Query Parameters

page

integer

default:1

Página da listagem. Padrão: 1.

Required range: x >= 1

limit

integer

default:20

Itens por página. Padrão: 20. Máximo: 100.

Required range: 1 <= x <= 100

status

enum<string>[]

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.

Available options:

scheduled,

suspended,

open,

paid,

past_due,

unpaid,

canceled,

refunded

subscriptionId

string

Faturas de uma assinatura (sub_). Correspondência exata.

customerId

string

Faturas de um cliente (cust_). Correspondência exata.

paymentMethods

enum<string>[]

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.

Available options:

card,

pix,

boleto,

other

code

string

Número da fatura, como aparece no painel (2026-0007). Correspondência parcial: 7 encontra 2026-0007.

Maximum string length: 20

totalMin

integer

Valor total mínimo, em centavos.

Required range: x >= 0

totalMax

integer

Valor total máximo, em centavos.

Required range: x >= 0

dateField

enum<string>

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.

Available options:

issued,

due,

paid,

created,

charge

dateFrom

Início do período, em ISO 8601. Exige dateField.

dateTo

Fim do período, em ISO 8601. Exige dateField.

sortBy

enum<string>

Campo de ordenação: createdAt (emissão), dueAt (vencimento), code (número), paidAt (pagamento) ou value (total). Default: createdAt.

Available options:

createdAt,

dueAt,

code,

paidAt,

value

sortDir

enum<string>

Direção da ordenação: asc ou desc. Default: desc.

Available options:

asc,

desc

Response

Lista paginada

data

object[]

Lista de registros retornados na página atual.

Show child attributes

pagination

object

Dados de paginação do resultado.

Show child attributes

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Listar faturas

Exemplo

Authorizations

Query Parameters

Response

​Exemplo

Authorizations

Query Parameters

Response

Exemplo