Sesiones, inscripciones e interrupciones
Cómo se abre, se cierra, se abandona y se reinicia una captura, cómo responden los relojes de las posiciones y cómo se ofrecen las microintervenciones.
De la inscripción a los resultados
Sección titulada «De la inscripción a los resultados»- 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. - Pregunta qué posición toca (
GET /user-protocols/{userProtocolId}). Suprotocol.interpreteddice si el protocolo se interpreta: confalse, como en Measurement, las capturas solo dan indicadores, el stream anunciaresults.readyen lugar deconstellation.completeyPOST /analyzeresponde409 PROTOCOL_NOT_ANALYSED.GET /catalog/protocolsyGET /catalog/protocol_grouptambién lo traen. Hoy solo el Engine del entorno de pruebas devuelveinterpreted. - 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. - 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
Sección titulada «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 desdestep: 1conkpnfile.order: 1. El mensaje te dice el umbral del entorno donde se capturó este ejemplo:
{ "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 uncaptureIdnuevo cierra el intento que estaba abierto y empieza este; cualquier otro lote con uncaptureIddistinto del del intento abierto responde409 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_COMPLETEDa cualquier lote nuevo:
{ "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 responde200concancelled: falseyreason: "no_open_session". Con?captureId=cierra la captura abierta solo si es esa; si hay otra abierta, no toca nada y responde200concancelled: falseyreason: "other_capture_open". SincaptureId, cierra lo que esté abierto; con un token de captura (POST /token/capture), sincaptureIdse usa el del token, así que solo puede cerrar esa captura.cancelled: falseconreason: nullquiere 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 aceptacaptureId. - 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,deferredycapturedAtenPOST …/context) se describe en la referencia de la API. El aviso de fin de una grabación que ya se canceló, o que se rechazó por fuera de orden (recordingEndedAtsincapturedAt), responde409 CAPTURE_CANCELLED: no reserva nada, así que no reintentes. GET /user-protocols/{userProtocolId}/{protocolMechanicId}/sessionslista los intentos de una posición, del más antiguo al más reciente, con sustatusy sucaptureId.deferred: truemarca una grabación retenida para procesarse después, yreceivingPackets: trueun intento que ya recibió al menos un lote: un intento diferido conreceivingPackets: falsees una reserva que aún espera sus frames. Son los mismos dos campos que elholderde un409 POSITION_RESERVED. Hoy solo el Engine del entorno de pruebas los devuelve.
Cuando una posición no está disponible
Sección titulada «Cuando una posición no está disponible»Engine declara los relojes de las posiciones (ver Protocolos) 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
Sección titulada «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ó.
- Te enteras por el stream en vivo (
interruption.offered) o conGET /user-protocols/{userProtocolId}/interruptions?status=offered. GET /interruptions/{interruptionId}devuelve qué mostrar: steps e instrucciones, con la misma forma que una posición.- Captúrala con
POST /interruptions/{interruptionId}/process-kpn-emo. Una oferta que no se empieza caduca. GET /results/interruption/{interruptionId}devuelve los resultados de la captura que disparó la oferta, enorigen(la API escribe esta clave en español), y los de la microintervención, enmicro(nullsi no se hizo).- Para abandonar una microintervención en curso:
POST /interruptions/{interruptionId}/cancel. Es idempotente: si no hay nada abierto responde200concancelled: 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.