Faturas - Chargefy

Uma fatura (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.

Modelo conceitual

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.

Objeto	Responsabilidade	Relação
Invoice	Documento de cobrança: valores, itens, status	pertence a um `customer`
Line item	Linha faturada: produto/preço, quantidade, período	um ou mais por fatura
Payment Intent	Tentativa de pagamento da fatura	gerado ao cobrar
Subscription	Origem recorrente da fatura	opcional (`null` em avulsas)

O schema público completo está em Objeto invoice. O cliente é detalhado em Clientes.

De onde vem uma fatura

O campo billing_reason diz qual fluxo originou a fatura:

`billing_reason`	Quando acontece
`subscription_create`	Primeira fatura no momento em que a assinatura é criada.
`subscription_cycle`	Renovação periódica da assinatura a cada novo ciclo.
`subscription_update`	Ajuste de itens/valor de uma assinatura existente.
`manual`	Cobrança avulsa criada via `POST /v1/invoices`, sem ciclo automático.

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 via metadata. 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.

`status`	Significado
`open`	Criada, imutável e aguardando pagamento.
`paid`	Liquidada com sucesso. `paid_at` e `latest_charge` preenchidos.
`uncollectible`	Baixa contábil manual: você marca a fatura como incobrável e ela deixa de ser cobrada. As tentativas automáticas nunca chegam aqui sozinhas — uma fatura cuja cobrança falhou continua `open` e pagável.
`void`	Cancelada. Não pode mais ser paga.

A criação é imutável: depois que a fatura existe, amount_due, vencimento, snapshots do cliente e itens de linha não mudam mais. Para alterar valores ou dados de cobrança, cancele (void) e gere uma nova fatura.

Como a fatura é cobrada

O collection_method define como o pagamento é coletado:

`collection_method`	Comportamento
`charge_automatically`	Tenta cobrar automaticamente o método de pagamento salvo do cliente (cartão).
`send_invoice`	Disponibiliza a fatura para o cliente pagar manualmente pela URL da invoice. Default em faturas avulsas.

Página hospedada da fatura

Toda invoice pode expor hosted_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 linkhosted_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 payment links.

Os valores monetários são sempre inteiros em centavos:

Campo	Significado
`amount_subtotal`	Soma dos itens antes de desconto e imposto.
`amount_discount`	Desconto aplicado.
`amount_tax`	Imposto/taxa calculado.
`amount_total`	`amount_subtotal − amount_discount + amount_tax`.
`amount_due`	Valor devido, fixado na criação.
`amount_paid`	Valor já liquidado.
`amount_remaining`	Saldo ainda em aberto.

Itens de linha

Cada item em line_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:

Forma	Quando usar
`price`	Cobra um preço já cadastrado no catálogo (`price_*`).
`price_data`	Define valor e moeda inline, sem preço prévio no catálogo.

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.

amount_subtotal do item = unit_amount × quantity

Criar uma fatura avulsa

Use POST /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.

curl https://api.chargefy.io/v1/invoices \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_456",
    "collection_method": "send_invoice",
    "line_items": [
      { "price": "price_789", "quantity": 1 }
    ]
  }'

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ções POST /v1/invoices/{id}/<ação>. Cada uma retorna a fatura completa atualizada.

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

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

POST /v1/invoices/{id}/void cancela a fatura (status = void). Funciona em open; faturas paid não podem ser canceladas (409).

DELETE /v1/invoices/{id} expressa “tirar de uso” e, quando aplicável, leva a fatura para void, retornando a fatura completa atualizada — não há remoção física, porque a fatura é um documento financeiro auditável.

Relação com payment intent e charge

Quando uma fatura é cobrada, ela gera um payment intent — a tentativa de pagamento. O campo payment_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 em data.object:

Evento	Quando
`invoice.created`	Fatura criada e pronta para cobrança.
`invoice.paid`	Pagamento confirmado.
`invoice.payment.failed`	Tentativa de cobrança falhou.
`invoice.voided`	Fatura cancelada.

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.

​Modelo conceitual

​De onde vem uma fatura

​Quando usar uma fatura

​Ciclo de vida

​Como a fatura é cobrada

​Página hospedada da fatura

​Itens de linha

​Criar uma fatura avulsa

​Ações da fatura

​Relação com payment intent e charge

​Snapshot do cliente

​Webhooks

​Próximos passos

Objeto invoice

Assinaturas

Payment Intents

Clientes

Modelo conceitual

De onde vem uma fatura

Quando usar uma fatura

Ciclo de vida

Como a fatura é cobrada

Página hospedada da fatura

Itens de linha

Criar uma fatura avulsa

Ações da fatura

Relação com payment intent e charge

Snapshot do cliente

Webhooks

Próximos passos