Tags

Gestión de tags para categorización de llamadas. Las tags pueden organizarse en jerarquía (árbol). Requiere rol de attendant o superior.

Endpoints

Método	Endpoint	Descripción	Rol Mínimo
GET	/api/v1/tags	Listar tags	attendant
POST	/api/v1/tags	Crear tag	attendant
GET	/api/v1/tags/:id	Buscar tag	attendant
PUT	/api/v1/tags/:id	Actualizar tag	attendant
DELETE	/api/v1/tags/:id	Eliminar tag	supervisor
GET	/api/v1/tags/tree	Árbol jerárquico de tags	attendant

---

Listar Tags

GET /api/v1/tags

Query Parameters

Parámetro	Tipo	Predeterminado	Descripción
page	integer	1	Número de página
page_size	integer	50	Elementos por página
sort_by	string	name	Campo para ordenamiento
sort_order	string	asc	Dirección del ordenamiento
search	string	-	Filtro por nombre

Ejemplo de Request

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

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

---

Crear Tag

POST /api/v1/tags

Request Body

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre de la tag
color	string	No	Color en hexadecimal (predeterminado: #6b7280)
parent_id	uuid	No	ID de la tag padre (para jerarquía)

Ejemplo de Request

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

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

---

Buscar Tag

GET /api/v1/tags/:id

---

Actualizar Tag

PUT /api/v1/tags/:id

Ejemplo de Request

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

---

Eliminar Tag

DELETE /api/v1/tags/:id

Nota

Las tags con sub-tags serán eliminadas en cascada. Las tags aplicadas a llamadas serán desasociadas.

Ejemplo de Request

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

Respuesta Exitosa (204)

Sin cuerpo en la respuesta.

---

Árbol de Tags

Devuelve las tags organizadas en estructura jerárquica.

GET /api/v1/tags/tree

Ejemplo de Request

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

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