143 lines
2.7 KiB
Markdown
143 lines
2.7 KiB
Markdown
# 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" }
|
|
```
|