# 📘 Documentação da API: Módulo Financeiro e Pagamentos

Este módulo controla datas de recebimento, lançamento de aluguéis mensais (avulso ou recorrente), envio de comprovantes PIX/transferência pelo inquilino e confirmação de baixa em tempo real pelo gestor.

---

## 1. Lançar Cobrança / Gerar Parcelas (`criar.php`)
Permite ao gestor lançar uma mensalidade avulsa ou gerar até 36 parcelas mensais de um contrato de uma só vez.

- **URL:** `POST /aluguel/api/pagamentos/criar.php`
- **Autenticação:** Requer perfil `gestor`
- **Headers:** `Authorization: Bearer <token>`, `Content-Type: application/json`

### Body (JSON)
```json
{
  "vinculo_id": 1,
  "valor": 2500.00,
  "data_vencimento": "2026-12-05",
  "descricao": "Aluguel Mensal",
  "quantidade_meses": 12,
  "observacoes": "Chave PIX: gestor@teste.com"
}
```
> Se `valor` for omitido, a API usa automaticamente o `valor_aluguel` cadastrado no imóvel.

---

## 2. Listar Movimentação, Prazos e Resumo Financeiro (`listar.php`)
Retorna todas as parcelas do usuário autenticado (`gestor` vê seus recebíveis; `inquilino` vê seus prazos e histórico) acompanhadas do resumo financeiro calculado em tempo real (`total_pago`, `total_a_receber`, `total_em_atraso`, `proximo_vencimento`).

- **URL:** `GET /aluguel/api/pagamentos/listar.php`
- **Filtros opcionais (Query String):**
  - `status`: `pendente`, `aguardando_confirmacao`, `pago`, `atrasado`, `cancelado`
  - `imovel_id`: ID do imóvel
  - `vinculo_id`: ID do vínculo/contrato
- **Headers:** `Authorization: Bearer <token>`

---

## 3. Enviar Comprovante de Pagamento (`enviar_comprovante.php`)
O inquilino anexa a foto ou PDF do comprovante (PIX, boleto ou transferência), movendo a parcela para `aguardando_confirmacao`.

- **URL:** `POST /aluguel/api/pagamentos/enviar_comprovante.php`
- **Autenticação:** Requer token (`inquilino` dono ou `gestor` do imóvel)
- **Headers:** `Authorization: Bearer <token>`, `Content-Type: multipart/form-data`
- **Campos FormData:**
  - `pagamento_id` *(int, obrigatório)*
  - `forma_pagamento` *(opcional: `pix`, `boleto`, `transferencia`, `dinheiro`, `outro` — padrão `pix`)*
  - `observacoes` *(opcional)*
  - `arquivo` *(PDF, JPG, PNG, DOC, DOCX)*

---

## 4. Confirmar Recebimento / Dar Baixa (`confirmar.php`)
O gestor confirma que o dinheiro caiu na conta (`confirmar`), devolve o comprovante para reenvio (`rejeitar_comprovante`) ou cancela a cobrança (`cancelar`).

- **URL:** `POST /aluguel/api/pagamentos/confirmar.php`
- **Autenticação:** Requer perfil `gestor`
- **Headers:** `Authorization: Bearer <token>`, `Content-Type: application/json`

### Body (JSON)
```json
{
  "pagamento_id": 1,
  "acao": "confirmar",
  "forma_pagamento": "pix",
  "data_pagamento": "2026-12-05",
  "observacoes": "Recebido via PIX."
}
```
> As URLs retornadas em `url_comprovante` (tanto no `enviar_comprovante.php` quanto no `listar.php`) apontam para [`/api/arquivos/ver.php`](../arquivos/README.md) com token temporário assinado, garantindo que somente o inquilino pagador e o gestor dono do imóvel possam abrir o comprovante.