Buscar fatura por ID

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/invoices/{id} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/invoices/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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": "open",
  "periodStart": "2025-07-01T03:00:00.000Z",
  "periodEnd": "2025-08-01T03:00:00.000Z",
  "chargeAt": "2025-07-01T03:00:00.000Z",
  "dueAt": "2025-07-03T03:00:00.000Z",
  "issuedAt": "2025-07-01T03:00:00.000Z",
  "paidAt": null,
  "canceledAt": null,
  "subtotal": 9990,
  "taxTotal": 0,
  "total": 9990,
  "amountPaid": 0,
  "amountRemaining": 9990,
  "amountRefunded": 0,
  "taxLines": [],
  "adjustments": [],
  "collectionMethod": "charge_automatically",
  "installments": 1,
  "splitConfig": null,
  "paidWithPaymentMethodRef": null,
  "metadata": {},
  "publicAccessToken": "itk_qv8n3pk2wsd7ryf5htzc9x4bm",
  "allowedPaymentMethods": [
    "pix",
    "boleto"
  ],
  "installmentsConfig": null,
  "items": [
    {
      "id": "line_moc9ac1hhm3knowcx09ontk0x",
      "invoiceId": "inv_wkiu3z9t8e97or7aygbiyxah9",
      "subscriptionId": "sub_e3ga045sifx4s5yj3gaadlap8",
      "subscriptionItemId": "subi_wq3n8fk52hbdzr7m0aeypvcjt",
      "priceVersionId": "price_l1r8693wk6ksbd9044bwvwu93",
      "type": "subscription",
      "description": "Plano Pro — mensal",
      "quantity": 1,
      "unitAmount": 18990,
      "amount": 18990,
      "periodStart": "2026-08-10T00:00:00.000Z",
      "periodEnd": "2026-09-10T00:00:00.000Z",
      "createdAt": "2026-08-05T09:00:00.000Z"
    }
  ],
  "createdAt": "2025-07-01T03:00:00.000Z",
  "updatedAt": "2025-07-01T03:00:00.000Z"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Invoice not found"
  }
}

GET

invoices

{id}

Buscar fatura por ID

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/invoices/{id} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/invoices/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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": "open",
  "periodStart": "2025-07-01T03:00:00.000Z",
  "periodEnd": "2025-08-01T03:00:00.000Z",
  "chargeAt": "2025-07-01T03:00:00.000Z",
  "dueAt": "2025-07-03T03:00:00.000Z",
  "issuedAt": "2025-07-01T03:00:00.000Z",
  "paidAt": null,
  "canceledAt": null,
  "subtotal": 9990,
  "taxTotal": 0,
  "total": 9990,
  "amountPaid": 0,
  "amountRemaining": 9990,
  "amountRefunded": 0,
  "taxLines": [],
  "adjustments": [],
  "collectionMethod": "charge_automatically",
  "installments": 1,
  "splitConfig": null,
  "paidWithPaymentMethodRef": null,
  "metadata": {},
  "publicAccessToken": "itk_qv8n3pk2wsd7ryf5htzc9x4bm",
  "allowedPaymentMethods": [
    "pix",
    "boleto"
  ],
  "installmentsConfig": null,
  "items": [
    {
      "id": "line_moc9ac1hhm3knowcx09ontk0x",
      "invoiceId": "inv_wkiu3z9t8e97or7aygbiyxah9",
      "subscriptionId": "sub_e3ga045sifx4s5yj3gaadlap8",
      "subscriptionItemId": "subi_wq3n8fk52hbdzr7m0aeypvcjt",
      "priceVersionId": "price_l1r8693wk6ksbd9044bwvwu93",
      "type": "subscription",
      "description": "Plano Pro — mensal",
      "quantity": 1,
      "unitAmount": 18990,
      "amount": 18990,
      "periodStart": "2026-08-10T00:00:00.000Z",
      "periodEnd": "2026-09-10T00:00:00.000Z",
      "createdAt": "2026-08-05T09:00:00.000Z"
    }
  ],
  "createdAt": "2025-07-01T03:00:00.000Z",
  "updatedAt": "2025-07-01T03:00:00.000Z"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Invoice not found"
  }
}

GET /invoices/:id Faz parte do recurso Faturas — o conceito, os oito estados e os links hospedados estão lá. Devolve a fatura completa: os totais, as datas do ciclo de cobrança e os items que compõem o valor. Não existe rota separada para os itens — são poucos, nascem e morrem com a fatura e não têm ação própria.

Os quatro valores respondem perguntas diferentes. total é o que a fatura cobra; amountPaid o que já entrou; amountRemaining o que falta; amountRefunded o que voltou depois de pago. Numa fatura refunded, amountPaid continua preenchido — o pagamento aconteceu, e o estorno é um fato posterior, não um desfazimento do primeiro.

chargeAt e dueAt não são a mesma data. chargeAt é quando a fatura deixa de ser scheduled e a cobrança é tentada; dueAt é o vencimento. Em boleto e PIX eles se separam por alguns dias, porque a slip é registrada com antecedência. Ver Ciclos.

kind diz de onde a fatura veio e não muda depois: recurring é o ciclo regular, enrollment é a adesão cobrada na primeira fatura, e manual é a avulsa lançada pelo painel. A avulsa não tem período de serviço — periodStart e periodEnd vêm nulos.

type distingue as linhas do item: subscription é a linha do ciclo e one_time é a cobrança única — adesão ou fatura avulsa.

