Clients

Gestion des clients (personnes prises en charge). Nécessite le rôle attendant ou supérieur.

Endpoints

Méthode	Endpoint	Description	Rôle Minimum
GET	/api/v1/customers	Lister les clients	attendant
POST	/api/v1/customers	Créer un client	attendant
GET	/api/v1/customers/:id	Rechercher un client	attendant
PUT	/api/v1/customers/:id	Mettre à jour un client	attendant
DELETE	/api/v1/customers/:id	Supprimer un client	attendant
POST	/api/v1/customers/merge	Fusionner des clients en double	supervisor

---

Lister les Clients

GET /api/v1/customers

Query Parameters

Paramètre	Type	Défaut	Description
page	integer	1	Numéro de page
page_size	integer	20	Éléments par page
sort_by	string	name	Champ de tri (name, email, inserted_at)
sort_order	string	asc	Direction du tri
search	string	-	Recherche par nom, email ou téléphone

Exemple de Requête

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

Réponse de Succès (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
  }
}

---

Créer un Client

POST /api/v1/customers

Request Body

Champ	Type	Obligatoire	Description
name	string	Oui	Nom complet
email	string	Non	Email
phone	string	Non	Téléphone
document	string	Non	CPF ou CNPJ
notes	string	Non	Observations

Exemple de Requête

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

Réponse de Succès (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"
  }
}

---

Rechercher un Client

GET /api/v1/customers/:id

Exemple de Requête

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

---

Mettre à Jour un Client

PUT /api/v1/customers/:id

Exemple de Requête

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": "Client VIP - traitement préférentiel"
    }
  }'

---

Supprimer un Client

DELETE /api/v1/customers/:id

Exemple de Requête

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

Réponse de Succès (204)

Pas de corps dans la réponse.

---

Fusionner des Clients

Fusionne deux ou plusieurs enregistrements de clients en double en un seul enregistrement. Nécessite le rôle supervisor.

POST /api/v1/customers/merge

Request Body

Champ	Type	Obligatoire	Description
target_id	uuid	Oui	ID du client qui recevra les données
source_ids	uuid[]	Oui	IDs des clients à fusionner

Exemple de Requête

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

Réponse de Succès (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
  }
}

Note

Les clients sources (source_ids) seront supprimés et tous leurs appels seront réattribués au client cible.