US02 - Criar endpoint de cadastro de usuário intérprete #26
Description
Contrato REST API - Cadastro de Intérprete
Visão Geral
API RESTful para cadastro e gerenciamento de intérpretes de Libras no sistema PointTils.
Base URL: https://api.pointtils.com/v1
1. Interpreter Registration Controller
POST /interpreters/register
Registrar novo intérprete de Libras.
Request Body:
{
"personal_data": {
"name": "Ana Maria Intérprete",
"email": "ana.interprete@exemplo.com",
"password": "senhaSegura123",
"phone": "11999999999",
"gender": "F",
"birthday": "1985-03-20",
"cpf": "98765432101",
"picture": "base64_encoded_image"
},
"location": {
"uf": "SP",
"city": "São Paulo"
},
"professional_data": {
"cnpj": "12345678000199",
"min_value": 150.00,
"max_value": 300.00,
"modality": "ambos",
"description": "Intérprete certificada com 10 anos de experiência em contextos médicos e jurídicos.",
"image_rights": true
}
}Responses:
201 Created- Intérprete registrado com sucesso{ "success": true, "message": "Intérprete cadastrado com sucesso", "data": { "interpreter": { "id": 456, "user": { "id": 123, "email": "ana.interprete@exemplo.com", "type": "person", "status": "pending_verification", "phone": "11999999999", "picture": "https://storage.pointtils.com/avatars/123.jpg" }, "person": { "name": "Ana Maria Intérprete", "gender": "F", "birthday": "1985-03-20", "cpf": "987.***.***-01" }, "professional_info": { "cnpj": "12.345.678/0001-99", "rating": 0.0, "min_value": 150.00, "max_value": 300.00, "modality": "ambos", "description": "Intérprete certificada com 10 anos de experiência...", "image_rights": true }, "location": { "id": 789, "uf": "SP", "city": "São Paulo" }, "specialties": [ { "id": 1, "name": "Médica" }, { "id": 3, "name": "Jurídica" }, { "id": 5, "name": "Educacional" } ], "created_at": "2025-08-26T10:00:00Z" } } }400 Bad Request- Dados inválidos409 Conflict- CPF, CNPJ ou email já existem422 Unprocessable Entity- Validação falhou
GET /interpreters/{id}
Obter dados completos de um intérprete.
Request Headers:
Authorization: Bearer {access_token}
Responses:
200 OK- Dados do intérprete retornados{ "success": true, "message": "Dados do intérprete obtidos com sucesso", "data": { "interpreter": { "id": 456, "user": { "id": 123, "email": "ana.interprete@exemplo.com", "type": "person", "status": "active", "phone": "11999999999", "picture": "https://storage.pointtils.com/avatars/123.jpg", "created_at": "2025-08-26T10:00:00Z", "updated_at": "2025-08-27T14:30:00Z" }, "person": { "name": "Ana Maria Intérprete", "gender": "F", "birthday": "1985-03-20", "cpf": "987.***.***-01" }, "professional_info": { "cnpj": "12.345.678/0001-99", "rating": 4.8, "min_value": 150.00, "max_value": 300.00, "modality": "ambos", "description": "Intérprete certificada com 10 anos de experiência...", "image_rights": true }, "location": { "id": 789, "uf": "SP", "city": "São Paulo" }, "specialties": [ { "id": 1, "name": "Médica" }, { "id": 3, "name": "Jurídica" } ] } } }401 Unauthorized- Não autenticado403 Forbidden- Sem permissão404 Not Found- Intérprete não encontrado
PATCH /interpreters/{id}
Atualizar dados do intérprete.
Request Headers:
Authorization: Bearer {access_token}
Request Body:
{
"personal_data": {
"name": "Ana Maria Silva Intérprete",
"phone": "11988888888",
"picture": "base64_encoded_image"
},
"professional_data": {
"min_value": 180.00,
"max_value": 350.00,
"modality": "presencial",
"description": "Intérprete certificada com 12 anos de experiência...",
"image_rights": false
},
"location": {
"uf": "RJ",
"city": "Rio de Janeiro"
}
}Responses:
200 OK- Intérprete atualizado com sucesso{ "success": true, "message": "Dados do intérprete atualizados com sucesso", "data": { "interpreter": { "id": 456, "updated_fields": [ "name", "phone", "min_value", "max_value", "location" ], "updated_at": "2025-08-26T15:00:00Z" } } }400 Bad Request- Dados inválidos401 Unauthorized- Não autenticado403 Forbidden- Sem permissão404 Not Found- Intérprete não encontrado409 Conflict- CNPJ já em uso por outro intérprete
GET /interpreters
Listar intérpretes com filtros.
Query Parameters:
specialty(optional): Filtrar por especialidadecity(optional): Filtrar por cidadeuf(optional): Filtrar por estadomodality(optional): presencial | online | ambosmin_rating(optional): Rating mínimomax_value(optional): Valor máximoavailable_date(optional): Data de disponibilidade (YYYY-MM-DD)status(optional): Status do intérpretepage(optional): Número da páginalimit(optional): Itens por páginasort(optional): rating | price | distance
Responses:
200 OK- Lista de intérpretes retornada{ "success": true, "message": "Lista de intérpretes obtida com sucesso", "data": { "interpreters": [ { "id": 456, "name": "Ana Maria Intérprete", "rating": 4.8, "total_reviews": 38, "min_value": 150.00, "max_value": 300.00, "modality": "ambos", "image_rights": true, "location": { "city": "São Paulo", "uf": "SP" }, "specialties": [ "Médica", "Jurídica" ], "availability": { "next_available": "2025-08-28T09:00:00Z", "response_time_avg": "2 horas" }, "profile_image": "https://storage.pointtils.com/avatars/123.jpg" } ], "pagination": { "current_page": 1, "total_pages": 5, "total_items": 48, "items_per_page": 10 }, "filters_applied": { "specialty": "Médica", "city": "São Paulo", "min_rating": 4.0 } } }400 Bad Request- Filtros inválidos
POST /interpreters/{id}/specialties
Adicionar ou atualizar especialidades do intérprete.
Request Headers:
Authorization: Bearer {access_token}
Request Body:
{
"specialty_ids": [1, 2, 4, 7],
"replace_all": true
}Responses:
200 OK- Especialidades atualizadas com sucesso{ "success": true, "message": "Especialidades atualizadas com sucesso", "data": { "specialties": [ { "id": 1, "name": "Médica" }, { "id": 2, "name": "Jurídica" }, { "id": 4, "name": "Psicológica" }, { "id": 7, "name": "Empresarial" } ], "changes": { "added": ["Psicológica", "Empresarial"], "removed": ["Educacional"] } } }400 Bad Request- IDs de especialidades inválidos401 Unauthorized- Não autenticado404 Not Found- Intérprete não encontrado
DELETE /interpreters/{id}
Desativar intérprete.
Request Headers:
Authorization: Bearer {access_token}
Path Parameter:
- id: id do usuário
Responses:
204 No Content- Intérprete desativado com sucesso401 Unauthorized- Não autenticado403 Forbidden- Sem permissão404 Not Found- Intérprete não encontrado409 Conflict- Possui agendamentos ativos
Códigos de Status Utilizados
| Status | Descrição | Uso |
|---|---|---|
| 200 | OK | Operação bem-sucedida |
| 201 | Created | Intérprete registrado com sucesso |
| 400 | Bad Request | Dados inválidos |
| 401 | Unauthorized | Não autenticado |
| 403 | Forbidden | Sem permissão |
| 404 | Not Found | Intérprete não encontrado |
| 409 | Conflict | CPF/CNPJ/email já existem |
| 422 | Unprocessable Entity | Validação falhou |
| 500 | Internal Server Error | Erro interno do servidor |
Validações Específicas
Dados Pessoais
- CPF: Formato brasileiro válido (11 dígitos) e único
- CNPJ: Formato brasileiro válido (14 dígitos) e único
- Email: Formato válido e único no sistema
- Telefone: Formato brasileiro (11 dígitos)
- Data de nascimento: Idade mínima 18 anos, máxima 75 anos
Dados Profissionais
- Valores: min_value deve ser menor que max_value
- Rating: Entre 0.0 e 5.0 (calculado automaticamente)
- Modalidade: "presencial", "online" ou "ambos"
- Descrição: Mínimo 50 caracteres, máximo 1000
Localização
- UF: Código brasileiro válido (2 caracteres)
- Cidade: Deve existir no estado especificado
Especialidades
- Mínimo: 1 especialidade obrigatória
- Máximo: 10 especialidades por intérprete
- Validação: IDs devem existir na tabela specialties
Estrutura do Banco de Dados
Relacionamentos Envolvidos
- user → person → interpreter (herança)
- interpreter → user_specialties (N:N)
- interpreter → schedule (1:N)
- interpreter → appointment (1:N)
- interpreter → interpreter_documents (1:N)
- user → location (1:1)
Status Possíveis
- pending_verification: Aguardando verificação
- active: Ativo e disponível
- inactive: Temporariamente inativo
- suspended: Suspenso por violação
- blocked: Bloqueado permanentemente
Headers de Segurança
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'
Rate Limiting
- Registro: 3 tentativas por IP por hora
- Atualizações: 20 por intérprete por hora
- Consultas públicas: 100 por IP por hora
- Consultas autenticadas: 500 por usuário por hora
- Operações admin: 1000 por admin por hora