> ## Documentation Index > Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Faturas > O documento de cobrança de um cliente — gerado pelo ciclo de uma assinatura ou criado de forma avulsa. 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 direta** Cobranç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](/features/payment-intents), mantendo o fluxo de pagamento leve. A fatura existe quando há um documento de cobrança a ser representado e auditado. ## Modelo conceitual ```mermaid theme={} flowchart LR S[Subscription] -- ciclo de cobrança --> I[Invoice] M[Cobrança avulsa] -- manual --> I I -- gera --> PI[Payment Intent] PI -- liquida --> CH[Charge] I --> C[Customer] ``` 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](/api-reference/invoices). O cliente é detalhado em [Clientes](/features/customer-management). ## 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](/api-reference/subscriptions). 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](/features/payment-intents) e a [charge](/features/charges). 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. ```mermaid theme={} stateDiagram-v2 [*] --> open [*] --> paid: fluxo já liquidado open --> paid: pagamento confirmado open --> void: void open --> uncollectible: baixa manual (incobrável) paid --> [*] void --> [*] uncollectible --> [*] ``` | `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 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 [payment links](/features/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. ```text theme={} 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. ```bash Item com preço do catálogo theme={} 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 } ] }' ``` ```bash Item com preço ad-hoc theme={} curl https://api.chargefy.io/v1/invoices \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "customer": "cus_456", "collection_method": "charge_automatically", "line_items": [ { "description": "Consultoria avulsa", "quantity": 1, "price_data": { "currency": "brl", "unit_amount": 25000 } } ] }' ``` `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}/`. Cada uma retorna a **fatura completa atualizada**. `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`. `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. `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](/features/payment-intents) — 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 Schema público completo e campos retornados. A origem recorrente das faturas. Como a fatura vira uma tentativa de pagamento. Quem é cobrado e o snapshot de cobrança.