Départements

Gestion des départements de service client. Les départements organisent les agents et définissent les files d'attente des appels. Nécessite le rôle supervisor ou supérieur.

Important

Les départements possédant des enregistrements associés ne peuvent pas être supprimés. Utilisez la désactivation dans ce cas.

Endpoints

Méthode	Endpoint	Description	Rôle Minimum
GET	/api/v1/departments	Lister les départements	supervisor
POST	/api/v1/departments	Créer un département	supervisor
GET	/api/v1/departments/:id	Rechercher un département	supervisor
PUT	/api/v1/departments/:id	Mettre à jour un département	supervisor
DELETE	/api/v1/departments/:id	Supprimer un département	supervisor
GET	/api/v1/departments/:id/users	Lister les utilisateurs du département	supervisor
POST	/api/v1/departments/:id/users	Ajouter un utilisateur au département	supervisor
DELETE	/api/v1/departments/:id/users/:user_id	Retirer un utilisateur du département	supervisor

---

Lister les Départements

GET /api/v1/departments

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
sort_order	string	asc	Direction du tri

Exemple de Requête

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

Réponse de Succès (200)

{
  "data": [
    {
      "id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
      "name": "Suporte Técnico",
      "identifier": "suporte-tecnico",
      "description": "Departamento de suporte técnico ao cliente",
      "active": true,
      "sector_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
      "max_queue_size": 20,
      "max_wait_time": 300,
      "user_count": 5,
      "inserted_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-02-01T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 10,
    "total_pages": 1,
    "total_count": 3
  }
}

---

Créer un Département

POST /api/v1/departments

Request Body

Champ	Type	Obligatoire	Description
name	string	Oui	Nom du département
identifier	string	Non	Identifiant unique (slug, généré automatiquement si omis)
description	string	Non	Description
sector_id	uuid	Non	ID du secteur associé
max_queue_size	integer	Non	Taille maximale de la file d'attente (défaut : 20)
max_wait_time	integer	Non	Temps d'attente maximum en secondes (défaut : 300)

Exemple de Requête

curl -X POST https://voki.avanter.com.br/api/v1/departments \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "department": {
      "name": "Vendas",
      "description": "Departamento de vendas e consultoria",
      "sector_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
      "max_queue_size": 15,
      "max_wait_time": 180
    }
  }'

Réponse de Succès (201)

{
  "data": {
    "id": "a7b8c9d0-e1f2-3456-ghij-789012345678",
    "name": "Vendas",
    "identifier": "vendas",
    "description": "Departamento de vendas e consultoria",
    "active": true,
    "sector_id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
    "max_queue_size": 15,
    "max_wait_time": 180,
    "user_count": 0,
    "inserted_at": "2026-02-18T12:00:00Z",
    "updated_at": "2026-02-18T12:00:00Z"
  }
}

---

Rechercher un Département

GET /api/v1/departments/:id

Exemple de Requête

curl -X GET https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

---

Mettre à Jour un Département

PUT /api/v1/departments/:id

Exemple de Requête

curl -X PUT https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "department": {
      "name": "Suporte Premium",
      "max_queue_size": 30
    }
  }'

---

Supprimer un Département

DELETE /api/v1/departments/:id

Attention

Les départements avec des enregistrements associés retourneront une erreur 422. Désactivez le département au lieu de le supprimer.

Exemple de Requête

curl -X DELETE https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Réponse de Succès (204)

Pas de corps dans la réponse.

Erreurs

Code	Description
422	Le département possède des enregistrements et ne peut pas être supprimé
404	Département non trouvé

---

Lister les Utilisateurs du Département

GET /api/v1/departments/:department_id/users

Exemple de Requête

curl -X GET https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456/users \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Réponse de Succès (200)

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "João Silva",
      "email": "joao@empresa.com",
      "role": "attendant",
      "active": true
    }
  ]
}

---

Ajouter un Utilisateur au Département

POST /api/v1/departments/:department_id/users

Request Body

Champ	Type	Obligatoire	Description
user_id	uuid	Oui	ID de l'utilisateur à ajouter

Exemple de Requête

curl -X POST https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456/users \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Réponse de Succès (201)

{
  "data": {
    "message": "Utilisateur ajouté au département"
  }
}

---

Retirer un Utilisateur du Département

DELETE /api/v1/departments/:department_id/users/:user_id

Exemple de Requête

curl -X DELETE https://voki.avanter.com.br/api/v1/departments/e5f6a7b8-c9d0-1234-efgh-567890123456/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Réponse de Succès (204)

Pas de corps dans la réponse.