Faturas Recorrentes

Gerencie faturas recorrentes (contas fixas mensais). Crie faturas com recorrencia automatica, gere pagamentos mensais e controle anexos de comprovantes.

GET/api/bills

Lista faturas recorrentes com filtros.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`page`(query)	`integer`	Nao	Pagina(default: `1`)
`limit`(query)	`integer`	Nao	Itens por pagina(default: `20`)
`category`(query)	`string`	Nao	Categoria
`type`(query)	`string`	Nao	payable ou receivable
`isActive`(query)	`boolean`	Nao	Filtrar ativas/inativas

bash

curl -s "https://flow.seudominio.com/api/bills?type=payable&isActive=true" \
  -H "Authorization: Bearer $TOKEN" | jq .

200Lista de faturas recorrentes

json

{
  "success": true,
  "data": {
    "bills": [
      {
        "id": "clx...",
        "name": "Servidor Cloud AWS",
        "category": "infraestrutura",
        "type": "payable",
        "recurrence": "monthly",
        "estimatedAmount": 450.00,
        "dueDay": 10,
        "isActive": true
      }
    ],
    "total": 12,
    "page": 1,
    "limit": 20
  }
}

POST/api/bills

Cria uma nova fatura recorrente.

Body

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Sim	Nome da fatura
`category`	`string`	Sim	Categoria
`type`	`string`	Sim	payable ou receivable
`recurrence`	`string`	Sim	monthly, quarterly, yearly
`estimatedAmount`	`number`	Sim	Valor estimado
`dueDay`	`integer`	Sim	Dia de vencimento (1-31)

curl -X POST "https://flow.seudominio.com/api/bills" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Servidor Cloud AWS",
    "category": "infraestrutura",
    "type": "payable",
    "recurrence": "monthly",
    "estimatedAmount": 450.00,
    "dueDay": 10
  }'

GET/api/bills/{id}

Retorna detalhes de uma fatura com historico de pagamentos.

bash

curl -s "https://flow.seudominio.com/api/bills/clx123" \
  -H "Authorization: Bearer $TOKEN" | jq .

PUT/api/bills/{id}

Atualiza uma fatura recorrente.

bash

curl -X PUT "https://flow.seudominio.com/api/bills/clx123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "estimatedAmount": 500.00, "dueDay": 15 }'

DELETE/api/bills/{id}

Remove uma fatura recorrente.

bash

curl -X DELETE "https://flow.seudominio.com/api/bills/clx123" \
  -H "Authorization: Bearer $TOKEN"

GET/api/bills/summary

Resumo das faturas recorrentes para dashboard.

200Resumo de faturas

json

{
  "success": true,
  "data": {
    "totalBills": 12,
    "activeBills": 10,
    "totalMonthlyPayable": 8500.00,
    "totalMonthlyReceivable": 15000.00,
    "pendingPayments": 3,
    "overduePayments": 1
  }
}

Gerar Pagamento

POST/api/bills/{id}/generate

Gera um pagamento para um mes especifico de uma fatura recorrente.

Body

Nome	Tipo	Obrigatorio	Descricao
`referenceDate`	`string`	Sim	Mes de referencia (YYYY-MM)

bash

curl -X POST "https://flow.seudominio.com/api/bills/clx123/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "referenceDate": "2026-03" }'

201Pagamento gerado

json

{
  "success": true,
  "data": {
    "id": "clx...",
    "billId": "clx123",
    "amount": 450.00,
    "dueDate": "2026-03-10",
    "status": "pending",
    "referenceDate": "2026-03"
  }
}

Pagamentos

GET/api/bills/payments/list

Lista todos os pagamentos gerados.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`page`(query)	`integer`	Nao	Pagina(default: `1`)
`limit`(query)	`integer`	Nao	Itens por pagina(default: `20`)
`status`(query)	`string`	Nao	pending, paid, overdue ou cancelled
`billId`(query)	`string`	Nao	Filtrar por fatura
`startDate`(query)	`string`	Nao	Data inicio
`endDate`(query)	`string`	Nao	Data fim

GET/api/bills/payments/{id}

Retorna detalhes de um pagamento.

PUT/api/bills/payments/{id}

Atualiza dados de um pagamento.

Body

Nome	Tipo	Obrigatorio	Descricao
`amount`	`number`	Nao	Valor do pagamento
`dueDate`	`string`	Nao	Data de vencimento
`notes`	`string`	Nao	Observacoes

POST/api/bills/payments/{id}/pay

Marca um pagamento como pago.

Body

Nome	Tipo	Obrigatorio	Descricao
`paidAmount`	`number`	Nao	Valor efetivamente pago
`paidAt`	`string`	Nao	Data do pagamento (YYYY-MM-DD)
`notes`	`string`	Nao	Observacoes

bash

curl -X POST "https://flow.seudominio.com/api/bills/payments/clx456/pay" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "paidAmount": 450.00, "paidAt": "2026-02-10" }'

POST/api/bills/payments/{id}/cancel

Cancela um pagamento pendente.

Anexos

POST/api/bills/payments/{id}/attachments

Adiciona um comprovante/anexo a um pagamento.

bash

curl -X POST "https://flow.seudominio.com/api/bills/payments/clx456/attachments" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/comprovante.pdf"

DELETE/api/bills/attachments/{id}

Remove um anexo.