> For the complete documentation index, see [llms.txt](https://anunzi-ai.gitbook.io/anunzi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://anunzi-ai.gitbook.io/anunzi-docs/api-widgets/consultar-ticket.md). # 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 ``` *** ## 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.