> ## 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.
# Buscar fatura por ID
> Retorna a fatura com os itens que compõem o total.
`GET /invoices/:id`
Faz parte do recurso [Faturas](/pt-BR/subscriptions/invoices) — 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](/pt-BR/subscriptions/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](/pt-BR/subscriptions/invoices).
## Exemplo
```bash theme={null}
curl https://api.sandbox.z2pay.com/v1/invoices/inv_wkiu3z9t8e97or7aygbiyxah9 \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json Resposta 200 theme={null}
{
"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.
## OpenAPI
````yaml openapi/billing.json GET /invoices/{id}
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/{id}:
get:
tags:
- Invoices
summary: Buscar fatura por ID
description: >-
Retorna a fatura com os `items` que compõem o total — a linha do ciclo,
o rateio de uma mudança no meio do período (`proration`, que pode ser
negativo) e a adesão. Não há rota separada para eles: são poucos, nascem
e morrem com a fatura e não têm ação própria.
operationId: InvoiceController_getById
parameters:
- name: id
in: path
required: true
description: ID da fatura
schema:
type: string
responses:
'200':
description: Fatura com os itens que compõem o total
content:
application/json:
schema:
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:
type: array
items:
type: string
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).
items:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
invoiceId:
type: string
description: ID da fatura à qual a linha pertence.
subscriptionId:
type: string
nullable: true
description: ID da assinatura relacionada ao registro.
subscriptionItemId:
type: string
nullable: true
description: ID do item da assinatura que originou a linha.
priceVersionId:
type: string
description: ID da versão de preço aplicada ao item.
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:
type: string
description: >-
Descrição do item (item do plano ou linha da
fatura).
quantity:
type: integer
description: Quantidade do item.
unitAmount:
type: integer
description: Valor unitário do item, em centavos.
amount:
type: integer
description: Valor do preço ou da linha, em centavos.
periodStart:
type: string
format: date-time
nullable: true
description: >-
Início do período coberto pela fatura ou pela linha
(ISO 8601).
periodEnd:
type: string
format: date-time
nullable: true
description: >-
Fim do período coberto pela fatura ou pela linha
(ISO 8601).
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
description: >-
Linhas que compõem o total da fatura. Não há rota separada
para elas.
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).
example:
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'
'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
'404':
description: Fatura não encontrada
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: NOT_FOUND
message: Invoice not found
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````