Tags

Gerenciamento de tags para categorização de chamadas. Tags podem ser organizadas em hierarquia (árvore). Requer papel de attendant ou superior.

Endpoints

Método	Endpoint	Descrição	Role Mínimo
GET	/api/v1/tags	Listar tags	attendant
POST	/api/v1/tags	Criar tag	attendant
GET	/api/v1/tags/:id	Buscar tag	attendant
PUT	/api/v1/tags/:id	Atualizar tag	attendant
DELETE	/api/v1/tags/:id	Excluir tag	supervisor
GET	/api/v1/tags/tree	Árvore hierárquica de tags	attendant

---

Listar Tags

GET /api/v1/tags

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
page	integer	1	Número da página
page_size	integer	50	Itens por página
sort_by	string	name	Campo para ordenação
sort_order	string	asc	Direção da ordenação
search	string	-	Filtro por nome

Exemplo de Request

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

Resposta de Sucesso (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
  }
}

---

Criar Tag

POST /api/v1/tags

Request Body

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da tag
color	string	Não	Cor em hexadecimal (padrão: #6b7280)
parent_id	uuid	Não	ID da tag pai (para hierarquia)

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

Resposta de Sucesso (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

---

Atualizar Tag

PUT /api/v1/tags/:id

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

---

Excluir Tag

DELETE /api/v1/tags/:id

Nota

Tags com sub-tags serão excluídas em cascata. Tags aplicadas a chamadas serão desassociadas.

Exemplo 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"

Resposta de Sucesso (204)

Sem corpo na resposta.

---

Árvore de Tags

Retorna as tags organizadas em estrutura hierárquica.

GET /api/v1/tags/tree

Exemplo de Request

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

Resposta de Sucesso (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": []
    }
  ]
}