# Zapini API — Tags

**Versión:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticación

Todos los endpoints requieren un Bearer Token:

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

Genera tokens de API en el panel admin en **API Docs → Gestionar Tokens**.

---

## Tags

Gestiona tags de conversaciones para organizar y categorizar chats. Las tags son de ámbito de tenant y pueden asignarse a múltiples conversaciones.

### GET /tags

Listar todas las tags del tenant actual.

**Respuesta:**

```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

Crear una nueva tag.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| name | string | Sí | Nombre de la tag (máx. 50 caracteres, único por tenant) |
| color | string | Sí | Código de color hexadecimal (#RRGGBB) |

**Ejemplo:**

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

**Respuesta:**

```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 detalles de la tag.

---

### PATCH /tags/{uuid}

Actualizar una tag existente.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| name | string | No | Nuevo nombre de la tag (máx. 50 caracteres) |
| color | string | No | Nuevo código de color hexadecimal (#RRGGBB) |

---

### DELETE /tags/{uuid}

Eliminar una tag. La tag será eliminada automáticamente de todas las conversaciones.

---

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

Actualizar tags asignadas a una conversación. Esto reemplaza todas las tags existentes con la lista proporcionada.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| tag_ids | array | Sí | Array de UUIDs de tags a asignar |

**Ejemplo:**

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

**Respuesta:**

```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 eliminar todas las tags de una conversación, envía un array vacío: `{"tag_ids": []}`

> **Cambio importante v1.2.0:** Los IDs de tags ahora son UUIDs en lugar de enteros.

---

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