# Sesiones, inscripciones e interrupciones

## De la inscripción a los resultados

1. Crea el usuario (`POST /users`) e **inscríbelo** en un protocolo (`POST /user-protocols`). Una inscripción aún no tiene captura, y la misma persona puede inscribirse en el mismo protocolo más de una vez.
2. Pregunta qué **posición** toca (`GET /user-protocols/{userProtocolId}`). Su `protocol.interpreted` dice si el protocolo se interpreta: con `false`, como en Measurement, las capturas solo dan indicadores, el stream anuncia `results.ready` en lugar de `constellation.complete` y `POST /analyze` responde `409 PROTOCOL_NOT_ANALYSED`. `GET /catalog/protocols` y `GET /catalog/protocol_group` también lo traen. Hoy solo el Engine del entorno de pruebas devuelve `interpreted`.
3. Envía el primer lote de esa posición: Engine abre una **sesión** para ella. No hay id de sesión que guardar: la identifica el par `userProtocolId` + `protocolMechanicId`.
4. Cuando cada step tiene sus lotes y su `Final`, la sesión se completa y aparecen sus resultados.

Cada posición tiene como mucho una sesión abierta y una completada. Para medir otra vez la misma posición, vuelve a inscribir.

## Capturas abandonadas y reiniciadas

- Una sesión que no recibe ningún lote durante unos minutos se **abandona** (el umbral es un ajuste del entorno), y el stream en vivo lo avisa con `session.abandoned`.
- Un lote que llega tarde responde entonces `409 SESSION_ABANDONED`. Reinicia desde `step: 1` con `kpnfile.order: 1`. El mensaje te dice el umbral del entorno donde se capturó este ejemplo:

```json
{
  "status": 409,
  "body": {
    "code": 409,
    "reason": "SESSION_ABANDONED",
    "message": "Session abandoned after 300s of inactivity. This mechanic must be restarted from the beginning.",
    "restartRequired": true,
    "expected": {
      "step": 1,
      "kpnfile": {
        "order": 1,
        "status": "Partial"
      }
    }
  }
}
```

- Cada intento lleva su `captureId`. Un lote de reinicio (`step: 1`, `kpnfile.order: 1`) con un `captureId` **nuevo** cierra el intento que estaba abierto y empieza este; cualquier otro lote con un `captureId` distinto del del intento abierto responde `409 SESSION_ABANDONED`: es un lote tardío de un intento que ya sustituiste.
- Una posición que ya tiene una captura completada responde `409 POSITION_ALREADY_COMPLETED` a cualquier lote nuevo:

```json
{
  "status": 409,
  "body": {
    "code": 409,
    "reason": "POSITION_ALREADY_COMPLETED",
    "message": "This mechanic already has a completed session."
  }
}
```

- Para abandonar una captura a propósito: `POST /user-protocols/{userProtocolId}/{protocolMechanicId}/cancel`. Es idempotente: sin nada abierto responde `200` con `cancelled: false` y `reason: "no_open_session"`. Con `?captureId=` cierra la captura abierta solo si es esa; si hay otra abierta, no toca nada y responde `200` con `cancelled: false` y `reason: "other_capture_open"`. Sin `captureId`, cierra lo que esté abierto; con un token de captura (`POST /token/capture`), sin `captureId` se usa el del token, así que solo puede cerrar esa captura. `cancelled: false` con `reason: null` quiere decir que la captura se cerró sola en ese mismo momento (caducó o terminó): ya no queda nada que cancelar. Hoy solo el Engine del entorno de pruebas acepta `captureId`.
- Mientras otro intento retiene la posición (una captura en curso o una grabación pendiente de enviar), uno nuevo responde `409 POSITION_RESERVED`. Grabar ahora y enviar los frames después (`captureId`, `deferred` y `capturedAt` en `POST …/context`) se describe en la [referencia de la API](/docs/es/reference/). El aviso de fin de una grabación que ya se canceló, o que se rechazó por fuera de orden (`recordingEndedAt` sin `capturedAt`), responde `409 CAPTURE_CANCELLED`: no reserva nada, así que no reintentes.
- `GET /user-protocols/{userProtocolId}/{protocolMechanicId}/sessions` lista los intentos de una posición, del más antiguo al más reciente, con su `status` y su `captureId`. `deferred: true` marca una grabación retenida para procesarse después, y `receivingPackets: true` un intento que ya recibió al menos un lote: un intento diferido con `receivingPackets: false` es una reserva que aún espera sus frames. Son los mismos dos campos que el `holder` de un `409 POSITION_RESERVED`. Hoy solo el Engine del entorno de pruebas los devuelve.

