> ## Documentation Index
> Fetch the complete documentation index at: https://docs.patrimonion.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Financeiro

> Parcelas, pagamentos (integral e parcial), controle automático de inadimplência e geração de recibos.

## O objeto Conta

```json theme={null}
{
  "id": "fin001",
  "contratoId": "con789",
  "descricao": "Aluguel - Fevereiro/2025",
  "valor": 2500,
  "dataVencimento": "2025-02-05",
  "tipo": "ALUGUEL",
  "status": "PAGO",
  "dataPagamento": "2025-02-03T18:00:00.000Z",
  "reciboId": "rec001",
  "userId": "uid_do_usuario",
  "criadoEm": "2025-01-15T10:00:00.000Z"
}
```

### Tipos válidos

| Valor     | Descrição                 |
| --------- | ------------------------- |
| `ALUGUEL` | Parcela mensal de aluguel |
| `CAUCAO`  | Depósito caução           |
| `REPARO`  | Cobrança por reparo/dano  |

### Status

| Valor       | Descrição                                                         |
| ----------- | ----------------------------------------------------------------- |
| `PENDENTE`  | Aguardando pagamento                                              |
| `ATRASADO`  | `PENDENTE` com `dataVencimento` anterior a hoje — auto-gerenciado |
| `PAGO`      | Pagamento confirmado                                              |
| `CANCELADO` | Conta cancelada manualmente                                       |

<Info>
  O status `ATRASADO` nunca precisa ser setado manualmente. A API atualiza automaticamente via batch ao listar ou buscar contas.
</Info>

***

## Criar conta

<ParamField body="contratoId" type="string" required>
  ID do contrato ao qual esta conta está vinculada.
</ParamField>

<ParamField body="descricao" type="string" required>
  Descrição legível (ex: `"Aluguel - Fevereiro/2025"`).
</ParamField>

<ParamField body="valor" type="number" required>
  Valor em reais.
</ParamField>

<ParamField body="dataVencimento" type="string" required>
  Data de vencimento no formato `YYYY-MM-DD`.
</ParamField>

<ParamField body="tipo" type="string" required>
  Um dos valores: `ALUGUEL`, `CAUCAO`, `REPARO`.
</ParamField>

```http theme={null}
POST /financeiro
Cookie: imob_session=<session_cookie>
Content-Type: application/json

{
  "contratoId": "con789",
  "descricao": "Aluguel - Fevereiro/2025",
  "valor": 2500,
  "dataVencimento": "2025-02-05",
  "tipo": "ALUGUEL"
}
```

```json Resposta 201 theme={null}
{
  "message": "Conta criada com sucesso",
  "id": "fin001"
}
```

***

## Listar contas

<ParamField query="contratoId" type="string">
  Filtra por contrato específico.
</ParamField>

<ParamField query="status" type="string">
  Filtra por status após a atualização automática de inadimplência.
</ParamField>

```http theme={null}
GET /financeiro?contratoId=con789&status=ATRASADO
Cookie: imob_session=<session_cookie>
```

***

## Listar contas por contrato

Atalho equivalente a `GET /financeiro?contratoId=:id`. Mantido por compatibilidade.

```http theme={null}
GET /financeiro/contrato/:contratoId
Cookie: imob_session=<session_cookie>
```

***

## Registrar pagamento

Este é o endpoint mais importante do módulo. Ele suporta pagamento **integral** e **parcial**.

<ParamField body="valorPago" type="number">
  Valor efetivamente recebido. Se omitido, assume o valor total da conta.
</ParamField>

<ParamField body="formaPagamento" type="string">
  Ex: `"PIX"`, `"Boleto"`, `"Transferência"`. Salvo no recibo.
</ParamField>

```http theme={null}
PATCH /financeiro/:id/pagar
Cookie: imob_session=<session_cookie>
Content-Type: application/json

{
  "valorPago": 2500,
  "formaPagamento": "PIX"
}
```

### Pagamento Integral

```json Resposta 200 — Integral theme={null}
{
  "status": "sucesso",
  "tipo_pagamento": "INTEGRAL",
  "saldo_devedor": 0,
  "recibo_digital": { ... }
}
```

### Pagamento Parcial

Quando `valorPago < valor`:

1. A conta atual é marcada como `PAGO` com o valor recebido e descrição `(Parcial)`.
2. Uma **nova conta** é criada automaticamente com o saldo restante, status `PENDENTE` e mesmo `dataVencimento`.
3. Um recibo do tipo `PARCIAL` é gerado e vinculado.

```json Resposta 200 — Parcial theme={null}
{
  "status": "sucesso",
  "tipo_pagamento": "PARCIAL",
  "saldo_devedor": 500,
  "recibo_digital": { ... }
}
```

<Warning>
  Contas com status `PAGO` ou `CANCELADO` retornam `400 Bad Request` ao tentar pagar novamente.
</Warning>

***

## Atualizar conta

Use para editar campos como `descricao`, `dataVencimento` ou `status` manualmente.

```http theme={null}
PATCH /financeiro/:id
Cookie: imob_session=<session_cookie>
Content-Type: application/json

{
  "status": "CANCELADO"
}
```

***

## Deletar conta

```http theme={null}
DELETE /financeiro/:id
Cookie: imob_session=<session_cookie>
```