# Contract: Admin Endpoints

**Blueprint**: `admin_bp` — prefix `/api/v1/admin`
**Auth**: JWT Bearer — `require_auth` — MVP: qualquer ClientUser autenticado
**Dívida Técnica**: Verificação de role admin adiada para feature pós-MVP (ver Constitution Check no plan.md)

---

# POST /api/v1/admin/boletos

Cria um boleto para um cliente, opcionalmente vinculado a um imóvel.

## Request

```
POST /api/v1/admin/boletos
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "property_id": "4gb96g75-6828-5673-c4gd-3d074g77bg33",
  "description": "Aluguel referente a Maio/2026",
  "amount": 3500.00,
  "due_date": "2026-05-10",
  "url": "https://boleto.banco.com.br/abc123"
}
```

Campos obrigatórios: `user_id`, `description`, `amount`, `due_date`.
Campos opcionais: `property_id`, `url`.

---

## Response 201 Created

```json
{
  "id": "d5be07h8-9012-6784-d5he-4e185h88ch33",
  "description": "Aluguel referente a Maio/2026",
  "amount": "3500.00",
  "due_date": "2026-05-10",
  "status": "pending",
  "url": "https://boleto.banco.com.br/abc123"
}
```

---

## Response 404 Not Found

```json
{ "error": "Cliente não encontrado" }
```

Quando `user_id` não corresponde a nenhum `ClientUser` existente.

---

## Response 422 Unprocessable Entity

```json
{
  "error": "Dados inválidos",
  "details": ["user_id: field required", "amount: field required"]
}
```

---

## Response 401 Unauthorized

```json
{ "error": "Token inválido ou ausente" }
```

---

# PUT /api/v1/admin/visits/<id>/status

Atualiza o status de uma VisitRequest e opcionalmente define a data/hora agendada.

## Request

```
PUT /api/v1/admin/visits/b3fc85f6-1234-4562-b3fc-2c963f66af11/status
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "status": "confirmed",
  "scheduled_at": "2026-05-01T10:00:00"
}
```

`status` obrigatório: `"pending"` | `"confirmed"` | `"cancelled"` | `"completed"`
`scheduled_at` opcional: ISO 8601 datetime string.

---

## Response 200 OK

```json
{
  "id": "b3fc85f6-1234-4562-b3fc-2c963f66af11",
  "property": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "title": "Apartamento 3 quartos Jardins",
    "slug": "apartamento-3-quartos-jardins"
  },
  "message": "Gostaria de visitar no final de semana.",
  "status": "confirmed",
  "scheduled_at": "2026-05-01T10:00:00Z",
  "created_at": "2026-04-13T10:00:00Z"
}
```

---

## Response 404 Not Found

```json
{ "error": "Visita não encontrada" }
```

---

## Response 422 Unprocessable Entity

```json
{
  "error": "Dados inválidos",
  "details": ["status: value is not a valid enumeration member"]
}
```

---

## Response 401 Unauthorized

```json
{ "error": "Token inválido ou ausente" }
```