Pular para o conteúdo principal

Exemplos de API

Introducao ao documento​

Exemplos de request/response derivados dos controladores e validacoes da API. Onde o contrato nao esta totalmente inferivel, a lacuna e registrada em Pendencias.

Versionamento​

  • Versao do documento: 1.0.0
  • Ultima atualizacao: 2026-03-17
  • Responsavel: GitHub Copilot

Referencial teorico​

  • OpenAPI 3.0.3
  • HTTP/JSON APIs
  • Validacao de entrada Laravel

Autenticacao​

A maioria dos endpoints em /api exige header Authorization validado contra tabela api_keys.

Authorization: <API_KEY>
  • Evidencia: routes/api.php:26
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:22
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:39

1) Criar agendamento​

Endpoint: POST /api/appointments

Request​

{
  "start_time": "2026-03-20T14:00:00",
  "finish_time": "2026-03-20T15:00:00",
  "comments": "Atendimento inicial",
  "additional_fields": "{\"course_name\":\"Mentoria X\",\"link\":\"https://hub.sebraeingresse.com.br\"}",
  "class_id": "123",
  "client_id": "12345678909",
  "employee_id": "98765432100",
  "type_id": 3
}

Response 201​

{
  "status": 201,
  "message": "Appointment created successfully",
  "data": {
    "id": 100,
    "start_time": "2026-03-20T14:00:00.000000Z",
    "finish_time": "2026-03-20T15:00:00.000000Z",
    "class_id": "123",
    "client_id": 12,
    "employee_id": 5,
    "type_id": 3
  }
}

Response 409 (conflito)​

{
  "status": 409,
  "message": "There is another appointment within the specified time range.",
  "data": true
}
  • Evidencia: app/Http/Controllers/AppointmentController.php:161
  • Evidencia: app/Http/Controllers/AppointmentController.php:167
  • Evidencia: app/Http/Controllers/AppointmentController.php:176
  • Evidencia: app/Http/Controllers/AppointmentController.php:213

2) Listar slots disponiveis​

Endpoint: GET /api/appointments/slots/2026-03-20/employee/98765432100/client/12345678909

Response 200​

{
  "status": 200,
  "message": "Available appointments slots. Data from db",
  "data": [
    {"id": "2026-03-20 09:00:00", "date": "2026-03-20", "time": "09:00:00"},
    {"id": "2026-03-20 10:00:00", "date": "2026-03-20", "time": "10:00:00"}
  ]
}
  • Evidencia: routes/api.php:30
  • Evidencia: app/Http/Controllers/AppointmentController.php:583
  • Evidencia: app/Http/Controllers/AppointmentController.php:601
  • Evidencia: app/Models/Appointment.php:117

3) Mover agendamentos futuros​

Endpoint: POST /api/appointments/move/from/98765432100/to/11122233344/class/123

Response 200​

{
  "status": 200,
  "message": "Upcoming appointments moved successfully.",
  "data": {
    "moved": [],
    "unmoved": []
  }
}
  • Evidencia: routes/api.php:38
  • Evidencia: app/Http/Controllers/AppointmentController.php:475
  • Evidencia: app/Http/Controllers/AppointmentController.php:503

4) Buscar cliente por CPF​

Endpoint: GET /api/clients/cpf/12345678909

Response 200​

{
  "status": 200,
  "message": "Usuario encontrado.",
  "data": {
    "id": 12,
    "name": "Cliente Exemplo",
    "cpf": "12345678909"
  }
}
  • Evidencia: routes/api.php:40
  • Evidencia: app/Http/Controllers/ClientController.php:46
  • Evidencia: app/Http/Controllers/ClientController.php:54

5) Limpar cache​

Endpoint: GET /api/cache/flush

Response 200​

{
  "status": "success",
  "message": "Cache flushed successfully.",
  "data": true
}
  • Evidencia: routes/api.php:42
  • Evidencia: app/Http/Controllers/CacheController.php:15

6) Exportar agendamentos para S3​

Endpoint: GET /api/export-appointments

Response 200​

{
  "message": "Arquivo exportado e enviado ao S3 com sucesso. 42 Agendamentos.",
  "url": "https://bucket.s3.amazonaws.com/appointments/last-update.csv"
}
  • Evidencia: routes/api.php:46
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:91
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:98

Endpoints sem cobertura completa nesta versao​

  • Grupo /api/v1/* com auth:api (permissions, roles, users, services, employees, clients, appointments): cobertura parcial no openapi por falta de visibilidade completa dos resources/serializacao e de metodos aparentes ausentes como updateDate.
  • Evidencia: routes/api.php:55
  • Evidencia: routes/api.php:76
  • Evidencia: app/Http/Controllers/Api/V1/Admin/AppointmentsApiController.php:12

Pendencias​

  • Parametro client nas rotas de slots nao e utilizado no metodo correspondente.
    • Evidencia: routes/api.php:30
    • Evidencia: app/Http/Controllers/AppointmentController.php:577
  • Existe potencial divergencia entre validacao de update (class_id existe em clients) e regra de dominio de class_id textual/numerico.
    • Evidencia: app/Http/Controllers/AppointmentController.php:331
    • Evidencia: app/Http/Controllers/AppointmentController.php:166