Usuarios

Gestión de usuarios de la plataforma. La mayoría de los endpoints requiere rol de manager o superior.

Endpoints

Método	Endpoint	Descripción	Rol Mínimo
GET	/api/v1/users/me	Datos del usuario autenticado	attendant
GET	/api/v1/users	Listar usuarios	manager
POST	/api/v1/users	Crear usuario	manager
GET	/api/v1/users/:id	Buscar usuario por ID	manager
PUT	/api/v1/users/:id	Actualizar usuario	manager

Nota

El endpoint DELETE no está disponible. Los usuarios se desactivan mediante actualización del campo active.

---

Usuario Actual

Devuelve los datos del usuario autenticado.

GET /api/v1/users/me

Ejemplo de Request

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

Respuesta Exitosa (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 Usuarios

Devuelve la lista paginada de usuarios del tenant.

GET /api/v1/users

Query Parameters

Parámetro	Tipo	Predeterminado	Descripción
page	integer	1	Número de página
page_size	integer	20	Elementos por página (máx. 100)
sort_by	string	name	Campo para ordenamiento (name, email, role, inserted_at)
sort_order	string	asc	Dirección (asc, desc)
search	string	-	Filtro por nombre o email
role	string	-	Filtro por rol (attendant, supervisor, manager)
active	boolean	-	Filtro por estado activo/inactivo

Ejemplo 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"

Respuesta Exitosa (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
  }
}

---

Crear Usuario

Crea un nuevo usuario en el tenant.

POST /api/v1/users

Request Body

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre completo (mín. 2 caracteres)
email	string	Sí	Email único en el tenant
password	string	Sí	Contraseña (mín. 8 caracteres)
role	string	Sí	Rol: attendant, supervisor o manager
locale	string	No	Idioma: pt-BR, en-US, es-ES, fr (predeterminado: pt-BR)

Ejemplo 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"
    }
  }'

Respuesta Exitosa (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"
  }
}

Errores

Código	Descripción
422	Datos inválidos (email duplicado, contraseña débil, etc.)
403	Sin permiso (rol insuficiente)

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

---

Buscar Usuario

Devuelve los datos de un usuario específico.

GET /api/v1/users/:id

Path Parameters

Parámetro	Tipo	Descripción
id	uuid	ID del usuario

Ejemplo 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"

Respuesta Exitosa (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"
  }
}

Errores

Código	Descripción
404	Usuario no encontrado

---

Actualizar Usuario

Actualiza los datos de un usuario existente.

PUT /api/v1/users/:id

Request Body

Campo	Tipo	Obligatorio	Descripción
name	string	No	Nombre completo
email	string	No	Email
password	string	No	Nueva contraseña
role	string	No	Nuevo rol
active	boolean	No	Activar/desactivar
locale	string	No	Idioma

Ejemplo 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
    }
  }'

Respuesta Exitosa (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"
  }
}