sass-imobiliaria/.specify/features/006-client-area/contracts/admin.md

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

{
  "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

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

Quando user_id não corresponde a nenhum ClientUser existente.

---

Response 422 Unprocessable Entity

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

---

Response 401 Unauthorized

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

---

PUT /api/v1/admin/visits//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

{
  "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

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

---

Response 422 Unprocessable Entity

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

---

Response 401 Unauthorized

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