Pagamentos — Endpoints

Base URL: /api/payments

Permissões: Admin, Financial

---

GET /api/payments

Lista pagamentos da empresa.

Query params:

Parâmetro	Tipo	Descrição
page	integer	Página (padrão: 1)
pageSize	integer	Itens por página
search	string	Busca por contrato ou cliente
status	string	Pending, Paid, Defaulted, Cancelled
type	string	Rent, Condo, IPTU, Fine, Expense
period	string	Competência no formato YYYY-MM
contractId	guid	Filtrar por contrato

Resposta 200:

{
  "data": [
    {
      "id": "e1f2a3b4-...",
      "type": "Rent",
      "period": "2026-06",
      "value": 2800.00,
      "dueDate": "2026-06-05",
      "status": "Pending",
      "method": null,
      "paidAt": null,
      "paidValue": null,
      "contractId": "d1e2f3a4-...",
      "contract": {
        "id": "d1e2f3a4-...",
        "client": {
          "name": "João da Silva"
        },
        "property": {
          "code": "AP-001"
        }
      },
      "createdAt": "2026-05-20T10:00:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 56,
  "totalPages": 3,
  "hasNext": true,
  "hasPrevious": false
}

---

GET /api/payments/:id

Retorna detalhes de um pagamento.

Resposta 200:

{
  "id": "e1f2a3b4-...",
  "type": "Rent",
  "period": "2026-06",
  "value": 2800.00,
  "dueDate": "2026-06-05",
  "status": "Paid",
  "method": "Pix",
  "paidAt": "2026-06-03T14:22:00Z",
  "paidValue": 2800.00,
  "receiptUrl": "https://storage.googleapis.com/.../comprovante.pdf",
  "notes": "Pago adiantado.",
  "contractId": "d1e2f3a4-...",
  "boletoUrl": null,
  "createdAt": "2026-05-20T10:00:00Z"
}

---

POST /api/payments

Lança um novo pagamento.

Body:

{
  "contractId": "d1e2f3a4-...",
  "type": "Rent",
  "period": "2026-07",
  "value": 2800.00,
  "dueDate": "2026-07-05",
  "notes": "Competência julho/2026"
}

Campo	Tipo	Obrigatório
contractId	guid	Sim
type	string	Sim
period	string	Sim (formato YYYY-MM)
value	decimal	Sim
dueDate	date	Sim

Resposta 201: Pagamento criado com status Pending.

---

PUT /api/payments/:id

Atualiza dados de um pagamento.

---

PATCH /api/payments/:id/pay

Marca um pagamento como pago.

Body:

{
  "method": "Pix",
  "paidAt": "2026-06-03T14:22:00Z",
  "paidValue": 2800.00,
  "receiptUrl": "https://storage.googleapis.com/.../comprovante.pdf",
  "notes": "Confirmado via extrato."
}

Campo	Tipo	Obrigatório
method	string	Sim: Pix, Boleto, Transfer, Cash
paidAt	datetime	Sim
paidValue	decimal	Sim

Resposta 200: Pagamento com status Paid.

Erros:

• 422 — Pagamento já está pago ou cancelado

---

DELETE /api/payments/:id

Remove pagamento (soft delete).

Permissões: Admin

Erros:

• 400 — Pagamento já está pago (não pode ser deletado)

---

Relatórios de pagamento

GET /api/payments/report/defaulted

Retorna relatório de inadimplência.

Query params: period, contractId

Resposta 200:

{
  "totalDefaulted": 5,
  "totalValue": 14000.00,
  "payments": [...]
}

GET /api/payments/report/revenue

Retorna relatório de receita.

Query params: periodFrom, periodTo

Resposta 200:

{
  "totalRevenue": 84000.00,
  "byMonth": [
    { "period": "2026-04", "value": 27000.00 },
    { "period": "2026-05", "value": 28500.00 },
    { "period": "2026-06", "value": 28500.00 }
  ]
}