> 📘 O que você vai aprender com este artigo? > > * Como criar uma fatura na iugu, tanto via interface do Alia quanto via API > * Diferenças entre faturas e cobranças diretas > * Parâmetros obrigatórios e personalizáveis ao criar uma fatura > * Exemplo prático de como realizar uma requisição para criar uma fatura via API As Faturas (ou invoices) são como *pedidos* e os detalhes desses pedidos. Diferente da Charge, elas não são cobradas imediatamente. O pagador precisa acessá-la e, só então, pagá-la. Além disso, as invoices têm um nível de personalização de suas variáveis muito maior que a [Cobrança Direta](https://dev.iugu.com/reference/cobranca-direta), por exemplo. Entenda a [Diferença entre Cobrança Direta e Fatura](https://dev.iugu.com/docs/diferen%C3%A7a-entre-cobran%C3%A7a-direta-e-fatura). *** ### Está procurando pela referência da API? Clique [aqui](https://dev.iugu.com/reference/introdu%C3%A7%C3%A3o-a-api) para conferir na íntegra todas as nossas APIs. # Criar Para criar uma fatura na iugu, há duas formas: ## 1. Via Alia 1. Acesse [alia.iugu.com](https://alia.iugu.com) > clique em Recebimento 2. Faturas > Nova > escolha o cliente (ou crie um novo) > **Criar Fatura** 1. Na tela Nova Fatura, preencha:

Campo	Descrição
Data de Vencimento	Data em que a fatura vencerá.
Descrição	1. Nome do item ou descrição do serviço. 2. Quantidade do item. 3. Preço do item
Desconto, juros e multa	Escolha se a fatura terá desconto, multa e/ou juros e porcentagem para cada um.
Métodos de Pagamento	Escolha quais métodos serão aceitos para pagá-la. 1. Pix 2. Cartão de Crédito 3. Boleto Bancário

3. Clique em **Salvar**. ## 2. Via API Para criar uma invoice utilizando nossa API, siga estes passos: > 📘 Observação > > Como dito, as invoices têm inúmeras configurações personalizáveis, então, para fins didáticos, simplificamos o exemplo a seguir. 1. Utilize o endpoint [Criar Fatura](https://dev.iugu.com/reference/criar-fatura) — `POST` `/v1/invoices` 2. Preencha os seguintes parâmetros (os com `*` são **obrigatórios**): | Parâmetro | Descrição | | :----------------------------- | :------------------------------------------------------------------------------------- | | `email` | Endereço de e-mail que a fatura será enviada. | | `due_date` | Data de vencimento. | | `payable_with` | `bank_slip`, `credit_card` , `bank_slip` ou `all` (que contempla todos os anteriores). | | `payable_with` com `bank_slip` | Preencha também, pelo menos, os parâmetros `cpf_cnpj` e `name `do objeto `payer`. | | `items` | E seus parâmetros `description`, `quantity` e `price_cents`. |
3. Faça a requisição. ### Requisição exemplo ```shell Requisição curl --request POST \ --url https://api.iugu.com/v1/invoices \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data ' { "items": [ { "description": "Descrição do Item", "quantity": 1, "price_cents": 3000 } ], "payer": { "cpf_cnpj": "113.436.750-30", "name": "Nome do Pagador" }, "email": "email@iugu.com", "due_date": "2024-09-16", "payable_with": [ "all" ] } ' ``` ```json Retorno { "id": "C34C8435CE0A4F79BFE5020C9A7BE2F3", "due_date": "2024-09-16", "currency": "BRL", "discount_cents": null, "email": "email@iugu.com", "items_total_cents": 3000, "notification_url": null, "return_url": null, "status": "pending", "tax_cents": null, "total_cents": 3000, "total_paid_cents": 0, "taxes_paid_cents": null, "paid_at": null, "paid_cents": null, "cc_emails": null, "financial_return_date": null, "payable_with": "all", "overpaid_cents": null, "ignore_due_email": null, "ignore_canceled_email": null, "advance_fee_cents": null, "commission_cents": null, "early_payment_discount": false, "order_id": null, "updated_at": "2024-09-16T10:53:17-03:00", "credit_card_brand": null, "credit_card_bin": null, "credit_card_last_4": null, "credit_card_captured_at": null, "credit_card_tid": null, "external_reference": null, "max_installments_value": null, "payer_name": "Nome do Pagador", "payer_email": null, "payer_cpf_cnpj": "11343675030", "payer_phone": null, "payer_phone_prefix": null, "payer_address_zip_code": null, "payer_address_street": null, "payer_address_district": null, "payer_address_city": null, "payer_address_state": null, "payer_address_number": null, "payer_address_complement": null, "payer_address_country": null, "late_payment_fine": 0, "late_payment_fine_cents": null, "split_id": null, "external_payment_id": null, "external_payment_description": null, "payment_booklet_id": null, "subscription_id": null, "variables": [ { "variable": "barcode_v1", "value": "40196984100000030002024260000000000000072933" }, { "variable": "barcode_version", "value": "1" }, { "variable": "payer.cpf_cnpj", "value": "11343675030" }, { "variable": "payer.name", "value": "Nome do Pagador" }, { "variable": "payment_data.transaction_number", "value": "726644242606514" } ], "custom_variables": [], "logs": [ { "id": "10654E834A23449F8EE0BFCD036E8917", "description": "Email de Fatura enviado!", "notes": "Fatura enviada com sucesso para: email@iugu.com", "created_at": "16/09, 10:53" }, { "id": "8DDEA4B2090A4154B3F75623208956DA", "description": "Fatura criada com sucesso!", "notes": "Fatura criada!", "created_at": "16/09, 10:53" } ], "credit_card_transaction": null, "account_id": "44C5DC6376804D1FA792CBCA382105C1", "bank_account_branch": "0001", "bank_account_number": "2739435-0", "account_name": "Nome da Conta", "secure_id": "c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153", "secure_url": "https://faturas.iugu.com/c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153", "customer_id": null, "customer_ref": null, "customer_name": null, "user_id": null, "total": "R$ 30,00", "taxes_paid": "R$ 0,00", "total_paid": "R$ 0,00", "total_overpaid": "R$ 0,00", "total_refunded": "R$ 0,00", "commission": "R$ 0,00", "fines_on_occurrence_day": "R$ 0,00", "total_on_occurrence_day": "R$ 0,00", "fines_on_occurrence_day_cents": 0, "total_on_occurrence_day_cents": 0, "refunded_cents": 0, "remaining_captured_cents": 0, "advance_fee": null, "estimated_advance_fee": null, "paid": "R$ 0,00", "original_payment_id": null, "double_payment_id": null, "per_day_interest": false, "per_day_interest_value": null, "per_day_interest_cents": 0, "interest": null, "discount": null, "duplicated_invoice_id": null, "bank_slip_extra_due": 10, "created_at": "16/09, 10:53", "created_at_iso": "2024-09-16T10:53:17-03:00", "authorized_at": null, "authorized_at_iso": null, "expired_at": null, "expired_at_iso": null, "refunded_at": null, "refunded_at_iso": null, "canceled_at": null, "canceled_at_iso": null, "protested_at": null, "protested_at_iso": null, "chargeback_at": null, "chargeback_at_iso": null, "occurrence_date": null, "refundable": null, "installments": null, "transaction_number": 726644242606514, "payment_method": null, "financial_return_dates": null, "bank_slip": { "digitable_line": "40192024256000000000400000729335698410000003000", "barcode_data": "40196984100000030002024260000000000000072933", "barcode": "https://api.iugu.com/v1/public/invoice/c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153/barcode", "bank_slip_url": "https://boletos.iugu.com/v1/public/invoice/c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153/bank_slip", "bank_slip_pdf_url": "https://boletos.iugu.com/v1/public/invoice/c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153/bank_slip.pdf", "bank_slip_bank": 401, "bank_slip_status": "pending", "bank_slip_error_code": null, "bank_slip_error_message": null, "recipient_cpf_cnpj": "113.436.750-30" }, "pix": { "qrcode": "https://faturas.iugu.com/qr_code/c34c8435-ce0a-4f79-bfe5-020c9a7be2f3-5153", "qrcode_text": "00020101021226840014br.gov.bcb.pix2562qr.iugu.com/public/payload/v2/C34C8435CE0A4F79BFE5020C9A7BE2F3520400005303986540530.005802BR5924KARTHEN JUNIOR RODRIGUES6009SAO PAULO62070503***630479A8", "status": "qr_code_created", "payer_cpf_cnpj": null, "payer_name": null, "end_to_end_id": null, "end_to_end_refund_id": null, "account_number_last_digits": null }, "items": [ { "id": "1F9F8BD291444FEDABE30FB750DCEFD7", "description": "Descrição do Item", "price_cents": 3000, "quantity": 1, "created_at": "2024-09-16T10:53:17-03:00", "updated_at": "2024-09-16T10:53:17-03:00", "price": "R$ 30,00" } ], "early_payment_discounts": [], "split_rules": null } ``` ### Onde acessá-la? A fatura é enviada para o e-mail do cliente, então, o pagador deve acessá-lo e clicar no botão "Pagar a Fatura". ## Importante :warning: — Tarifas do Checkout iugu Quando o pagador acessa o link checkout.iugu.com, **é cobrado uma tarifa**. Se deseja evitá-la, é necessário criar o seu próprio checkout. Saiba mais sobre [Checkout Transparente e Checkout iugu](https://dev.iugu.com/docs/checkout). Consulte também nossas tarifas em [iugu.com/planos](https://www.iugu.com/planos/). *** # Consultar Há duas formas de consultar as Faturas na iugu: ## 1. Via Alia 1. Com o ID da Fatura > clique em Recebimento 2. No campo de pesquisa > insira o ID e aperte Enter

Campo de pesquisa de faturas (elastic search) do Alia 3. Ao lado direito, clique em Ver para visualizar os detalhes da fatura e, inclusive, ter acesso ao link que redireciona para o checkout (`secure_url`). ## 2. Via API Existem 2 endpoints que retornam detalhes de faturas:

Nome	Endpoint	Descrição
[Consultar Fatura](https://dev.iugu.com/reference/buscar-fatura)	`GET` `/v1/invoices/{id}`	Retorna detalhes de uma fatura específica.
[Listar/Buscar Faturas](https://dev.iugu.com/reference/listar-faturas)	`GET` `/v1/invoices`	Listagem de 100 invoices por página. Com possibilidade de filtros de "criado em" à "status da fatura". Saiba mais sobre [paginação](https://dev.iugu.com/reference/pagina%C3%A7%C3%A3o). Conheça os [nossos Gatilhos](https://dev.iugu.com/docs/gatilhos) ao invés de realizar pooling.

## [Consultar Fatura](https://dev.iugu.com/reference/buscar-fatura) — `/v1/invoices/{id}` ### Response exemplo ```json Response { "id": "16F7AA3D2E0B41E9987B1DC95B957456", "due_date": "2024-07-16", "currency": "BRL", "discount_cents": null, "email": "email@iugu.com", "items_total_cents": 3000, "notification_url": null, "return_url": null, "status": "pending", "tax_cents": null, "total_cents": 3000, "total_paid_cents": 0, "taxes_paid_cents": null, "paid_at": null, "paid_cents": null, "cc_emails": null, "financial_return_date": null, "payable_with": "all", "overpaid_cents": null, "ignore_due_email": null, "ignore_canceled_email": null, "advance_fee_cents": null, "commission_cents": null, "early_payment_discount": false, "order_id": null, "updated_at": "2024-07-16T16:35:49-03:00", "credit_card_brand": null, "credit_card_bin": null, "credit_card_last_4": null, "credit_card_captured_at": null, "credit_card_tid": null, "external_reference": null, "max_installments_value": null, "payer_name": "Nome", "payer_email": null, "payer_cpf_cnpj": "11343675030", "payer_phone": null, "payer_phone_prefix": null, "payer_address_zip_code": null, "payer_address_street": null, "payer_address_district": null, "payer_address_city": null, "payer_address_state": null, "payer_address_number": null, "payer_address_complement": null, "payer_address_country": null, "late_payment_fine": 1, "late_payment_fine_cents": null, "split_id": null, "external_payment_id": null, "external_payment_description": null, "payment_booklet_id": null, "subscription_id": null, "variables": [ { "variable": "barcode_v1", "value": "40195977900000030002024198000000000000165649" }, { "variable": "barcode_version", "value": "1" }, { "variable": "payer.cpf_cnpj", "value": "11343675030" }, { "variable": "payer.name", "value": "Nome" }, { "variable": "payment_data.transaction_number", "value": "375641241984723" } ], "custom_variables": [], "logs": [ { "id": "0C7750D2CFEE44F187910416FE7E1661", "description": "Email de Fatura enviado!", "notes": "Fatura enviada com sucesso para: email@iugu.com", "created_at": "16/07, 16:34" }, { "id": "F2A2A91E829245BFA72D1DE6244D2374", "description": "Fatura criada com sucesso!", "notes": "Fatura criada!", "created_at": "16/07, 16:34" } ], "credit_card_transaction": null, "account_id": "27016E1AD888499A98994E781B6C3762", "bank_account_branch": "0001", "bank_account_number": "3693443-0", "account_name": "Nome da Conta", "secure_id": "16f7aa3d-2e0b-41e9-987b-1dc95b957456-d7a2", "secure_url": "https://checkout.iugu.com/invoices/16f7aa3d-2e0b-41e9-987b-1dc95b957456-d7a2", "customer_id": null, "customer_ref": null, "customer_name": null, "user_id": null, "total": "R$ 30,00", "taxes_paid": "R$ 0,00", "total_paid": "R$ 0,00", "total_overpaid": "R$ 0,00", "total_refunded": "R$ 0,00", "commission": "R$ 0,00", "fines_on_occurrence_day": "R$ 0,00", "total_on_occurrence_day": "R$ 0,00", "fines_on_occurrence_day_cents": 0, "total_on_occurrence_day_cents": 0, "refunded_cents": 0, "remaining_captured_cents": 0, "advance_fee": null, "estimated_advance_fee": null, "paid": "R$ 0,00", "original_payment_id": null, "double_payment_id": null, "per_day_interest": false, "per_day_interest_value": null, "per_day_interest_cents": 0, "interest": null, "discount": null, "duplicated_invoice_id": null, "bank_slip_extra_due": 2, "created_at": "16/07, 16:34", "created_at_iso": "2024-07-16T16:34:53-03:00", "authorized_at": null, "authorized_at_iso": null, "expired_at": null, "expired_at_iso": null, "refunded_at": null, "refunded_at_iso": null, "canceled_at": null, "canceled_at_iso": null, "protested_at": null, "protested_at_iso": null, "chargeback_at": null, "chargeback_at_iso": null, "occurrence_date": null, "refundable": null, "installments": null, "transaction_number": 375641241984723, "payment_method": null, "financial_return_dates": null, "bank_slip": { "digitable_line": "40192024179800000000400001656495597790000003000", "barcode_data": "40195977900000030002024198000000000000165649", "barcode": "https://api.iugu.com/v1/public/invoice/16f7aa3d-2e0b-41e9-987b-1dc95b957456-d7a2/barcode", "bank_slip_url": "https://boletos.iugu.com/v1/public/invoice/16f7aa3d-2e0b-41e9-987b-1dc95b957456-d7a2/bank_slip", "bank_slip_bank": 401, "bank_slip_status": "registered", "bank_slip_error_code": null, "bank_slip_error_message": null, "recipient_cpf_cnpj": "113.436.750-30" }, "pix": { "qrcode": "https://faturas.iugu.com/qr_code/16f7aa3d-2e0b-41e9-987b-1dc95b957456-d7a2", "qrcode_text": "00020101021226840014br.gov.bcb.pix2562qr.iugu.com/public/payload/v2/16F7AA3D2E0B41E9987B1DC95B957456520400005303986540530.005802BR5925IUGU INSTITUICAO DE PAGAM6009SAO PAULO62070503***630446D8", "status": "qr_code_created", "payer_cpf_cnpj": null, "payer_name": null, "end_to_end_id": null, "end_to_end_refund_id": null, "account_number_last_digits": null }, "items": [ { "id": "0F30A8B1ED244325BBC6C8A1AE34AE18", "description": "Item", "price_cents": 3000, "quantity": 1, "created_at": "2024-07-16T16:34:53-03:00", "updated_at": "2024-07-16T16:34:53-03:00", "price": "R$ 30,00" } ], "early_payment_discounts": [], "split_rules": null } ``` ## [Listar/Buscar Fatura](https://dev.iugu.com/reference/listar-faturas) — `/v1/invoices` ### Response exemplo ```json Response { "items": [ { /Detalhes de uma Fatura (assim como o exemplo acima) } ], "facets": { "late": { "_type": "filter", "count": 60 }, "status": { "_type": "terms", "missing": 0, "other": 163, "terms": [ { "term": "pending", "count": 125 } ], "total": 125 } }, "totalItems": 288 } ``` *** # Prazo de Expiração e Data de Vencimento Data de Expiração e Data de Vencimento de uma Fatura podem ser confusas se não compreendermos a finalidade de cada um. Então, vamos por partes. ## Data de Vencimento (`due_date`) A data de vencimento é utilizada, em sua grande maioria, quando o modelo de negócio incide multas quando a data é ultrapassada e ainda não foi paga. > 👍 Dica (API)💡 > > Utilize o parâmetro `expired_url` para **redirecionar** o pagador para o endereço web que desejar, seja com instruções de como reemitir a fatura ou o que sua criatividade quiser 😉. ## Data de Expiração (`expires_in`) Já a data de expiração é a data limite para pagar a invoice, mesmo que ela tenha ultrapassado a data de vencimento (`due_date`). Quando a fatura assume o status `expired`, não é possível pagá-la, obrigando sua reemissão. ## Como combiná-los (sugestão)? **Cenário** > "Gostaria que a fatura tivesse o vencimento no dia 26/09, mas permanecesse disponível por mais 4 dias, permitindo que o cliente a pague mesmo após o vencimento. Se o pagamento ocorrer entre os dias 27 e 30, deve ser aplicada uma multa de 2% sobre o valor total da fatura." Para este cenário, durante a criação de uma Fatura, defina a Data de Vencimento **menor** que a Data de Expiração. Então, na prática (API): ```shell { "due_date": "2024-09-26", "expires_in": "2024-09-30", "fines": true, "late_payment_fine": 2 } ```