# Agregar nota a un ticket

Este endpoint permite que un agente de IA agregue una nota a un ticket de soporte existente cuando un contacto se vuelve a comunicar para dar seguimiento a su reclamo. Opcionalmente, el agente puede cambiar el estado del ticket al mismo tiempo.

***

## ¿Para qué sirve?

Cuando un contacto llama o escribe nuevamente mencionando un caso que ya tiene abierto, el agente puede:

1. Consultar el ticket con `GET /api/ticket-status.php` para obtener el estado actual.
2. Registrar la nueva información recibida con este endpoint.
3. Si corresponde, actualizar el estado (por ejemplo, pasar de "Abierto" a "En proceso").

La nota queda visible en el hilo del ticket dentro del panel, atribuida al agente de IA.

***

## Obtener el token del agente

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**.

> 🔒 Trata el token como una contraseña. No lo compartas públicamente.

***

## Endpoint

```
POST https://panel.anunzi.net/api/ticket-update.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 |
|---|---|---|---|
| `case_number` | texto | ✅ Sí (si no se usa `ticket_id`) | Número de caso: `CAS-000042`, `CAS-42` o `42`. |
| `ticket_id` | número | ✅ Sí (si no se usa `case_number`) | ID interno del ticket. |
| `note` | texto | ✅ Sí | Texto de la nota a agregar al hilo del ticket. |
| `status` | texto | No | Nuevo estado del ticket. Si se omite, el estado no cambia. Ver valores válidos abajo. |

> Solo es necesario indicar **uno** de los dos identificadores: `case_number` o `ticket_id`.

### Valores válidos para `status`

| Valor | Etiqueta |
|---|---|
| `abierto` | Abierto |
| `en_proceso` | En proceso |
| `resuelto` | Resuelto |
| `cerrado` | Cerrado |

***

## Ejemplos de solicitud

### Agregar una nota sin cambiar el estado

```bash
curl -X POST "https://panel.anunzi.net/api/ticket-update.php" \
  -H "Authorization: Bearer TU_TOKEN_AQUÍ" \
  -H "Content-Type: application/json" \
  -d '{
    "case_number": "CAS-000042",
    "note": "El cliente llamó nuevamente. Confirma que aún no recibió respuesta del equipo de logística. Solicita ser contactado antes del mediodía."
  }'
```

### Agregar una nota y cambiar el estado a "En proceso"

```bash
curl -X POST "https://panel.anunzi.net/api/ticket-update.php" \
  -H "Authorization: Bearer TU_TOKEN_AQUÍ" \
  -H "Content-Type: application/json" \
  -d '{
    "case_number": "CAS-000042",
    "note": "El cliente confirmó que recibió el reemplazo del producto. Cierra conformemente.",
    "status": "resuelto"
  }'
```

***

## Respuesta — 200 OK

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

| Campo | Descripción |
|---|---|
| `ok` | `true` si la nota se agregó correctamente. |
| `case_number` | Número de caso del ticket actualizado. |
| `ticket_id` | ID interno del ticket. |
| `status` | Estado final del ticket (puede ser el mismo que tenía si no se envió `status`). |

***

## Códigos de estado

| Código | Descripción |
|---|---|
| `200` | Nota agregada correctamente. |
| `400` | Faltan campos requeridos o el estado indicado es inválido. |
| `401` | Token ausente o inválido. |
| `403` | El agente no tiene un usuario asociado. |
| `404` | El ticket no existe o no pertenece a tu cuenta. |
| `500` | Error interno del servidor. |

***

## Comportamiento en el panel

Una vez procesada la solicitud:

* La nota aparece en el **hilo del ticket** atribuida al agente de IA (🤖).
* Si se cambió el estado, se agrega automáticamente un mensaje del sistema indicando el cambio.
* El owner recibe una **notificación in-app** con el número de caso y un extracto de la nota.
* El campo `updated_at` del ticket se actualiza con la hora de la nota.

***

## Flujo típico de seguimiento

```
Contacto llama nuevamente mencionando "mi caso CAS-000042"
    → Agente consulta GET /api/ticket-status.php?case_number=CAS-000042
    → Lee el estado actual y el último mensaje al contacto
    → Contacto da nueva información
    → Agente registra POST /api/ticket-update.php con la nota
    → El equipo de soporte ve la actualización en el panel
```