Multa e juros não entram nos itens. Eles vivem em adjustments, por fora do principal — a lista vem vazia quando não há encargo. É por isso que somar os items pode dar menos que o total de uma fatura vencida.

paidWithPaymentMethodRef é o retrato de como foi pago, gravado quando a fatura vira paid e imutável depois. Ele não acompanha a troca de forma de pagamento da assinatura: a fatura antiga continua mostrando o que a quitou. Em fatura não paga, vem nulo.

A resposta traz o publicAccessToken. É a credencial que abre a página de pagamento daquela fatura, sem login. Trate-o como senha. Ver Os dois links.

Exemplo

curl https://api.sandbox.z2pay.com/v1/invoices/inv_wkiu3z9t8e97or7aygbiyxah9 \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Resposta 200

{
  "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",
  "issuedAt": "2026-08-05T09:00:00.000Z",
  "paidAt": null,
  "canceledAt": null,
  "periodStart": "2026-08-10T00:00:00.000Z",
  "periodEnd": "2026-09-10T00:00:00.000Z",
  "subtotal": 18990,
  "taxTotal": 0,
  "total": 18990,
  "amountPaid": 0,
  "amountRemaining": 18990,
  "amountRefunded": 0,
  "installments": 1,
  "items": [
    {
      "id": "line_moc9ac1hhm3knowcx09ontk0x",
      "invoiceId": "inv_wkiu3z9t8e97or7aygbiyxah9",
      "subscriptionId": "sub_e3ga045sifx4s5yj3gaadlap8",
      "type": "subscription",
      "description": "Plano Pro — mensal",
      "quantity": 1,
      "unitAmount": 18990,
      "amount": 18990,
      "periodStart": "2026-08-10T00:00:00.000Z",
      "periodEnd": "2026-09-10T00:00:00.000Z",
      "createdAt": "2026-08-05T09:00:00.000Z"
    }
  ],
  "createdAt": "2026-07-29T09:00:00.000Z",
  "updatedAt": "2026-08-05T09:00:00.000Z"
}

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)

Path Parameters

string

required

ID da fatura

Response

Fatura com os itens que compõem o total

string

Identificador único do registro.

number

object

Número do endereço.

Show child attributes

customerId

string

ID do cliente associado ao registro.

customerEmail

string

E-mail do cliente.

customerName

string

Nome do cliente.

customerDocument

string

Documento do cliente (CPF ou CNPJ).

currency

string

Moeda no padrão ISO 4217 (ex.: BRL).

subscriptionId

string

ID da assinatura relacionada ao registro.

kind

enum<string>

Origem da fatura: enrollment (adesão), recurring (ciclo da assinatura) ou manual (avulsa).

Available options:

enrollment,

recurring,

manual

billingGroupId

any | null

ID do grupo de cobrança ao qual o registro pertence; nulo se não agrupado.

status

enum<string>

Status atual do registro (assinatura, fatura, plano ou slip de pagamento).

Available options:

scheduled,

suspended,

open,

paid,

past_due,

unpaid,

canceled,

refunded

periodStart

string<date-time>

Início do período coberto pela fatura ou pela linha (ISO 8601).

periodEnd

string<date-time>

Fim do período coberto pela fatura ou pela linha (ISO 8601).

chargeAt

string<date-time>

Data e hora em que a fatura será cobrada (ISO 8601).

dueAt

string<date-time>

Data e hora de vencimento da fatura (ISO 8601).

issuedAt

string<date-time> | null

Data e hora de emissão da fatura (ISO 8601).

paidAt

string<date-time> | null

Data e hora em que a fatura foi paga; nula se não paga (ISO 8601).

canceledAt

any | null

Data e hora do cancelamento; nula se não cancelado (ISO 8601).

subtotal

integer

Soma dos itens da fatura antes de impostos, em centavos.

taxTotal

integer

Total de impostos da fatura, em centavos.

total

integer

Valor total da fatura, em centavos.

amountPaid

integer

Valor já pago da fatura, em centavos.

amountRemaining

integer

Valor ainda em aberto da fatura, em centavos.

amountRefunded

integer

Valor reembolsado da fatura, em centavos.

taxLines

any[]

Detalhamento dos impostos aplicados à fatura.

adjustments

any[]

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

enum<string>

Como a fatura é cobrada. Hoje só a cobrança automática na forma de pagamento padrão.

Available options:

charge_automatically

installments

integer

Número de parcelas da cobrança da fatura.

splitConfig

any | null

Configuração de divisão (split) dos valores entre recebedores; nula se sem split.

paidWithPaymentMethodRef

object | null

Referência da forma de pagamento com que a fatura foi paga.

Show child attributes

metadata

object

Metadados livres (pares chave-valor) para uso do integrador; não afeta o processamento.

publicAccessToken

string

Token de acesso público para o cliente visualizar e pagar a fatura.

allowedPaymentMethods

string[]

Formas de pagamento aceitas para quitar a fatura.

installmentsConfig

any | null

Configuração de parcelamento da fatura (máximo de parcelas, parcelas sem juros e taxa de juros).

items

object[]

Linhas que compõem o total da fatura. Não há rota separada para elas.

Show child attributes

createdAt

string<date-time>

Data e hora de criação do registro (ISO 8601).

updatedAt

string<date-time>

Data e hora da última atualização do registro (ISO 8601).

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Buscar fatura por ID

Exemplo

Authorizations

Path Parameters

Response

​Exemplo

Authorizations

Path Parameters

Response

Exemplo