Usuários

Gerenciamento de usuários da plataforma. A maioria dos endpoints requer papel de manager ou superior.

Endpoints

Método	Endpoint	Descrição	Role Mínimo
GET	/api/v1/users/me	Dados do usuário logado	attendant
GET	/api/v1/users	Listar usuários	manager
POST	/api/v1/users	Criar usuário	manager
GET	/api/v1/users/:id	Buscar usuário por ID	manager
PUT	/api/v1/users/:id	Atualizar usuário	manager

Nota

O endpoint DELETE não está disponível. Usuários são desativados via atualização do campo active.

---

Usuário Atual

Retorna os dados do usuário autenticado.

GET /api/v1/users/me

Exemplo de Request

curl -X GET https://voki.avanter.com.br/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (200)

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "João Silva",
    "email": "joao@empresa.com",
    "role": "attendant",
    "active": true,
    "avatar_url": null,
    "mfa_enabled": false,
    "locale": "pt-BR",
    "inserted_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-01T14:20:00Z"
  }
}

---

Listar Usuários

Retorna a lista paginada de usuários do tenant.

GET /api/v1/users

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
page	integer	1	Número da página
page_size	integer	20	Itens por página (máx. 100)
sort_by	string	name	Campo para ordenação (name, email, role, inserted_at)
sort_order	string	asc	Direção (asc, desc)
search	string	-	Filtro por nome ou email
role	string	-	Filtro por role (attendant, supervisor, manager)
active	boolean	-	Filtro por status ativo/inativo

Exemplo de Request

curl -X GET "https://voki.avanter.com.br/api/v1/users?page=1&page_size=10&role=attendant" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (200)

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "João Silva",
      "email": "joao@empresa.com",
      "role": "attendant",
      "active": true,
      "avatar_url": null,
      "mfa_enabled": false,
      "locale": "pt-BR",
      "inserted_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-02-01T14:20:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Maria Santos",
      "email": "maria@empresa.com",
      "role": "attendant",
      "active": true,
      "avatar_url": "https://example.com/avatar.jpg",
      "mfa_enabled": true,
      "locale": "pt-BR",
      "inserted_at": "2026-01-20T08:00:00Z",
      "updated_at": "2026-01-20T08:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 10,
    "total_pages": 3,
    "total_count": 25
  }
}

---

Criar Usuário

Cria um novo usuário no tenant.

POST /api/v1/users

Request Body

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome completo (mín. 2 caracteres)
email	string	Sim	Email único no tenant
password	string	Sim	Senha (mín. 8 caracteres)
role	string	Sim	Papel: attendant, supervisor ou manager
locale	string	Não	Idioma: pt-BR, en-US, es-ES, fr (padrão: pt-BR)

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/v1/users \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "name": "Pedro Oliveira",
      "email": "pedro@empresa.com",
      "password": "senhaSegura123",
      "role": "attendant",
      "locale": "pt-BR"
    }
  }'

Resposta de Sucesso (201)

{
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Pedro Oliveira",
    "email": "pedro@empresa.com",
    "role": "attendant",
    "active": true,
    "avatar_url": null,
    "mfa_enabled": false,
    "locale": "pt-BR",
    "inserted_at": "2026-02-18T10:00:00Z",
    "updated_at": "2026-02-18T10:00:00Z"
  }
}

Erros

Código	Descrição
422	Dados inválidos (email duplicado, senha fraca, etc.)
403	Sem permissão (role insuficiente)

{
  "errors": {
    "email": ["já está em uso"]
  }
}

---

Buscar Usuário

Retorna os dados de um usuário específico.

GET /api/v1/users/:id

Path Parameters

Parâmetro	Tipo	Descrição
id	uuid	ID do usuário

Exemplo de Request

curl -X GET https://voki.avanter.com.br/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (200)

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "João Silva",
    "email": "joao@empresa.com",
    "role": "attendant",
    "active": true,
    "avatar_url": null,
    "mfa_enabled": false,
    "locale": "pt-BR",
    "inserted_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-01T14:20:00Z"
  }
}

Erros

Código	Descrição
404	Usuário não encontrado

---

Atualizar Usuário

Atualiza os dados de um usuário existente.

PUT /api/v1/users/:id

Request Body

Campo	Tipo	Obrigatório	Descrição
name	string	Não	Nome completo
email	string	Não	Email
password	string	Não	Nova senha
role	string	Não	Novo papel
active	boolean	Não	Ativar/desativar
locale	string	Não	Idioma

Exemplo de Request

curl -X PUT https://voki.avanter.com.br/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "role": "supervisor",
      "active": true
    }
  }'

Resposta de Sucesso (200)

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "João Silva",
    "email": "joao@empresa.com",
    "role": "supervisor",
    "active": true,
    "avatar_url": null,
    "mfa_enabled": false,
    "locale": "pt-BR",
    "inserted_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-18T11:00:00Z"
  }
}