Documentação da API de Acesso (Access API)

Esta documentação descreve os endpoints de gerenciamento de usuários e funções (roles) do módulo de Acesso.

Visão Geral

• Base URL: /access/manager
• Autenticação: Bearer Token (Laravel Sanctum)
• Headers Obrigatórios:
  • Accept: application/json
  • Content-Type: application/json
  • account: ID da conta ativa (ou X-Account-Id)

---

Gerenciamento de Usuários (UsersController)

1. Listar Usuários

Retorna uma lista paginada de usuários associados à conta ativa, excluindo o usuário autenticado.

• Método: GET
• Rota: /users
• Autenticação: Sim

Parâmetros de Query (Opcionais)

Nome	Tipo	Descrição
per_page	integer	Itens por página (padrão: 100)
page	integer	Número da página
search	string	Busca por nome, email ou documento
status	string	Filtro por status do usuário
role	string	Filtro por nome da função

Exemplo de Resposta (200 OK)

{
  "data": [
    {
      "id": 1,
      "user_id": 10,
      "account_id": 5,
      "user": {
        "id": 10,
        "name": "João Silva",
        "email": "joao@exemplo.com",
        "phone": "11999999999",
        "document": "12345678901",
        "status": 1
      },
      "roles": [
        { "id": 2, "name": "Vendedor" }
      ],
      "created_at": "2024-02-23T11:00:00.000000Z",
      "updated_at": "2024-02-23T11:00:00.000000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 100,
    "total_pages": 1,
    "has_next_page": false,
    "has_prev_page": false
  },
  "message": "Lista de usuários recuperada com sucesso!"
}

---

2. Criar Usuário

Cria um novo usuário ou associa um existente à conta atual.

• Método: POST
• Rota: /users
• Autenticação: Sim

Payload (JSON)

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome (máx 30 caracteres)
email	string	Sim	E-mail único
document	string	Sim	CPF/CNPJ único
role	integer	Sim	ID da função (Role)
password	string	Condicional	Obrigatório se a Role não for "API" (mín 5 caracteres)
phone	string	Não	Telefone de contato

Exemplo de Requisição

{
  "name": "Maria Oliveira",
  "email": "maria@exemplo.com",
  "document": "98765432100",
  "role": 3,
  "password": "secretpassword",
  "phone": "11988887777"
}

Respostas

• 201 Created: Usuário criado com sucesso.
• 422 Unprocessable Entity: Erro de validação.

  {
    "code": 422,
    "message": "The email has already been taken.",
    "success": false,
    "data": {
      "email": ["The email has already been taken."]
    }
  }

---

3. Detalhes do Usuário

Recupera as informações detalhadas de um usuário específico.

• Método: GET
• Rota: /users/\{id\}
• Autenticação: Sim

Exemplo de Resposta (200 OK)

{
  "data": {
    "id": 1,
    "user_id": 10,
    "user": { ... },
    "roles": [ ... ]
  },
  "message": "Usuário recuperado com sucesso!"
}

---

4. Atualizar Usuário

Atualiza os dados de um usuário existente.

• Método: PUT / PATCH
• Rota: /users/\{id\}
• Autenticação: Sim

Payload (JSON)

Mesmos campos da Criação, mas password não é obrigatário e email/document podem ser os mesmos do próprio usuário.

Resposta (200 OK)

{
  "data": { ... },
  "message": "Usuário atualizado com sucesso!"
}

---

5. Remover Usuário

Remove a associação do usuário com a conta (e remove o usuário do sistema). Não é permitido apagar a si mesmo.

• Método: DELETE
• Rota: /users/\{id\}
• Autenticação: Sim

Respostas

• 200 OK: Usuário removido com sucesso.
• 422 Unprocessable Entity: Tentativa de excluir o próprio usuário autenticado.

---

Gerenciamento de Funções (RolesController)

1. Listar Roles Disponíveis

Retorna as funções (roles) que podem ser atribuídas a novos usuários (filtros automáticos removem funções administrativas e de sistema).

• Método: GET
• Rota: /guard/roles
• Autenticação: Sim

Exemplo de Resposta (200 OK)

{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "name": "Vendedor",
      "guard_name": "api",
      "description": "O total de vendevor",
      "permissions": [ ... ]
    }
  ],
  "total": 1
}

---

Respostas de Erro Comuns

401 Unauthorized (Não Autorizado)

Token Inválido ou ausente.

{
  "message": "Unauthenticated."
}

403 Forbidden (Proibido)

Usuário sem permissão para acessar o recurso.

{
  "message": "This action is unauthorized."
}

404 Not Found (Não Encontrado)

Recurso solicitado não existe.

{
  "code": 404,
  "message": "Nenhum resultado encontrado para o modelo especificado.",
  "success": false,
  "data": "No query results for model [App\\Models\\UserAccount] 99"
}

500 Internal Server Error (Erro Interno)

Erro genérico no servidor.

{
  "code": 500,
  "message": "Ocorreu um erro. Processo não concluído.",
  "success": false,
  "data": "Mensagem detalhada do erro (em ambiente de dev)"
}