> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need.

# Contrato de handoff

Este documento separa el contrato técnico entre workflows del contrato de
entrega a una persona. Es una referencia de diseño: los campos, permisos y
response nodes deben aprobarse antes de usarla para una integración.

## Tipos de handoff

| Tipo | Origen | Destino | Resultado |
|---|---|---|---|
| Route handoff | Dispatcher | Especialista | Workflow hijo que continúa la conversación. |
| Human handoff de voz | Especialista de voz | Connect y cola humana | Transferencia de la llamada y continuidad de atención. |
| Human handoff de texto | Especialista de texto | TeLeo | Ticket y mensajes bidireccionales. |
| De-escalado | TeLeo o especialista | Workflow/bot | La conversación vuelve al bot cuando el contrato lo permite. |

## Envelope mínimo

| Campo | Route handoff | Human handoff | Regla |
|---|:---:|:---:|---|
| `channel` / trigger | Sí | Sí | Conserva voz/texto y evita cruces. |
| `intent` / `subintent` | Sí | Sí | Catálogo cerrado del dominio. |
| `confidence` | Sí | Opcional | Indica cuándo aplicar fallback. |
| `summary` | Sí | Sí | Breve, saneado y sin secretos. |
| `session_id` / `run_id` | Sí | Sí | Une app, workflow, ticket y backend. |
| `parent_run_id` | Sí, cuando hay child | Sí, cuando se conserva el árbol | Evita atribuir el cierre al run hijo equivocado. |
| `environment` | Sí | Sí | Impide cruzar perfiles. |
| Identificador de caso | Si ya existe | Si el destino lo necesita | Nunca se inventa desde el texto. |
| Estado de autenticación | Sí | Sí | Solo estado; nunca el token. |
| Resultado parcial | Opcional | Sí | Describe qué se confirmó y qué queda pendiente. |
| Transcript completo | No por defecto | Solo si el contrato lo exige | Minimizar y respetar retención. |
| DNI/IBAN/teléfono completo | No por defecto | Solo mínimo autorizado | No copiar datos innecesarios. |
| API key, token, cookie o secreto | Nunca | Nunca | Debe permanecer en el servicio que lo custodia. |

## Respuesta esperada

Un workflow hijo debe devolver un resultado estructurado y no una explicación
libre que el parent tenga que interpretar:

```text
status          = COMPLETED | RETURN_TO_TRIAGE | ESCALATED | FAILED
summary         = resumen breve saneado
handoff_status  = opcional
error_code      = categoría técnica controlada
next_action     = catálogo aprobado
```

El response node debe estar declarado en el workflow destino y todos los caminos
terminales deben exponer el mismo contrato. Un timeout o una respuesta vacía se
trata como `FAILED`; el parent no debe continuar con datos incompletos.

## Reglas por destino

### TeLeo

La ingesta debe ser idempotente por el identificador estable de la sesión. El
ticket inicial puede incluir histórico, resumen, cliente y contexto Naturgy
minimizado. Los mensajes del cliente se añaden al ticket; las respuestas
públicas del agente vuelven por webhook. Las notas privadas no cruzan al
cliente.

El ciclo de TeLeo distingue cierre permanente, de-escalado, Pendientes, cola y
reapertura. El sistema debe conservar el vínculo ticket ↔ sesión y hacer
observable un fallo de webhook.

### Connect

La transferencia de voz debe seguir el contrato de Connect: el especialista
indica la acción y libera su tramo; Connect decide la cola o destino. El
payload conserva motivo, resumen, correlación y estado de autenticación, sin
usar un SIP REFER como sustituto de la lógica de transferencia acordada.

### ATC modular

El parent callable de ATC debe poder llamar Auth, Triaje, especialistas y
Post-call como children. Cada child debe ser callable, tener response node y
recibir solo sus parámetros declarados. El contrato debe conservar
`parent_run_id`, `parent_version_id`, `parent_environment` y correlación porque
los campos `current.*` del child pertenecen al child.

## Idempotencia y errores

| Situación | Comportamiento |
|---|---|
| Creación repetida del ticket | Devolver el ticket existente; no crear otra atención. |
| Mensaje sin confirmación | Consultar estado antes de reenviar; evitar duplicados. |
| Timeout del child | Marcar `FAILED`, impedir continuación silenciosa y aplicar fallback. |
| Falla del webhook | Mantener el mensaje guardado, registrar el fallo y reintentar según contrato. |
| Destino no disponible | Respuesta de no disponibilidad o escalado aprobado; no simular éxito. |
| Entorno incorrecto | Rechazar o bloquear antes de ejecutar una mutación. |
| Estado de negocio ambiguo | No afirmar resultado; pedir comprobación al backend owner. |

## Propiedad y aceptación

| Parte | Owner de la decisión |
|---|---|
| Campos y target de Workflow Function | HappyRobot + owner del workflow |
| Creación y estado de CI/CG | Salesforce/Mulesoft/Carolina según canal |
| Transferencia de voz | Connect y owner de telefonía |
| Ticket y consola humana | TeLeo y owner de atención escrita |
| Identidad y autorización de negocio | Omega y backend owner |
| Retención, acceso y auditoría | Naturgy, Seguridad/SiP y cada plataforma |
| Criterio UAT/E2E | Producto, Negocio y owners técnicos |

El contrato queda pendiente mientras falte cualquiera de estos owners, el
fallback o la evidencia del entorno. La [evidencia UAT](/use-cases/super-app/reference/evidence)
debe registrar qué campos y resultados se comprobaron.