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

# Faturas

> O documento de cobrança que cada ciclo emite — os oito estados por que passa e os dois links que a Z2Pay hospeda para o pagador.

A **fatura** (`inv_`) é o documento de cobrança que uma assinatura emite a cada ciclo. Ela reúne os
itens cobrados, tem um total em centavos e percorre um ciclo de vida próprio, independente do da
[assinatura](/pt-BR/subscriptions) que a gerou.

Pela API, a fatura é **somente leitura**: quem a cria é o motor de cobrança, no ritmo da recorrência.
O que se faz aqui é acompanhar — e distribuir o link de pagamento.

<Info>
  Todas as rotas exigem o header `x-api-key`. Veja [Autenticação](/pt-BR/autenticacao). Valores
  monetários são sempre inteiros em centavos (`18990` = R\$ 189,90).
</Info>

***

## Endpoints

| Método | Rota             | Descrição                                                    |
| ------ | ---------------- | ------------------------------------------------------------ |
| `GET`  | `/invoices`      | [Lista as faturas](/pt-BR/subscriptions/invoices/list)       |
| `GET`  | `/invoices/{id}` | [Busca uma fatura por ID](/pt-BR/subscriptions/invoices/get) |

<Note>
  **Não há rota de escrita.** Criar fatura avulsa, gerar link de pagamento, reagendar e forçar uma
  nova cobrança são ações do painel do lojista, com sessão de usuário — não estão expostas por
  `x-api-key`. Pela API você lê o que o motor produziu.
</Note>

***

## Os oito estados

| Estado      | O que significa                                                                |
| ----------- | ------------------------------------------------------------------------------ |
| `scheduled` | Criada com antecedência; vira pagável quando o `chargeAt` chega                |
| `suspended` | Congelada pela pausa de uma assinatura `upfront` — fora dos ciclos de cobrança |
| `open`      | Aguardando pagamento; a slip de PIX ou boleto já existe, quando é o caso       |
| `paid`      | Paga integralmente                                                             |
| `past_due`  | A cobrança falhou e a régua de inadimplência está tentando de novo             |
| `unpaid`    | Retentativas esgotadas — a cobrança foi abandonada                             |
| `canceled`  | Anulada antes do pagamento                                                     |
| `refunded`  | Reembolsada depois de paga                                                     |

<Warning>
  **Não existe status `voided`.** O webhook chama-se `invoice.voided`, mas o campo `status` da
  fatura anulada é `canceled`. Uma integração que procure `voided` no objeto nunca vai encontrar.
  Ver o [catálogo de eventos](/pt-BR/webhooks/eventos).
</Warning>

<Note>
  **`suspended` só existe em assinatura `upfront` pausada.** Na pausa de uma `just_in_time`, as
  faturas não pagas são **anuladas** em vez de congeladas. A suspensa tem duas saídas: a
  [retomada](/pt-BR/subscriptions/resume) a devolve para `scheduled` com as datas deslocadas, e o
  cancelamento a leva para `canceled`. Enquanto suspensa, ela não é pagável — o link público
  responde `404`.
</Note>

<Note>
  **`paid`, `canceled`, `refunded` e `unpaid` são terminais** e recusam ação de cancelamento.
</Note>

***

## Os dois links que a Z2Pay hospeda

Você não precisa construir tela de pagamento nem de troca de cartão: a Z2Pay hospeda as duas e
entrega o link pronto. O seu papel é distribuí-lo — por e-mail, no seu app, onde fizer sentido.

**Link da fatura** — `/i/{token}`, onde o token é o `publicAccessToken` da fatura. O pagador abre e a
slip de PIX ou boleto é gerada na hora, em vez de expirar dentro de um e-mail antigo. O que ele vê
depende do estado:

| Estado da fatura                   | O que o link faz                                                    |
| ---------------------------------- | ------------------------------------------------------------------- |
| `scheduled`, `suspended`, `unpaid` | responde `404` — a fatura fica oculta, como se o link não existisse |
| `open`, `past_due`                 | página pagável                                                      |
| `paid`, `canceled`, `refunded`     | abre em modo leitura, mostrando o estado final                      |

**Link de troca de forma de pagamento** — o `paymentUpdateToken` da assinatura (prefixo `pmt_`),
exposto no objeto dela. É por aqui que o cliente final atualiza o cartão quando ele vence ou é
recusado, sem falar com você.

<Warning>
  **Os dois tokens são credencial, não identificador.** Quem tem o `itk_` abre aquela fatura; quem
  tem o `pmt_` troca o cartão daquela assinatura — sem login, porque é assim que o cliente final
  consegue pagar. Trate-os como senha: entregue ao titular pelo seu canal, e não os deixe em log de
  aplicação nem em URL de analytics.

  A [listagem](/pt-BR/subscriptions/invoices/list) devolve um `itk_` por fatura, então logar o corpo
  inteiro de uma página espalha vários de uma vez.
</Warning>

<Warning>
  **O link de troca só vale em assinatura já ativada.** Numa `incomplete`, a primeira forma de
  pagamento entra pelo [Checkout](/pt-BR/checkout/links) ou por
  [`POST /subscriptions/{id}/payment-method`](/pt-BR/subscriptions/payment-method) — ver
  [Assinaturas](/pt-BR/subscriptions).
</Warning>

<Note>
  **As rotas que essas páginas chamam por trás não são da API pública.** Elas se autenticam pela
  posse do token, não por `x-api-key`, e existem para o nosso próprio front. Quem for montar a
  própria página de pagamento monta o fluxo pelas rotas autenticadas, não por essas.
</Note>

***

## Veja também

<CardGroup cols={2}>
  <Card title="Assinaturas" icon="repeat" href="/pt-BR/subscriptions">
    O contrato que emite as faturas.
  </Card>

  <Card title="Ciclos" icon="clock" href="/pt-BR/subscriptions/ciclos">
    Quando cada fatura nasce, vence e é cobrada.
  </Card>

  <Card title="Planos e Preços" icon="tag" href="/pt-BR/subscriptions/plans">
    Os valores que compõem os itens da fatura.
  </Card>

  <Card title="Tokenizer" icon="credit-card" href="/pt-BR/tokenizer">
    Tokenize cartões no navegador do cliente.
  </Card>
</CardGroup>