> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestionar tickets con MCP

> Descubre trabajo, revisa evidencia, elige un responsable humano y verifica cada escritura.

Conecta un cliente MCP autorizado a:

```text theme={null}
https://platform-api.visitoai.com/m2m/v1/mcp
```

Consulta la [guía de conexión MCP](https://docs.visitoai.com/es/product-guides/getting-started/visito-mcp.md). Una autorización OAuth expone solo las herramientas permitidas. Si falta una herramienta, puede faltar su scope. Las autorizaciones existentes no se amplían automáticamente. La [matriz de operaciones](https://docs.visitoai.com/es/api-docs/tickets.md#rutas-herramientas-y-permisos) incluye las 18 herramientas de Tickets, Escalaciones y Comercio con sus permisos.

## Correspondencia de entradas REST y MCP

Las herramientas usan los mismos servicios de dominio y proyecciones de respuesta que REST:

| Entrada REST | Argumento MCP |
| - | - |
| Parámetro de ruta, como `ticketId` o `saleId` | Argumento del nivel superior con el mismo nombre |
| Parámetro de consulta, como `includeCommerce`, `status`, `cursor` | Argumento del nivel superior con el mismo nombre |
| Cuerpo JSON | Objeto bajo `input` |
| Cabecera `Idempotency-Key` | `idempotencyKey` en el nivel superior |

Los JSON siguientes son argumentos, no sobres JSON-RPC. El resultado estructurado contiene `statusCode` y `result`; el ticket o listado está dentro de `structuredContent.result`. No confundas la envoltura del transporte con el objeto de dominio. La Referencia de API documenta el esquema de respuesta.

## Descubrir → inspeccionar → asignar → iniciar → anotar → resolver → verificar

**1. Descubre toda la cola relevante**

Llama a `list_tickets`. Incluye Comercio explícitamente y sigue todos los cursores restantes con los mismos filtros.

```json theme={null}
{"includeCommerce":true,"status":"pending","owner":"unassigned","limit":25}
```

**2. Inspecciona el elemento y su evidencia**

Llama a `get_ticket` con `{"ticketId":"YOUR_TICKET_ID"}` y a `list_ticket_events` con el ID y `limit`. Comprueba tipo, origen, estado, revisión, responsable, acciones y disponibilidad del contexto.

Lee conversación, mensajes guardados, política de handoff, recibos de acciones y entrega con sus herramientas y permisos. Los títulos de fuentes no sustituyen esas lecturas. La evidencia de compra requiere `commerce:sales:read`. Indica explícitamente el contexto no disponible o denegado.

**3. Selecciona una persona responsable**

Busca un miembro activo con `list_assignable_operators`. `assign_ticket` recibe:

```json theme={null}
{"ticketId":"YOUR_TICKET_ID","input":{"revision":0,"operatorId":"YOUR_HUMAN_OPERATOR_ID"}}
```

Usa `assign_escalation` para una escalación; también cambia al responsable de la conversación. La credencial/autorización sigue siendo el actor de auditoría, no el responsable humano.

**4. Inicia explícitamente**

Llama a `start_ticket` o `start_escalation` con la revisión devuelta más reciente:

```json theme={null}
{"ticketId":"YOUR_TICKET_ID","input":{"revision":1}}
```

Un agente no puede iniciar un elemento sin asignar. Leer, asignar o responder no implica empezar trabajo.

**5. Registra evidencia y progreso**

Llama a `add_ticket_note` o `add_escalation_note`:

```json theme={null}
{"ticketId":"YOUR_TICKET_ID","input":{"revision":2,"note":"Front desk verified luggage storage until 6 pm. Reference: desk log DEMO-204."}}
```

Las notas son internas. Los mensajes al cliente usan herramientas y autorización de envío independientes.

**6. Completa el flujo correcto**

Para trabajo manual general, usa `resolve_ticket` al completarlo o `cancel_ticket` si deja de ser necesario. Para atención humana, usa `resolve_escalation` tras considerar que la IA podría volver a responder bajo los ajustes restantes.

```json theme={null}
{"ticketId":"YOUR_TICKET_ID","input":{"revision":3,"note":"Verified the requested information and completed the work."}}
```

Comercio requiere un resultado autoritativo de la compra. Usa sus [herramientas](https://docs.visitoai.com/es/api-docs/tickets/commerce.md); resolver/cancelar genéricamente no puede cerrarlo.

**7. Vuelve a leer**

Llama a `get_ticket`. Verifica el ID exacto, nueva revisión, estado esperado e historial. Revisa política o entrega por separado cuando corresponda. Las revisiones anteriores ilustran un elemento nuevo sin escrituras intermedias; usa siempre las reales.

## Crear trabajo o iniciar un handoff

`create_ticket` requiere conversación guardada, título y clave de creación:

```json theme={null}
{"idempotencyKey":"luggage-storage-2026-10-16-01","input":{"conversationId":"YOUR_CONVERSATION_ID","title":"Confirm luggage storage after checkout","description":"Verify availability with the front desk."}}
```

`create_escalation` también exige conversación y título, con `conversations:handoffs:create`. Pausa inmediatamente la IA por la ruta canónica de handoff. No sintetiza mensajes del huésped. Asigna una persona por separado e inicia el trabajo.

`update_ticket` edita un ticket general abierto con `ticketId` e `input` que contenga la `revision` actual y al menos un campo editable. No hay herramienta para editar títulos de escalaciones ni reabrir elementos en esta versión.

## Reintentos seguros

* Ante revisión obsoleta, vuelve a leer y reconsidera; no incrementes el número localmente ni repitas a ciegas.
* Ante creación incierta, conserva clave y entrada originales. Inspecciona el `requestId` devuelto con `get_ticket_request_status` antes de repetir.
* Procesando o requiriendo reconciliación no confirma éxito. Inspecciona cualquier ticket y su propietario; no crees otro handoff sustituto.
* Usa otra clave para una intención nueva, no para sortear un intento incierto.
* Los comandos de Comercio tienen `sourceVersion`, idempotencia y verificación propias.
* El acceso revocado detiene lecturas, escrituras y entregas autorizadas. Obtén una autorización explícita sin suplantar a un miembro del equipo.

Las aprobaciones del Agente integrado siguen siendo obligatorias donde se usan. La visibilidad MCP no omite aprobaciones ni elegibilidad de Comercio.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.