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.

Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.
Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.

⚠️ 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étodoPathDescrição
GET/payment-gatewaysListar gateways de pagamento (para descobrir os IDs)
GET/invoicesListar faturas
POST/invoicesCriar 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}/paymentsListar pagamentos
POST/invoices/{id}/paymentsRegistrar 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âmetroTipoDescrição
searchstringnúmero ou título
statusstringdraft, pending, sent, viewed, partial, paid, overdue, cancelled
contact_idintegerfiltra por contato
due_from / due_todatefaixa de vencimento (YYYY-MM-DD)
is_recurringbooleanfiltra recorrentes (apenas leitura)
sort_bystringcreated_at, due_date, total, number, status
sort_dirstringasc | desc (padrão desc)
per_pageintegerpadrã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.

CampoTipoRegras
contact_idintegerobrigatório
due_datedateobrigatório
itemsarrayobrigatório, mín 1 (name, quantity, unit_price obrigatórios por item)
title / descriptionstringtítulo / descrição
issue_datedatepadrão: hoje
currencystringpadrão BRL
discount_amount / discount_typenumber / stringdesconto (fixed | percent)
notes / termsstringobservações / termos
payment_gateway_idintegergateway principal (ID de GET /payment-gateways); se omitido usa o padrão do tenant
enabled_gatewaysarrayIDs dos gateways oferecidos ao cliente, ex: [3, 5]
asaas_installment_countintegerparcelas no cartão (1–12) via Asaas. Padrão 1 (à vista). Requer gateway Asaas habilitado
asaas_payment_methodsarraymétodos Asaas: pix, boleto, credit_card (o parcelamento aplica-se ao credit_card)

Parcelamento no cartão de crédito (Asaas)

  • Informe asaas_installment_count entre 1 e 12 (1 = à vista). O parcelamento é processado pelo Asaas no pagamento com cartão de crédito.
  • É obrigatório ter um gateway asaas entre os habilitados (payment_gateway_id ou enabled_gateways). Caso contrário, a API retorna 422.
  • Inclua credit_card em asaas_payment_methods para 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.
api faturas invoices pagamentos gateway asaas parcelamento cartão integração

Este artigo foi útil?

Artigos Relacionados