API — Faturas e Pagamentos (/invoices)
Criar e gerenciar faturas: itens, ESCOLHA de gateway (payment_gateway_id / enabled_gateways), PARCELAMENTO no cartão via Asaas (asaas_installment_count 1–12), descobrir gateways em GET /payment-gateways e registrar pagamentos. Carnê e faturas recorrentes não são suportados via API.
API — Faturas e Pagamentos
Emissão e gestão de faturas. Base: /api/v1/invoices.

⚠️ Sobre parcelamento e recorrência (leia primeiro): A API suporta parcelamento no cartão de crédito via asaas_installment_count (1–12), desde que haja um gateway Asaas habilitado. Já o carnê (parcelar boleto em várias faturas) e a criação de faturas recorrentes NÃO são suportados pela API — existem apenas na interface web. Para carnê via API, crie várias faturas com vencimentos diferentes.
Endpoints
| Método | Path | Descrição |
|---|---|---|
| GET | /payment-gateways | Listar gateways de pagamento (para descobrir os IDs) |
| GET | /invoices | Listar faturas |
| POST | /invoices | Criar fatura (itens, gateways, parcelamento) |
| GET | /invoices/{id} | Detalhes (itens, pagamentos, gateways, URL pública) |
| PUT | /invoices/{id} | Atualizar fatura |
| DELETE | /invoices/{id} | Excluir |
| GET | /invoices/{id}/payments | Listar pagamentos |
| POST | /invoices/{id}/payments | Registrar pagamento manual |
GET /payment-gateways — descobrir os gateways disponíveis
Liste os gateways ativos do tenant para obter seus id (usados em payment_gateway_id e enabled_gateways). O campo gateway identifica o provedor (ex.: asaas — necessário para parcelamento no cartão).
GET /api/v1/payment-gateways
{
"data": [
{ "id": 3, "gateway": "asaas", "name": "Asaas", "methods": ["pix","boleto","credit_card"], "use_in_invoices": true, "is_default": true },
{ "id": 5, "gateway": "inter", "name": "Banco Inter", "methods": ["pix","boleto"], "use_in_invoices": true, "is_default": false }
]
}
GET /invoices — filtros
| Parâmetro | Tipo | Descrição |
|---|---|---|
| search | string | número ou título |
| status | string | draft, pending, sent, viewed, partial, paid, overdue, cancelled |
| contact_id | integer | filtra por contato |
| due_from / due_to | date | faixa de vencimento (YYYY-MM-DD) |
| is_recurring | boolean | filtra recorrentes (apenas leitura) |
| sort_by | string | created_at, due_date, total, number, status |
| sort_dir | string | asc | desc (padrão desc) |
| per_page | integer | padrão 50, máx 100 |
POST /invoices — criar
Obrigatórios: contact_id, due_date e items (mín 1). A fatura nasce como draft e os totais são calculados automaticamente.
| Campo | Tipo | Regras |
|---|---|---|
| contact_id | integer | obrigatório |
| due_date | date | obrigatório |
| items | array | obrigatório, mín 1 (name, quantity, unit_price obrigatórios por item) |
| title / description | string | título / descrição |
| issue_date | date | padrão: hoje |
| currency | string | padrão BRL |
| discount_amount / discount_type | number / string | desconto (fixed | percent) |
| notes / terms | string | observações / termos |
| payment_gateway_id | integer | gateway principal (ID de GET /payment-gateways); se omitido usa o padrão do tenant |
| enabled_gateways | array | IDs dos gateways oferecidos ao cliente, ex: [3, 5] |
| asaas_installment_count | integer | parcelas no cartão (1–12) via Asaas. Padrão 1 (à vista). Requer gateway Asaas habilitado |
| asaas_payment_methods | array | métodos Asaas: pix, boleto, credit_card (o parcelamento aplica-se ao credit_card) |
Parcelamento no cartão de crédito (Asaas)
- Informe
asaas_installment_countentre 1 e 12 (1 = à vista). O parcelamento é processado pelo Asaas no pagamento com cartão de crédito. - É obrigatório ter um gateway
asaasentre os habilitados (payment_gateway_idouenabled_gateways). Caso contrário, a API retorna422. - Inclua
credit_cardemasaas_payment_methodspara que o cliente possa pagar parcelado pelo link da fatura. - O valor de cada parcela (com eventuais juros do parcelamento) é calculado pelo Asaas quando a cobrança no cartão é gerada.
- O limite de parcelas pode ser menor que 12 conforme a configuração do gateway Asaas do tenant.
Exemplo — Requisição (parcelado no cartão via Asaas)
POST /api/v1/invoices
{
"contact_id": 1,
"due_date": "2026-04-30",
"title": "Consultoria de Marketing",
"payment_gateway_id": 3,
"enabled_gateways": [3],
"asaas_installment_count": 3,
"asaas_payment_methods": ["pix", "boleto", "credit_card"],
"items": [
{ "name": "Consultoria", "quantity": 2, "unit_price": 500 },
{ "name": "Relatório", "quantity": 1, "unit_price": 300 }
]
}
Exemplo — Resposta 201 Created
{
"data": {
"id": 15,
"number": "FAT-00015",
"title": "Consultoria de Marketing",
"status": "draft",
"due_date": "2026-04-30",
"subtotal": 1300.00,
"tax_total": 0,
"total": 1300.00,
"amount_due": 1300.00,
"currency": "BRL",
"payment_gateway_id": 3,
"enabled_gateways": [3],
"asaas_installment_count": 3,
"asaas_payment_methods": ["pix", "boleto", "credit_card"],
"contact": { "id": 1, "name": "João Silva", "email": "joao@email.com" },
"gateway_name": "Asaas",
"gateways": [ { "id": 3, "gateway": "asaas", "name": "Asaas" } ],
"public_url": "https://contrate360.com/i/abc123",
"items": [
{ "id": 1, "name": "Consultoria", "quantity": 2, "unit": "un", "unit_price": 500, "total": 1000 },
{ "id": 2, "name": "Relatório", "quantity": 1, "unit": "un", "unit_price": 300, "total": 300 }
],
"payments": []
},
"message": "Invoice created successfully."
}
PUT /invoices/{id}
Atualiza o cabeçalho: contact_id, title, description, issue_date, due_date, status, currency, discount_amount, discount_type, notes, terms, payment_gateway_id, enabled_gateways, asaas_installment_count e asaas_payment_methods (mesmas regras do POST). Não altera os itens.
PUT /api/v1/invoices/15
{ "status": "sent", "enabled_gateways": [3], "asaas_installment_count": 3 }
Pagamentos
GET /invoices/{id}/payments lista os pagamentos. POST /invoices/{id}/payments registra um pagamento manual (campos: amount obrigatório, method [pix|boleto|credit_card|debit_card|transfer|manual], notes, paid_at). A fatura precisa estar em status que aceite baixa, senão 422.
Campos de gateway/parcelamento na resposta
payment_gateway_id,enabled_gateways— em todas as respostas.asaas_installment_count,asaas_payment_methods— em todas as respostas.gateway_name,gateways[](id, gateway, name) — apenas no detalhe (show/store/update).
Limitações da API de faturas
- Parcelamento no cartão: SUPORTADO via
asaas_installment_count+ gateway Asaas (veja acima). - Carnê (parcelar boleto): NÃO suportado via API. Existe apenas na interface web. Para simular, crie várias faturas com vencimentos diferentes (cada parcela = uma fatura).
- Faturas recorrentes: NÃO suportado via API. O campo
is_recurringé apenas leitura/filtro; crie recorrências pela interface web. - O PUT não altera itens. Para mudar itens, use a interface web ou recrie a fatura.