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));import requests
url = "https://api.sandbox.z2pay.com/v1/invoices/{id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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"
}
}Buscar fatura por ID
Retorna a fatura com os itens que compõem o total.
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));import requests
url = "https://api.sandbox.z2pay.com/v1/invoices/{id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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.
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, fatura avulsa ou uma
cobrança extra que entrou nesta fatura.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.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"
{
"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"
}
publicAccessToken de propósito — o playground ao lado mostra
o corpo inteiro.Authorizations
API Key da Credential (gerada no Backoffice)
Path Parameters
ID da fatura
Response
Fatura com os itens que compõem o total
Identificador único do registro.
Número do endereço.
Show child attributes
Show child attributes
ID do cliente associado ao registro.
E-mail do cliente.
Nome do cliente.
Documento do cliente (CPF ou CNPJ).
Moeda no padrão ISO 4217 (ex.: BRL).
ID da assinatura relacionada ao registro.
Origem da fatura: enrollment (adesão), recurring (ciclo da assinatura), manual (avulsa, lançada dentro de uma assinatura) ou standalone (venda rápida com data de cobrança, sem assinatura — aí subscriptionId vem nulo).
enrollment, recurring, manual, standalone ID do grupo de cobrança ao qual o registro pertence; nulo se não agrupado.
Status atual do registro (assinatura, fatura, plano ou slip de pagamento).
scheduled, suspended, open, paid, past_due, unpaid, canceled, refunded Início do período coberto pela fatura ou pela linha (ISO 8601).
Fim do período coberto pela fatura ou pela linha (ISO 8601).
Data e hora em que a fatura será cobrada (ISO 8601).
Data e hora de vencimento da fatura (ISO 8601).
Data e hora de emissão da fatura (ISO 8601).
Data e hora em que a fatura foi paga; nula se não paga (ISO 8601).
Data e hora do cancelamento; nula se não cancelado (ISO 8601).
Soma dos itens da fatura antes de impostos, em centavos.
Total de impostos da fatura, em centavos.
Valor total da fatura, em centavos.
Valor já pago da fatura, em centavos.
Valor ainda em aberto da fatura, em centavos.
Valor reembolsado da fatura, em centavos.
Detalhamento dos impostos aplicados à fatura.
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.
Como a fatura é cobrada. Hoje só a cobrança automática na forma de pagamento padrão.
charge_automatically Número de parcelas da cobrança da fatura.
Configuração de divisão (split) dos valores entre recebedores; nula se sem split.
Referência da forma de pagamento com que a fatura foi paga.
Show child attributes
Show child attributes
Metadados livres (pares chave-valor) para uso do integrador; não afeta o processamento.
Token de acesso público para o cliente visualizar e pagar a fatura.
Formas de pagamento aceitas para quitar a fatura.
Configuração de parcelamento da fatura (máximo de parcelas, parcelas sem juros e taxa de juros).
Linhas que compõem o total da fatura. Não há rota separada para elas.
Show child attributes
Show child attributes
Data e hora de criação do registro (ISO 8601).
Data e hora da última atualização do registro (ISO 8601).