## Cuando una posición no está disponible

Engine declara los relojes de las posiciones (ver [Protocolos](/docs/es/concepts/protocols/#las-posiciones-y-sus-relojes)) y los comprueba al abrir una sesión, nunca a mitad de ella. Que un fallo rechace la captura o solo quede registrado depende del entorno; cuando la rechaza, la respuesta es un `409`:

| `reason` | Qué hacer |
| --- | --- |
| `MECHANIC_NOT_YET_AVAILABLE` | Reintenta en `earliestAt` |
| `MECHANIC_EXPIRED` | Esa ventana se cerró para siempre: sigue con `goTo` |
| `MUST_START_AT_FIRST_POSITION` | Empieza por la posición de `goTo` |

`rule` nombra el reloj (`date_window`, `time_of_day`, `spacing`, `start_order`, `start_weekday`): úsalo en los logs, no para decidir qué hacer. `spacing` también puede venir de la separación mínima que Engine mantiene entre dos capturas del mismo protocolo, aunque la posición no declare ninguna.

**¿Cuándo se abre una posición?** En `GET /user-protocols/{userProtocolId}` cada sesión pendiente lleva un `window`. Con `hasTiming: true` y un reloj de franja horaria o de separación, `from` y `to` pueden llegar `null`, y no hay un `earliestAt` como el del `409`. Los datos para calcularlo sí llegan: `window.prevCaptureAt` (cuándo empezó la captura anterior) y `window.requiredGapSeconds` (la separación que pide Engine). La posición se abre en `prevCaptureAt` más `requiredGapSeconds`; si alguno es `null`, no hay separación que esperar.

**Sin calcularlo.** En el Engine del entorno de pruebas, `nextSessions` de `GET /user-protocols/{userProtocolId}/health` y de `GET /users/{externalId}/status` da a cada sesión pendiente un `window.earliestAt`: la misma hora que el `earliestAt` del `409 MECHANIC_NOT_YET_AVAILABLE`, y `null` si se puede capturar ya o ya no se podrá. En las mismas respuestas, `lastCompletedAt` dice cuándo empezó la última captura completada (cuándo se grabó, en una grabación), no cuándo acabó.

**¿Sin datos o aún procesando?** `GET /results/{userProtocolId}/{protocolMechanicId}` devuelve lo mismo en los dos casos: `200` con `rawResults` y `aggResults` vacíos, porque la posición aún no tiene sesión o su captura no se ha completado. Para distinguirlos, lee `GET …/sessions` de la posición: `sessions: []` significa que no se ha enviado nada; un intento con su `status` significa que va en camino. `GET /users/{externalId}/status` da el estado del protocolo entero (`capturing`, `awaiting_processing`…).

## Interrupciones y microintervenciones

Tras una captura completada, un contexto puede ofrecer una **microintervención**: una mecánica corta, como un ejercicio de respiración, que no es una posición del protocolo. La oferta es una **interrupción**, anclada a la captura que la disparó.

1. Te enteras por el stream en vivo (`interruption.offered`) o con `GET /user-protocols/{userProtocolId}/interruptions?status=offered`.
2. `GET /interruptions/{interruptionId}` devuelve qué mostrar: steps e instrucciones, con la misma forma que una posición.
3. Captúrala con `POST /interruptions/{interruptionId}/process-kpn-emo`. Una oferta que no se empieza caduca.
4. `GET /results/interruption/{interruptionId}` devuelve los resultados de la captura que disparó la oferta, en `origen` (la API escribe esta clave en español), y los de la microintervención, en `micro` (`null` si no se hizo).
5. Para abandonar una microintervención en curso: `POST /interruptions/{interruptionId}/cancel`. Es idempotente: si no hay nada abierto responde `200` con `cancelled: false`.

De una oferta, apóyate en `interruptionId`, `origin` y `message`. `observedValues`, `trigger` y `kpnWindow` son internos: no te apoyes en ellos. Que un contexto ofrezca microintervenciones depende de los contextos de tu organización.

> El SDK aún no gestiona microintervenciones: usa la API HTTP. Una oferta no se puede rechazar: si no la empiezas, caduca.
