invoice) é o documento de cobrança de um cliente: ela registra o que está sendo cobrado, quanto é devido e como o pagamento será coletado. Cada fatura nasce de um ciclo de assinatura ou de uma cobrança avulsa já como um snapshot imutável, e segue um ciclo de vida até ser paga, cancelada ou marcada como incobrável.
Fatura vs. compra avulsa diretaCobrança recorrente e cobrança avulsa de um cliente passam por uma fatura. Já uma compra única direta (checkout one-off) não gera fatura — ela transita direto sobre o payment intent, mantendo o fluxo de pagamento leve. A fatura existe quando há um documento de cobrança a ser representado e auditado.
Como a fatura entra na cobrança
Uma fatura é sempre de um cliente e agrega um ou mais itens de linha (
line_items). Quando cobrada, ela gera uma tentativa de pagamento (payment_intent); o latest_charge aponta para a cobrança bem-sucedida.
O schema público completo está em Objeto invoice. O cliente é detalhado em Clientes.
De onde vem uma fatura
O campobilling_reason diz qual fluxo originou a fatura:
As três primeiras são geradas automaticamente pelo ciclo de faturamento da assinatura. A
manual é criada por você quando precisa cobrar algo pontual de um cliente.
Quando usar uma fatura
Use uma invoice quando você precisa representar uma cobrança de um cliente ao longo do tempo: ciclo de assinatura, cobrança manual vinculada a um customer, retry de pagamento ou histórico financeiro que precisa apontar para itens, período e saldo em aberto. No Brasil, a invoice da Chargefy não substitui nota fiscal e não é tratada como documento fiscal oficial. Ela é um documento operacional de cobrança e conciliação dentro da Chargefy. Se você precisa emitir NF-e ou NFS-e, use o sistema fiscal apropriado e relacione o identificador fiscal pela sua própria integração ou viametadata.
Para compra única direta de checkout, normalmente você não precisa de invoice: acompanhe o payment intent e a charge. A invoice entra quando existe uma fatura do customer a acompanhar, não para todo pagamento avulso.
Ciclo de vida
Toda fatura nasce como aberta (open) ou, em fluxos já liquidados, como paga (paid). Não existe rascunho público: o ponto de não-retorno é a criação da fatura. A partir dela, valores, itens de linha, vencimento e snapshots do cliente não mudam.
Como a fatura é cobrada
Ocollection_method define como o pagamento é coletado:
Página hospedada da fatura
Toda invoice pode exporhosted_invoice_url, uma URL pública ativa no formato
https://billing.chargefy.io/invoice/:token. Compartilhe esse campo com o
cliente quando quiser que ele visualize ou pague a fatura. O token é opaco e
pode ser renovado pela Chargefy quando expira.
Enquanto a invoice está open, a página hospedada aceita pagamento pelos
métodos em payment_method_types, como Pix, boleto e cartão. Quando a invoice
entra em paid, void ou uncollectible, uma URL ativa continua apontando
para a fatura, mas a página mostra o estado final e não abre uma nova tentativa
de pagamento.
Invoice URL vs. payment link
hosted_invoice_url pertence a uma única invoice e acompanha o ciclo financeiro
dela. Um payment_link é um link reutilizável de venda: cada clique materializa
uma checkout session nova. Para cobrar uma invoice, compartilhe
hosted_invoice_url; para vender uma oferta reutilizável, use
links de pagamento.Itens de linha
Cada item emline_items[] representa uma linha faturada. Ele referencia um preço do catálogo ou carrega um preço ad-hoc, nunca os dois ao mesmo tempo:
Cada item também guarda
quantity, period_start/period_end (o período que aquela linha cobre) e os mesmos campos de valor da fatura, no nível do item.
Criar uma fatura avulsa
UsePOST /v1/invoices para cobranças pontuais. A fatura nasce em open, com valores e itens já fixados. Se precisar corrigir algo depois, cancele a fatura e crie outra.
line_items é obrigatório e não pode ser vazio. Cada item precisa de
exatamente um entre price e price_data — enviar os dois (ou nenhum)
retorna 400. Todos os itens devem usar a mesma moeda da fatura.Ações da fatura
Depois de criada, a fatura avança por açõesPOST /v1/invoices/{id}/<ação>. Cada uma retorna a fatura completa atualizada.
send — enviar por e-mail
send — enviar por e-mail
POST /v1/invoices/{id}/send envia a fatura por e-mail ao cliente. Exige
que o cliente tenha e-mail (422 caso contrário) e não funciona em faturas
void ou uncollectible.pay — disparar uma cobrança
pay — disparar uma cobrança
POST /v1/invoices/{id}/pay agenda uma nova tentativa de pagamento de uma
fatura open com saldo em aberto. Aceita payment_method para escolher o
método; sem ele, usa o método associado à fatura.void — cancelar
void — cancelar
POST /v1/invoices/{id}/void cancela a fatura (status = void). Funciona
em open; faturas paid não podem ser canceladas (409).Relação com payment intent e charge
Quando uma fatura é cobrada, ela gera um payment intent — a tentativa de pagamento. O campopayment_intent aponta para a tentativa mais recente; latest_charge aponta para o charge da liquidação bem-sucedida; payment_method registra o método usado.
Uma fatura pode acumular várias tentativas (uma falha, outra é disparada
via
pay). payment_intent reflete sempre a tentativa mais recente, e
amount_remaining indica se ainda há saldo a cobrar.Snapshot do cliente
No momento em que a fatura é gerada, ela captura um snapshot dos dados do cliente (customer_name, customer_email, customer_document, customer_billing_address, etc.). Esse retrato fica imutável na fatura mesmo que o cadastro do cliente mude depois — o documento de cobrança continua refletindo quem era o cliente naquele momento.
Webhooks
Mudanças na fatura disparam eventos com o objeto completo emdata.object:
Próximos passos
Objeto invoice
Schema público completo e campos retornados.
Assinaturas
A origem recorrente das faturas.
Payment Intents
Como a fatura vira uma tentativa de pagamento.
Clientes
Quem é cobrado e o snapshot de cobrança.