# Zapini API — Tags

**Versão:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticação

Todos os endpoints requerem um Bearer Token:

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

Gere tokens de API no painel admin em **API Docs → Gerenciar Tokens**.

---

## Tags

Gerencie tags de conversas para organizar e categorizar chats. As tags são limitadas ao tenant e podem ser atribuídas a múltiplas conversas.

### GET /tags

Listar todas as tags do tenant.

**Resposta:**

```json
{
  "success": true,
  "data": {
    "tags": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "VIP",
        "color": "#f59e0b",
        "conversations_count": 15,
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-15T10:30:00Z"
      }
    ]
  }
}
```

---

### POST /tags

Criar nova tag.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| name | string | Sim | Nome da tag (máx. 50 caracteres, único por tenant) |
| color | string | Sim | Código hexadecimal de cor (#RRGGBB) |

**Exemplo:**

```bash
curl -X POST https://zapini.app/api/v1/tags \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Important",
    "color": "#ef4444"
  }'
```

**Resposta:**

```json
{
  "success": true,
  "message": "Tag created successfully",
  "data": {
    "tag": {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "Important",
      "color": "#ef4444",
      "conversations_count": 0,
      "created_at": "2025-01-15T12:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z"
    }
  }
}
```

---

### GET /tags/{uuid}

Retorna detalhes da tag.

---

### PATCH /tags/{uuid}

Atualizar tag existente.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| name | string | Não | Novo nome da tag (máx. 50 caracteres) |
| color | string | Não | Novo código hexadecimal de cor (#RRGGBB) |

---

### DELETE /tags/{uuid}

Excluir uma tag. A tag será automaticamente removida de todas as conversas.

---

### PUT /conversations/{uuid}/tags

Atualizar tags atribuídas a uma conversa. Isso substitui todas as tags existentes pela lista fornecida.

**Parâmetros:**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| tag_ids | array | Sim | Array de UUIDs de tags para atribuir |

**Exemplo:**

```bash
curl -X PUT https://zapini.app/api/v1/conversations/550e8400-e29b-41d4-a716-446655440045/tags \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002"]
  }'
```

**Resposta:**

```json
{
  "success": true,
  "message": "Conversation tags updated",
  "data": {
    "tags": [
      {"id": "550e8400-e29b-41d4-a716-446655440001", "name": "VIP", "color": "#f59e0b"},
      {"id": "550e8400-e29b-41d4-a716-446655440002", "name": "Support", "color": "#3b82f6"}
    ]
  }
}
```

**Nota:** Para remover todas as tags de uma conversa, envie um array vazio: `{"tag_ids": []}`

> **Mudança v1.2.0:** Os IDs de tags agora são UUIDs em vez de inteiros.

---

*Gerado por Zapini — https://zapini.app*