Tags

Gestion des tags pour la catégorisation des appels. Les tags peuvent être organisés en hiérarchie (arborescence). Nécessite le rôle attendant ou supérieur.

Endpoints

Méthode	Endpoint	Description	Rôle Minimum
GET	/api/v1/tags	Lister les tags	attendant
POST	/api/v1/tags	Créer un tag	attendant
GET	/api/v1/tags/:id	Rechercher un tag	attendant
PUT	/api/v1/tags/:id	Mettre à jour un tag	attendant
DELETE	/api/v1/tags/:id	Supprimer un tag	supervisor
GET	/api/v1/tags/tree	Arborescence hiérarchique des tags	attendant

---

Lister les Tags

GET /api/v1/tags

Query Parameters

Paramètre	Type	Défaut	Description
page	integer	1	Numéro de page
page_size	integer	50	Éléments par page
sort_by	string	name	Champ de tri
sort_order	string	asc	Direction du tri
search	string	-	Filtre par nom

Exemple de Requête

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

Réponse de Succès (200)

{
  "data": [
    {
      "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Suporte",
      "color": "#3b82f6",
      "parent_id": null,
      "usage_count": 45,
      "inserted_at": "2026-01-10T09:00:00Z"
    },
    {
      "id": "t2b3c4d5-e6f7-8901-bcde-f23456789012",
      "name": "Bug",
      "color": "#ef4444",
      "parent_id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "usage_count": 12,
      "inserted_at": "2026-01-10T09:30:00Z"
    },
    {
      "id": "t3c4d5e6-f7a8-9012-cdef-345678901234",
      "name": "Vendas",
      "color": "#22c55e",
      "parent_id": null,
      "usage_count": 30,
      "inserted_at": "2026-01-10T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 50,
    "total_pages": 1,
    "total_count": 3
  }
}

---

Créer un Tag

POST /api/v1/tags

Request Body

Champ	Type	Obligatoire	Description
name	string	Oui	Nom du tag
color	string	Non	Couleur en hexadécimal (défaut : #6b7280)
parent_id	uuid	Non	ID du tag parent (pour la hiérarchie)

Exemple de Requête

curl -X POST https://voki.avanter.com.br/api/v1/tags \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "Feature Request",
      "color": "#8b5cf6",
      "parent_id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890"
    }
  }'

Réponse de Succès (201)

{
  "data": {
    "id": "t4d5e6f7-a8b9-0123-defg-456789012345",
    "name": "Feature Request",
    "color": "#8b5cf6",
    "parent_id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "usage_count": 0,
    "inserted_at": "2026-02-18T17:00:00Z"
  }
}

---

Rechercher un Tag

GET /api/v1/tags/:id

---

Mettre à Jour un Tag

PUT /api/v1/tags/:id

Exemple de Requête

curl -X PUT https://voki.avanter.com.br/api/v1/tags/t1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "color": "#2563eb"
    }
  }'

---

Supprimer un Tag

DELETE /api/v1/tags/:id

Note

Les tags avec des sous-tags seront supprimés en cascade. Les tags appliqués aux appels seront dissociés.

Exemple de Requête

curl -X DELETE https://voki.avanter.com.br/api/v1/tags/t4d5e6f7-a8b9-0123-defg-456789012345 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Réponse de Succès (204)

Pas de corps dans la réponse.

---

Arborescence des Tags

Retourne les tags organisés en structure hiérarchique.

GET /api/v1/tags/tree

Exemple de Requête

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

Réponse de Succès (200)

{
  "data": [
    {
      "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Suporte",
      "color": "#3b82f6",
      "usage_count": 45,
      "children": [
        {
          "id": "t2b3c4d5-e6f7-8901-bcde-f23456789012",
          "name": "Bug",
          "color": "#ef4444",
          "usage_count": 12,
          "children": []
        },
        {
          "id": "t4d5e6f7-a8b9-0123-defg-456789012345",
          "name": "Feature Request",
          "color": "#8b5cf6",
          "usage_count": 0,
          "children": []
        }
      ]
    },
    {
      "id": "t3c4d5e6-f7a8-9012-cdef-345678901234",
      "name": "Vendas",
      "color": "#22c55e",
      "usage_count": 30,
      "children": []
    }
  ]
}