Clientes

Gestión de clientes (personas atendidas). Requiere rol de attendant o superior.

Endpoints

Método	Endpoint	Descripción	Rol Mínimo
GET	/api/v1/customers	Listar clientes	attendant
POST	/api/v1/customers	Crear cliente	attendant
GET	/api/v1/customers/:id	Buscar cliente	attendant
PUT	/api/v1/customers/:id	Actualizar cliente	attendant
DELETE	/api/v1/customers/:id	Eliminar cliente	attendant
POST	/api/v1/customers/merge	Fusionar clientes duplicados	supervisor

---

Listar Clientes

GET /api/v1/customers

Query Parameters

Parámetro	Tipo	Predeterminado	Descripción
page	integer	1	Número de página
page_size	integer	20	Elementos por página
sort_by	string	name	Campo para ordenamiento (name, email, inserted_at)
sort_order	string	asc	Dirección del ordenamiento
search	string	-	Búsqueda por nombre, email o teléfono

Ejemplo de Request

curl -X GET "https://voki.avanter.com.br/api/v1/customers?search=carlos&page=1" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Respuesta Exitosa (200)

{
  "data": [
    {
      "id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
      "name": "Carlos Ferreira",
      "email": "carlos@email.com",
      "phone": "+5511999998888",
      "document": "123.456.789-00",
      "notes": "Cliente preferencial",
      "call_count": 5,
      "last_call_at": "2026-02-15T14:30:00Z",
      "inserted_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-02-15T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 20,
    "total_pages": 1,
    "total_count": 1
  }
}

---

Crear Cliente

POST /api/v1/customers

Request Body

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre completo
email	string	No	Email
phone	string	No	Teléfono
document	string	No	CPF o CNPJ
notes	string	No	Observaciones

Ejemplo de Request

curl -X POST https://voki.avanter.com.br/api/v1/customers \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "Ana Costa",
      "email": "ana@email.com",
      "phone": "+5511977776655",
      "document": "987.654.321-00"
    }
  }'

Respuesta Exitosa (201)

{
  "data": {
    "id": "3b4c5d6e-7f8a-9012-cdef-345678901234",
    "name": "Ana Costa",
    "email": "ana@email.com",
    "phone": "+5511977776655",
    "document": "987.654.321-00",
    "notes": null,
    "call_count": 0,
    "last_call_at": null,
    "inserted_at": "2026-02-18T15:00:00Z",
    "updated_at": "2026-02-18T15:00:00Z"
  }
}

---

Buscar Cliente

GET /api/v1/customers/:id

Ejemplo de Request

curl -X GET https://voki.avanter.com.br/api/v1/customers/2a3b4c5d-6e7f-8901-bcde-f23456789012 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

---

Actualizar Cliente

PUT /api/v1/customers/:id

Ejemplo de Request

curl -X PUT https://voki.avanter.com.br/api/v1/customers/2a3b4c5d-6e7f-8901-bcde-f23456789012 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "notes": "Cliente VIP - tratamento preferencial"
    }
  }'

---

Eliminar Cliente

DELETE /api/v1/customers/:id

Ejemplo de Request

curl -X DELETE https://voki.avanter.com.br/api/v1/customers/3b4c5d6e-7f8a-9012-cdef-345678901234 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Respuesta Exitosa (204)

Sin cuerpo en la respuesta.

---

Fusionar Clientes

Fusiona dos o más registros de clientes duplicados en un único registro. Requiere rol de supervisor.

POST /api/v1/customers/merge

Request Body

Campo	Tipo	Obligatorio	Descripción
target_id	uuid	Sí	ID del cliente que recibirá los datos
source_ids	uuid[]	Sí	IDs de los clientes a fusionar

Ejemplo de Request

curl -X POST https://voki.avanter.com.br/api/v1/customers/merge \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
    "source_ids": ["3b4c5d6e-7f8a-9012-cdef-345678901234"]
  }'

Respuesta Exitosa (200)

{
  "data": {
    "id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
    "name": "Carlos Ferreira",
    "email": "carlos@email.com",
    "phone": "+5511999998888",
    "document": "123.456.789-00",
    "call_count": 7,
    "merged_count": 1
  }
}

Nota

Los clientes origen (source_ids) serán eliminados y todas sus llamadas serán reasignadas al cliente destino.