US01 - Criar endpoint de cadastro de usuário surdo

[Iewandowski]

Contrato REST API - Cadastro de Usuário Surdo

Visão Geral

API RESTful para cadastro e gerenciamento de usuários surdos no sistema PointTils - plataforma de agendamento de intérpretes de Libras.

Base URL: https://api.pointtils.com/v1

---

1. Deaf Users Controller

POST /deaf-users/register

Registrar novo usuário surdo (pessoa física).

Request Body:

{
  "name": "Maria Santos",
  "email": "maria.santos@exemplo.com",
  "password": "senhaSegura123",
  "phone": "11999999999",
  "gender": "F",
  "birthday": "1990-05-15",
  "cpf": "12345678901",
  "picture": "base64_encoded_image",
  "status": "active",
  "type": "person",
  "location": {
    "uf": "SP",
    "city": "São Paulo"
  }
}

Responses:

• 201 Created - Usuário surdo registrado com sucesso

  {
    "success": true,
    "message": "Usuário surdo cadastrado com sucesso",
    "data": {
      "user": {
        "id": 123,
        "name": "Maria Santos",
        "email": "maria.santos@exemplo.com",
        "type": "person",
        "status": "active",
        "phone": "11999999999",
        "gender": "F",
        "birthday": "1990-05-15",
        "cpf": "123.***.***-01",
        "picture": "https://storage.pointtils.com/avatars/123.jpg",
        "location": {
          "id": 456,
          "uf": "SP",
          "city": "São Paulo"
        },
        "created_at": "2025-08-26T10:00:00Z"
      }
    }
  }

• 400 Bad Request - Dados inválidos
• 409 Conflict - CPF ou email já existem
• 422 Unprocessable Entity - Validação falhou

Códigos de Status Utilizados

Status	Descrição	Uso
200	OK	Operação bem-sucedida
201	Created	Usuário/empresa criado com sucesso
400	Bad Request	Dados inválidos
401	Unauthorized	Não autenticado
403	Forbidden	Sem permissão
404	Not Found	Recurso 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: Validação de formato (11 dígitos) e dígitos verificadores
• CNPJ: Validação de formato (14 dígitos) e dígitos verificadores
• Email: Formato válido e unicidade no sistema
• Telefone: Formato brasileiro válido (11 dígitos)
• Data de nascimento: Idade mínima de 16 anos