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 que a gerou.
As faturas do ciclo, quem cria é o motor de cobrança, no ritmo da recorrência — pela API você as
acompanha e distribui o link de pagamento. A exceção é a fatura avulsa: uma cobrança fora do
ciclo, com vencimento próprio, que você cria por POST /invoices.
Nem toda fatura vem de uma assinatura. A venda rápida com data de
cobrança gera uma fatura sem contrato
nenhum: ela vem com
kind: "standalone" e subscriptionId nulo. Tudo o mais nesta página
vale para ela — estados, links, atraso e os eventos invoice.*. Quem lê subscriptionId sem
tratar o nulo quebra justamente nessa.Todas as rotas exigem o header
x-api-key. Veja Autenticação. Valores
monetários são sempre inteiros em centavos (18990 = R$ 189,90).Endpoints
Depois de emitida, a fatura não muda pela API. Gerar link de pagamento, reagendar, anular e
forçar uma nova cobrança continuam sendo ações do painel do lojista, com sessão de usuário — não
estão expostas por
x-api-key. A exceção indireta é
POST /subscriptions/{id}/extra-items: ele não altera a
fatura, mas muda o que uma fatura futura ainda scheduled vai cobrar.Os oito estados
O valor só é definitivo a partir de
open. Uma fatura scheduled ainda pode ganhar linhas —
é o caso das cobranças extras, que entram nela até o instante
em que o ciclo fecha. subtotal e total de uma fatura scheduled são a leitura de agora, não
uma promessa do que ela vai cobrar.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 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.paid, canceled, refunded e unpaid são terminais e recusam ação de cancelamento.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:
A fatura
scheduled cobrada pelo link, e não automaticamente, é a exceção. O link mostra a
data em que ela abre e deixa o pagador gerar o PIX ou o boleto antes disso, o que leva a fatura a
open. Se a assinatura tem cancelamento agendado e a fatura cobre um período posterior ao atual,
o pedido é recusado e a página informa que a fatura não será cobrada.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ê.
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.Veja também
Assinaturas
O contrato que emite as faturas.
Ciclos
Quando cada fatura nasce, vence e é cobrada.
Planos e Preços
Os valores que compõem os itens da fatura.
Tokenizer
Tokenize cartões no navegador do cliente.