# Consultar estado de tickets

Este endpoint permite que un agente de IA consulte el estado actual de uno o varios tickets de soporte cuando un contacto pregunta por su caso durante una conversación.

***

## ¿Para qué sirve?

Cuando un contacto menciona su número de caso, su nombre o su teléfono durante una llamada o chat, el agente puede consultar este endpoint en tiempo real y responderle con el estado actualizado del ticket: si está abierto, en proceso, resuelto o cerrado, junto con el último mensaje registrado por el equipo de soporte.

***

## Obtener el token del agente

Cada agente tiene su propio **API Token**, que autoriza el acceso a los datos de tu cuenta. Para obtenerlo:

1. Ve a **Agentes de Llamada** (o WhatsApp) en el menú lateral.
2. Selecciona el agente que quieres usar.
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/ticket-status.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)

Debes indicar **al menos uno** de los siguientes criterios de búsqueda:

| Campo | Tipo | Descripción |
|---|---|---|
| `case_number` | texto | Número de caso. Acepta `CAS-000042`, `CAS-42` o simplemente `42`. |
| `phone` | texto (solo dígitos) | Teléfono del contacto. Devuelve todos sus tickets. El sistema prueba automáticamente variantes con y sin prefijo de país. |
| `contact_name` | texto | Nombre parcial del contacto (búsqueda flexible). Devuelve todos los tickets que coincidan. |

### Campo opcional

| Campo | Tipo | Descripción |
|---|---|---|
| `status` | texto | Filtra por estado: `abierto`, `en_proceso`, `resuelto` o `cerrado`. |

***

## Ejemplos de solicitud

### Consultar por número de caso

```bash
curl -X POST "https://panel.anunzi.net/api/ticket-status.php" \
  -H "Authorization: Bearer TU_TOKEN_AQUÍ" \
  -H "Content-Type: application/json" \
  -d '{"case_number": "CAS-000042"}'
```

### Consultar por teléfono del contacto

```bash
curl -X POST "https://panel.anunzi.net/api/ticket-status.php" \
  -H "Authorization: Bearer TU_TOKEN_AQUÍ" \
  -H "Content-Type: application/json" \
  -d '{"phone": "5491123456789"}'
```

### Consultar por nombre (solo tickets abiertos o en proceso)

```bash
curl -X POST "https://panel.anunzi.net/api/ticket-status.php" \
  -H "Authorization: Bearer TU_TOKEN_AQUÍ" \
  -H "Content-Type: application/json" \
  -d '{"contact_name": "María García", "status": "en_proceso"}'
```

***

## Respuesta — 200 OK

```json
{
  "ok": true,
  "count": 1,
  "tickets": [
    {
      "case_number": "CAS-000042",
      "ticket_id": 42,
      "title": "Producto recibido con daños",
      "status": "en_proceso",
      "status_label": "En proceso",
      "category": "reclamo",
      "category_label": "Reclamo",
      "priority": "alta",
      "priority_label": "Alta",
      "contact_name": "María García",
      "contact_phone": "5491123456789",
      "created_at": "2026-05-20T10:30:00Z",
      "updated_at": "2026-05-25T14:15:00Z",
      "last_message": {
        "author_type": "staff",
        "author_name": "Carlos (Soporte)",
        "body": "Ya derivamos el caso al equipo de logística. Te contactamos antes del viernes.",
        "created_at": "2026-05-25T14:15:00Z"
      }
    }
  ]
}
```

### Respuesta cuando no se encuentran tickets

```json
{
  "ok": true,
  "count": 0,
  "tickets": []
}
```

***

## Descripción de los campos de respuesta

| Campo | Descripción |
|---|---|
| `count` | Cantidad de tickets encontrados. |
| `case_number` | Número de caso en formato `CAS-XXXXXX`. |
| `ticket_id` | ID interno del ticket. |
| `title` | Título o asunto del ticket. |
| `status` | Estado actual en inglés técnico (clave interna). |
| `status_label` | Estado en texto legible: Abierto, En proceso, Resuelto, Cerrado. |
| `category` | Categoría interna. |
| `category_label` | Categoría en texto legible. |
| `priority` | Prioridad interna. |
| `priority_label` | Prioridad en texto legible: Baja, Normal, Alta, Urgente. |
| `contact_name` | Nombre del contacto asociado al ticket. |
| `contact_phone` | Teléfono del contacto (solo dígitos). |
| `created_at` | Fecha y hora de creación del ticket (ISO 8601, UTC). |
| `updated_at` | Fecha y hora de la última actualización (ISO 8601, UTC). |
| `last_message.author_type` | Quién escribió el último mensaje: `agent` (IA), `staff` (equipo), `system` (automático). |
| `last_message.author_name` | Nombre del autor del último mensaje. |
| `last_message.body` | Texto del último mensaje en el hilo. |
| `last_message.created_at` | Fecha y hora del último mensaje (ISO 8601, UTC). |

***

## Códigos de estado

| Código | Descripción |
|---|---|
| `200` | Consulta exitosa. El array `tickets` puede estar vacío si no se encontraron resultados. |
| `400` | No se proporcionó ningún parámetro de búsqueda, o el número de caso es inválido. |
| `401` | Token ausente o inválido. |
| `403` | El agente no tiene un usuario asociado. Contacta a soporte. |
| `500` | Error interno del servidor. |

***

## Ejemplo de uso en un agente de voz

Cuando el contacto diga algo como _"quiero saber el estado de mi reclamo, el número es CAS-000042"_, el agente puede:

1. Extraer el número de caso de la conversación.
2. Llamar a `GET /v1/ticket-status?case_number=CAS-000042`.
3. Leerle al contacto la respuesta: _"Tu caso CAS-000042 sobre **Producto recibido con daños** está actualmente **En proceso**. El último mensaje de nuestro equipo fue: 'Ya derivamos el caso al equipo de logística. Te contactamos antes del viernes.'"_

Si el contacto no recuerda su número de caso, el agente puede buscarlo por teléfono usando el número desde el que llama.