# Crear ticket desde un agente

Este endpoint permite que un agente de IA abra un ticket de soporte de forma automática al detectar un reclamo, consulta o solicitud durante una conversación.

***

## ¿Para qué sirve?

Configura a tu agente para que, cuando identifique un reclamo, llame a este endpoint. El ticket queda registrado en el panel de la cuenta con toda la información del caso, y el owner recibe una notificación in-app inmediata.

El agente puede entonces informarle al contacto su número de caso (`CAS-XXXXXX`) como confirmación de que el reclamo fue registrado.

***

## Obtener el token del agente

Cada agente tiene su propio **API Token**, que autoriza las operaciones sobre tu cuenta. Para obtenerlo:

1. Ve a **Agentes de Llamada** (o WhatsApp) en el menú lateral.
2. Selecciona el agente que quieres configurar.
3. En la sección **Resumen**, encontrarás el **API Token**.
4. Cópialo para incluirlo en las solicitudes.

> 🔒 Trata el token como una contraseña. No lo compartas públicamente ni lo incluyas en código que suba a repositorios públicos.

***

## Endpoint

```
POST https://panel.anunzi.net/api/tickets.php
```

### Encabezados requeridos

```
Authorization: Bearer TU_TOKEN_DE_AGENTE
Content-Type: application/json
```

> También podés autenticarte con tu **API Key de cuenta** (`anz_live_…`), que cubre toda tu cuenta con una sola credencial — ver [API Keys de cuenta](api-keys.md).


***

## Cuerpo de la solicitud (JSON)

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `title` | texto | ✅ Sí | Título o asunto del ticket. Máximo 255 caracteres. |
| `description` | texto | ✅ Sí | Detalle del reclamo o consulta. Se guarda como el primer mensaje en el hilo del ticket. |
| `category` | texto | No | Categoría del caso. Ver valores válidos abajo. Por defecto: `reclamo`. |
| `priority` | texto | No | Prioridad del caso. Ver valores válidos abajo. Por defecto: `normal`. |
| `contact_phone` | texto (solo dígitos) | No | Teléfono del contacto. Si coincide con un contacto existente en tu cuenta, el ticket queda vinculado automáticamente. |
| `contact_name` | texto | No | Nombre del contacto. Si se omite pero se encontró un lead por teléfono, se usa el nombre del lead. |

### Valores válidos para `category`

| Valor | Etiqueta |
|---|---|
| `reclamo` | Reclamo |
| `consulta` | Consulta |
| `garantia` | Garantía |
| `devolucion` | Devolución / Reembolso |
| `producto` | Producto / Servicio |
| `otro` | Otro |

### Valores válidos para `priority`

| Valor | Etiqueta |
|---|---|
| `baja` | Baja |
| `normal` | Normal |
| `alta` | Alta |
| `urgente` | Urgente |

***

## Ejemplos de solicitud

### Crear un reclamo básico

```bash
curl -X POST "https://panel.anunzi.net/api/tickets.php" \
  -H "Authorization: Bearer TU_TOKEN_AQUÍ" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Producto recibido con daños",
    "description": "El cliente indica que recibió el paquete con la caja rota y el producto dañado visualmente. Pidió que se revise el caso antes del viernes.",
    "category": "reclamo",
    "priority": "alta",
    "contact_phone": "5491123456789",
    "contact_name": "María García"
  }'
```

### Crear una consulta de garantía sin vincular contacto

```bash
curl -X POST "https://panel.anunzi.net/api/tickets.php" \
  -H "Authorization: Bearer TU_TOKEN_AQUÍ" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulta sobre garantía extendida",
    "description": "El cliente preguntó si su compra de marzo 2025 todavía tiene cobertura de garantía.",
    "category": "garantia"
  }'
```

***

## Respuesta — 200 OK

```json
{
  "ok": true,
  "case_number": "CAS-000042",
  "ticket_id": 42,
  "lead_linked": true
}
```

| Campo | Descripción |
|---|---|
| `ok` | `true` si el ticket se creó correctamente. |
| `case_number` | Número de caso asignado, en formato `CAS-XXXXXX`. Puedes comunicárselo al contacto. |
| `ticket_id` | ID interno del ticket en Anunzi. |
| `lead_linked` | `true` si se encontró y vinculó un contacto existente por teléfono. `false` si no se encontró coincidencia. |

***

## Códigos de estado

| Código | Descripción |
|---|---|
| `200` | Ticket creado correctamente. |
| `400` | Faltan campos requeridos (`title` o `description`). El campo `error` indica el motivo. |
| `401` | Token ausente o inválido. |
| `403` | El agente no tiene un usuario asociado. Contacta a soporte. |
| `500` | Error interno del servidor. |

### Respuesta de error

```json
{
  "ok": false,
  "error": "El campo title es requerido."
}
```

***

## Vinculación automática de contactos

Si incluyes `contact_phone` en la solicitud, el sistema busca en tu base de contactos si existe alguno con ese número de teléfono. La búsqueda prueba automáticamente variantes (con y sin prefijo de país) para maximizar la tasa de coincidencia.

Si se encuentra una coincidencia, el ticket queda vinculado al contacto y puedes acceder a su ficha completa directamente desde el detalle del ticket en el panel.

***

## Comportamiento en el panel

Una vez creado el ticket:

1. Aparece en la sección **Tickets de Soporte** del panel, con estado **Abierto**.
2. El owner de la cuenta recibe una **notificación in-app** con el número de caso y el título.
3. El primer mensaje del hilo contiene el texto de `description`, atribuido al agente que lo creó.
4. Si se vinculó un contacto, aparece un enlace directo a su ficha en el detalle del ticket.

***

> 💡 **Tip para agentes de voz**: cuando el agente detecte un reclamo, puede llamar a este endpoint al finalizar la llamada y luego decirle al contacto: _"Registré tu caso con el número CAS-000042. Nuestro equipo se pondrá en contacto contigo en breve."_