# Servicio de procesado

**Preview**

> Preview: el procesado en servidor es el servicio de procesado de Neurologyca, lo único disponible hoy, activado para tu organización; alojarlo tú mismo llegará más adelante. El manifiesto puede cambiar. Úsalo solo con personas que hayan dado su consentimiento informado; lo cubre el Anexo de tratamiento de datos (DPA) que tu organización acepta con los Términos de DevLab.

## Qué hace el servicio

Descarga el vídeo de tu backend, repite la captura contra Engine con el mismo SDK (`replayRecording`, de `@neurologyca/capture/replay`), transcribe el audio de la grabación (entero, si el trabajo pide algún step) y solo pasa a Engine el texto de los steps que pide cada trabajo (`transcribeSteps`) y avisa a tu backend con un webhook firmado. No calcula indicadores: los calcula Engine. Tú nunca ejecutas `/replay`: lo ejecuta el servicio.

## Con nuestro servicio, o autoalojado

| Aspecto | Con nuestro servicio (disponible hoy) | Autoalojado (más adelante) |
| --- | --- | --- |
| Qué recibes | Nada que desplegar. Una credencial por organización: la URL del servicio (`PROCESSOR_URL`) y su IP de salida, en tu kit; la clave del procesador (`PROCESSOR_API_KEY`) y el secreto del webhook (`PROCESSOR_SECRET`), una sola pareja que la comparten todos los equipos: cualquier equipo activo la recibe en el zip de su starter de grabación con **Incluir mi key y las credenciales del procesador**, y el equipo admin de tu organización la revela y la rota en [Tu cuenta](/account) | El procesador (una imagen de contenedor) y su guía de alojamiento, para ejecutarlo en tus servidores. Más adelante, sin fechas |
| Qué expones | Tres rutas HTTPS públicas bajo `PUBLIC_BASE_URL`: el vídeo firmado, la URL del token y el webhook | Nada público: un listener interno, alcanzable solo desde la red del procesador |
| Qué guardas | Secretos distintos para las URLs firmadas y el webhook, un almacén de nonces por propósito y una tabla de trabajos | Lo mismo |
| Contexto, idioma, transcripción | Por trabajo: cada `submit` lleva el `taxonomy`, el `language` y los `transcribeSteps` de esa captura | Lo mismo; un procesador cuyo cliente los fija acepta los mismos valores o ninguno |

- **Limitar las tres rutas a la IP de salida del servicio es defensa en profundidad, no autenticación.** Esa IP es la misma para todas las organizaciones: otra puede hacer que el servicio llame a tus rutas desde ella. Lo que te protege es la firma HMAC con tu `PROCESSOR_SECRET`, que verifican `createWebhookHandler` y `createProcessorTokenHandler`, y la firma de la URL del vídeo. No te saltes ninguna, limites por IP o no.
- **`PUBLIC_BASE_URL` es el origen HTTPS público de tu backend.** El servicio acepta cualquier origen `https:` público y rechaza `http:`, `localhost`, las direcciones privadas y de loopback, las redirecciones y las URLs con credenciales (`E_DESTINATION_NOT_ALLOWED`). **Para probar en tu máquina**, el servicio no puede llamar a `localhost`: abre un túnel HTTPS público (por ejemplo cloudflared o ngrok), pon su origen en `PUBLIC_BASE_URL` y ciérralo al terminar; o despliega. El starter de grabación explica las dos cosas.
- **Si se filtra una credencial**, Neurologyca desactiva el acceso de tu organización al servicio (`E_CLIENT_DISABLED`; los trabajos en curso terminan), tu equipo admin rota en dos pasos —los valores nuevos quedan pendientes hasta que los despliegas y los activas— y el acceso se reactiva. Ningún webhook en curso se firma con un secreto que tu backend aún no tiene: [Si se filtra una credencial del procesador](/docs/es/access/keys/#si-se-filtra-una-credencial-del-procesador).

## Mandar una grabación

Desde el `onComplete` de tu receptor, firma una URL para el vídeo y manda el trabajo con los parámetros de esa captura. Guarda el `jobId`.

```js
// Your backend, handing a recording to Neurologyca's processing service (Node 20.3+). `url`, `apiKey` and the webhook
// secret come from your DevLab account; `publicBase` is your backend's public HTTPS origin (PUBLIC_BASE_URL), where the
// service calls the video, the token URL and the webhook. Never localhost: to test on your machine, use a public tunnel.
import { createProcessorClient } from '@neurologyca/capture-server'

/**
 * @param {object} o
 * @param {string} o.url the processing service's URL (PROCESSOR_URL, from your kit)
 * @param {string} o.apiKey your key for the service (PROCESSOR_API_KEY; never the Engine key)
 * @param {Pick<import('@neurologyca/capture-server').UploadReceiver, 'signedUrl' | 'manifest'>} o.receiver your upload receiver
 * @param {string} o.publicBase your backend's public origin for the service (PUBLIC_BASE_URL, HTTPS)
 * @param {string} o.engineBase your environment's Engine URL (ENGINE_BASE)
 */
export function processing(o) {
  const processor = createProcessorClient({ url: o.url, apiKey: o.apiKey })
  return {
    // Call it from your receiver's onComplete. Idempotent per captureId: the service answers with the same job.
    // `params` are THIS capture's: taxonomy.contextId (your page's) and language (the session's) are required by the
    // service; with a non-empty transcribeSteps the service transcribes the whole audio of the recording and passes to Engine only
    // the text of the listed step types (absent or [] = nothing is transcribed).
    async submit(
      /** @type {string} */ captureId,
      /** @type {{ taxonomy: import('@neurologyca/capture-server').ProcessorJobTaxonomy, language: string, transcribeSteps?: string[] }} */ params,
    ) {
      const videoUrl = await o.receiver.signedUrl(captureId, { baseUrl: `${o.publicBase}/media` }) // valid 24 h by default
      const manifest = /** @type {{ userProtocolId: string, protocolMechanicId: string }} */ (await o.receiver.manifest(captureId))
      const { jobId, status } = await processor.submit({
        videoUrl, manifest, engineBaseUrl: o.engineBase,
        tokenUrl: `${o.publicBase}/processor/token`, webhookUrl: `${o.publicBase}/processor/webhook`,
        taxonomy: params.taxonomy, language: params.language, transcribeSteps: params.transcribeSteps ?? [],
      })
      // Save all of it next to the captureId: the token URL compares the pair with the JOB's, because the upload
      // (manifest included) is deleted at `interpreting` while the job still runs.
      return { jobId, status, userProtocolId: manifest.userProtocolId, protocolMechanicId: manifest.protocolMechanicId }
    },
    job: (/** @type {string} */ jobId) => processor.getJob(jobId), // poll when a webhook does not arrive
  }
}
```

Con nuestro servicio, `engineBaseUrl` tiene que ser un Engine que el servicio admite (el de tu cuenta): cualquier otro se rechaza en el `submit`. Cada `submit` lleva los parámetros de ESA captura: `taxonomy` (`contextId` obligatorio, `hciId` y `subcontextId` opcionales; el mismo `taxonomy.contextId` que la configuración de tu página), `language` (el idioma de la sesión, por ejemplo `'es'`), `transcribeSteps` (los tipos de step que se transcriben; `[]` es siempre ninguno; ausente es ninguno con el servicio alojado; con un servicio propio, los steps que su propia configuración fija para tu cliente) y, si quieres, `interimWebhook`. El servicio exige `taxonomy.contextId` y `language`: sin ellos, `400 E_BAD_REQUEST`. `createProcessorClient` los valida antes de enviar (un valor mal formado es un `TypeError` en la llamada) y solo envía los que pasas. Hacen falta `capture-server` 0.13.0 o posterior.

El servicio solo acepta MP4 con H.264, que es lo que produce el cliente de grabación. Si rechaza la llamada, `submit` rechaza con un `ProcessorError` (`code`, `status`, `retryAfterMs`); cada llamada se rinde a los 30 s.

## La URL del token

Monta la URL del token y el webhook antes de cualquier body parser: los dos verifican la firma sobre el cuerpo tal cual llega. El servicio le pide a tu backend un token de Engine, firmado, con el par de la captura y su `jobId`. `createProcessorTokenHandler` verifica la firma; tu `authorize` decide si entregar un token: solo si el `jobId` es el que devolvió `submit`, el trabajo sigue en curso (`interpreting` incluido) y el par es el que guardaste de ese trabajo en el `submit`. Nunca lo compares con `receiver.manifest()`: tras el aviso `interpreting` la subida, manifiesto incluido, ya está borrada, el servicio sigue renovando su token mientras espera la interpretación, y una negativa acaba esa espera en un `timeout` falso. Por defecto, el token es el token de developer de la organización, no uno limitado a esa captura: `authorize` limita cuándo se emite, nunca qué puede hacer. Es una condición para producción.

Desde `capture-server` 0.10.0 puedes entregar en su lugar un token limitado a la captura: `captureToken: { baseUrl }` en `createProcessorTokenHandler`, con `baseUrl` la URL de Engine de tu entorno (`ENGINE_BASE`). El handler se lo pide a Engine con `POST /token/capture`, para exactamente el par y el `captureId` firmados, autenticado con tus `tokens` (el token de developer nunca sale de tu backend), y entrega solo ese token. Dura 30 minutos (el servicio lo vuelve a pedir cuando caduca) y solo llega a la ingesta de esa captura, a su plan y a su stream. Está apagado por defecto: hoy solo el Engine del entorno de pruebas tiene esa ruta; contra un Engine que no la tiene, el handler responde un 502 que ve tu `onError`, nunca un fallo silencioso. Con él encendido, el replay no llama a ningún `/analyze*` (el token no puede, y el servicio repite con `awaitInterpretation: false`), así que nunca avisa `analysis.out-of-token-scope`: Engine hace la interpretación que pidió el `Final` de cierre, y tú la lees después con tu propia credencial. Engine limita además las peticiones de ese token por captura y por minuto; desde `@neurologyca/capture` 0.37.0 el replay espera el `Retry-After` y sigue, más lento, con el aviso `transport.rate-limited` (un procesador con una versión anterior hace fallar el trabajo). Qué puede y qué no puede hacer ese token: [Un token para una sola captura](/docs/es/start/authentication/#un-token-para-una-sola-captura). El modo diferido de DevLab también puede entregarlo: una opción de su servidor, apagada por defecto, solo contra el Engine del entorno de pruebas.

## El webhook

El servicio avisa a tu backend cuando termina el trabajo (`succeeded` o `failed`). El contrato (campos firmados, nonces, al menos una vez, idempotencia, `getJob` como respaldo): [Resultados en tu backend](/docs/es/sdk/results-backend/#el-webhook-del-diferido-como-contrato).

Desde `capture-server` 0.11.0 hay además un aviso intermedio, `status: 'interpreting'`, firmado como los demás, con `report` y `processor` a `null` y sin campos de fallo. El servicio lo manda mientras `interimWebhook` está encendido: con nuestro servicio, por defecto (apágalo por trabajo con `interimWebhook: false` en `submit`). Un receptor 0.10.0 le responde 400. No es terminal:

- **Borra el vídeo en `interpreting` o en `succeeded`, lo que llegue antes**, y no cierres el trabajo hasta el `succeeded`. Sin el aviso (apagado, o perdido) el vídeo se queda en tu receptor toda la espera, hasta 300 s más.
- **Mira `interpreting` lo primero.** Un `onEvent` que trata como fallo todo lo que no es `succeeded` cierra el trabajo: se deniega la renovación del token, la espera acaba en un `timeout` falso y el vídeo no se borra nunca. Actualiza el manejador antes de desplegar contra nuestro servicio, donde `interimWebhook` está encendido por defecto.
- **Un `interpreting` que llega después del terminal** (una entrega reintentada) no vuelve a abrir nada.

## La interpretación

Desde `capture-server` 0.11.0 el trabajo espera la interpretación de Engine. Si el protocolo se interpreta, el último `Final` la pide y Engine la hace por su cuenta (la guarda y la anuncia con `constellation.complete`); entretanto el trabajo está en `interpreting`, hasta 300 s por defecto. Cuenta como en curso, `getJob` lo devuelve así y nunca acaba en `failed`. `succeeded` llega cuando la interpretación está lista o cuando consta que no llegará, y su `interpretation` (en el webhook y en `getJob`) dice cómo acabó el análisis. **El trabajo acaba `succeeded` valga lo que valga**: los indicadores están en `/results`. El texto nunca viaja en el webhook: léelo con tu credencial (`client.analyze()` o `POST /analyze`).

| `interpretation` | Qué significa | Qué hacer |
| --- | --- | --- |
| `ready` | El análisis salió completo | Léela ya: sale de la caché (`from_cache: true`) y no vuelve a costar tokens. Medido el 2026-10-13: 726 ms |
| `degraded` | Llegó, pero el análisis salió degradado | No hay llamada que lea el análisis guardado sin rehacerlo: cada `/analyze` lo regenera (decenas de segundos, hasta unos dos minutos, y tokens de LLM) y devuelve el nuevo o, si sale peor, el guardado. Pídela una vez si la necesitas, nunca en bucle |
| `failed` | Llegó, pero el análisis falló | Lo mismo que `degraded` |
| `timeout` | No llegó el evento dentro de la espera | No es un fallo. Se puede pedir, a costa de tokens del LLM si no está guardada: Engine la genera en ese momento |
| `unknown` | Se pidió y no se sabe cómo acabó | Se puede pedir, a costa de tokens del LLM. Si `processor.interpretation.reconnects` es un número y el `outcome` no es `already-processed`, el evento llegó sin un estado legible: el análisis está guardado y `/analyze` lo sirve de la caché, como con `ready`. `reconnects: null` es un reinicio del servicio durante la espera; `outcome: 'already-processed'`, una sesión procesada por un trabajo anterior |
| `not-requested` | No se pidió (`triggerAnalysis: false`, un protocolo que no se interpreta), o Engine se la saltó porque le faltó una entrada (por ejemplo, la transcripción de una respuesta que acabó sin voz) | No hay nada que pedir; en el segundo caso, graba otra vez con voz en cada respuesta |

El trabajo trae la espera en `processor.interpretation` (`e.processor` en el webhook, `job.processor` en `getJob`; no en `report`): `{ outcome, waitedMs, reconnects, lastClose }`. Por qué importa esperar, medido por DevLab el 2026-10-13: pedida al terminar la repetición, `from_cache: false` (se generó otra y se pagó dos veces); pedida 300 s después, `from_cache: true` las dos veces.

> **Orden del despliegue.** El servicio que espera y `capture-server` 0.11.0 van juntos, y `capture-server` primero. Un `createProcessorClient` 0.10.0 rechaza con `E_PROCESSOR_PROTOCOL` toda respuesta de `submit` y `getJob` que diga `interpreting`, durante toda la espera, aunque `interimWebhook` esté apagado.

Con el token de captura (`captureToken`) aquí no cambia nada: el servicio repite con `awaitInterpretation: false` y no llama a ningún `/analyze*` (fuera del alcance de ese token), así que `analysis.out-of-token-scope` no aparece. La sesión acaba `complete`, y la interpretación es la que Engine hace por su cuenta.

## Códigos de error

Del catálogo de errores del servicio. «/retry» dice si el trabajo se puede reintentar; «Reserva», si el servicio libera la reserva de la persona en Engine.

| Código | Cuándo | /retry | Reserva | Qué hace tu backend |
| --- | --- | --- | --- | --- |
| Errores al llamar (`ProcessorError`; `submit` o `retry` rechazan con ellos) | `E_UNAUTHORIZED` (401): sin credencial o errónea. `E_CLIENT_DISABLED` (403): el acceso de tu organización al servicio está desactivado; `submit` y `retry` se rechazan, `getJob` sigue respondiendo y los trabajos en curso terminan. `E_BAD_REQUEST` (400; 413 si pasa de 4 MiB; con nuestro servicio, también un trabajo sin `taxonomy.contextId` o sin `language`), `E_DESTINATION_NOT_ALLOWED` (400, las URLs del trabajo quedan fuera de las reglas del servicio, por ejemplo un `PUBLIC_BASE_URL` en `http:`), `E_JOB_PARAMS_CONFLICT` (400, autoalojado: el cliente del procesador fija `taxonomy`, `language`, `transcribeSteps` o `interimWebhook` y el trabajo trae otro valor), `E_CAPTURE_ID_CONFLICT` (409, el `captureId` es de otro cliente), `E_NOT_RETRYABLE` (409, `retry` sobre un trabajo que no está `failed` o no es reintentable). `E_STARTING` y `E_STOPPING` (503). `E_PURGE_PENDING` (503, `Retry-After: 5`, `retry` mientras se borran los ficheros del trabajo). `E_PROCESSOR_HTTP` (una respuesta de error sin `code`) y `E_PROCESSOR_PROTOCOL` (un 2xx que el cliente no entiende), del cliente | No aplica | No aplica | Revisa la key del servicio (`E_UNAUTHORIZED`). Tras una filtración, rota en dos pasos y espera a que se reactive; si no, habla con Neurologyca (`E_CLIENT_DISABLED`). Defecto tuyo, no reintentes (`E_BAD_REQUEST`: manda `taxonomy` y `language` en cada `submit`; `E_JOB_PARAMS_CONFLICT`: manda los valores del cliente, o ninguno; `E_DESTINATION_NOT_ALLOWED`: corrige la configuración y vuelve a llamar a `submit`; `E_CAPTURE_ID_CONFLICT`, `E_NOT_RETRYABLE`). Reintenta más tarde (`E_STARTING`, `E_STOPPING`, `E_PROCESSOR_HTTP`, `E_PROCESSOR_PROTOCOL`); reintenta tras 5 s (`E_PURGE_PENDING`) |
| `E_REDIRECT_REFUSED`, `E_DESTINATION_NOT_ALLOWED`, `E_VIDEO_TOO_LARGE` | Se rechazó la descarga o la URL del token: una redirección, una dirección fuera de las reglas del servicio (con nuestro servicio, todo lo que no sea un origen HTTPS público), o un vídeo por encima del tope de tamaño del servicio | Sí, cuando falla la descarga o la URL del token (al llamar, `E_DESTINATION_NOT_ALLOWED` es un error de la llamada: corrígelo y vuelve a llamar a `submit`) | No | Corrige la configuración (un origen HTTPS público en `PUBLIC_BASE_URL`, nunca `localhost`) o manda una `videoUrl` nueva, y luego reintenta. No es un reintento a ciegas |
| `E_VIDEO_URL_EXPIRED` | La descarga respondió 401 o 403 | Sí, con una `videoUrl` nueva | No | Reintenta con una URL nueva |
| `E_DOWNLOAD_FAILED` | Red, 5xx, 408 o 429 tras 3 intentos | Sí | No | Reintenta más tarde |
| `E_DOWNLOAD_FAILED` (otro 4xx) | Tu ruta del vídeo respondió otro 4xx, por ejemplo un 404 porque `receiver.mediaHandler` no está montado en `/media/<captureId>/video` | No | Sí | Corrige la ruta del vídeo para las siguientes grabaciones; esta captura no se recupera (volver a enviarla devuelve el mismo trabajo fallido) |
| `E_QUEUE_FULL` | Más de 50 trabajos sin terminar del cliente | No aplica (se rechaza la llamada) | No | Reintenta `submit` más tarde con una espera creciente: `retryAfterMs` llega vacío (el servicio no manda `Retry-After`) |
| `E_MANIFEST_INVALID` | El manifiesto está mal formado o no cuadra con el vídeo | No | Sí | No reintentes |
| `E_MEDIA_UNSUPPORTED` | El vídeo no es MP4/H.264 | No | Sí | No reintentes |
| `E_MEDIA_INVALID`, `E_ROTATION_UNRESOLVED` | El fichero no se puede leer como vídeo, o no se resuelve su rotación | No | Sí | No reintentes |
| `E_NO_FACE_PREROLL`, `E_EMPTY_STEP` | Sin cara en los primeros segundos, o un step sin frames con cara | No | Sí | No reintentes; graba de nuevo con la persona |
| `E_TOKEN_FAILED` | La URL del token no respondió bien tras 3 intentos, o al primer intento si responde un 4xx | Sí | No | Revisa tu URL del token; reintenta |
| `E_POSITION_BUSY`, `E_OWN_ATTEMPT_PROCESSING` | La posición está ocupada, o el intento propio de la persona sigue procesándose, tras las esperas del propio servicio | Sí | No | Reintenta más tarde |
| `E_ALREADY_PROCESSED` | No es un fallo: el intento ya estaba completado en Engine y el trabajo acaba `succeeded` | No aplica | No | No es un fallo: trátalo como éxito |
| `E_CAPTURE_DISCARDED`, `E_CAPTURE_OUT_OF_ORDER` | La persona descartó la grabación, o ya hay una sesión posterior calculada | No | Sí | No reintentes; borra el vídeo |
| `E_USER_BLOCKED`, `E_USER_GONE` | Engine respondió 403 o 404 para el usuario o la posición | No | Sí | No reintentes |
| `E_POSITION_COMPLETED`, `E_CONFLICT` | Otra captura completó la posición, u otro conflicto de ventana | No | Sí | No reintentes |
| `E_SESSION_ABANDONED`, `E_KODEC`, `E_STT_FAILED` | Engine abandonó la sesión, o falló el análisis o la transcripción del servicio | Sí | No | Reintenta |
| `E_GPU_UNAVAILABLE`, `E_CHROME_SANDBOX` | El anfitrión del servicio no puede ejecutar el trabajo | Sí | No | Reintenta más tarde; es cosa del servicio |
| `E_PROCESSOR_HANG`, `E_JOB_TIMEOUT`, `E_PROCESSOR_RESTARTED` | 60 s sin latido, 120 minutos en marcha, o el servicio se reinició | Sí | No | Reintenta |
| `E_INTERNAL` | Un fallo inesperado | Sí | No | Reintenta; repórtalo si se repite |
| Cualquier otro código | El servicio tiene más códigos que esta tabla (`errorCode` es un texto) | El `retryable` del trabajo | | Reintenta solo si el trabajo dice `retryable: true`; si no, ciérralo |

Si ves `E_PROCESSOR_AUTH`, `E_PROCESSOR_UNAVAILABLE` o `E_PROCESSOR_REJECTED` en el playground de DevLab, son la forma propia de DevLab de mostrar «subido pero no entregado al servicio»: del lado de la subida es `E_UPLOAD_NOT_NOTIFIED` ([Diferido](/docs/es/sdk/deferred/)), y del lado del submit, uno de los códigos `ProcessorError` de arriba.

Un fallo que no vas a reintentar cierra el trabajo: deja de dar tokens por él en tu URL del token, y conserva o borra la grabación según tu retención. Un trabajo que falla con `E_REDIRECT_REFUSED`, `E_DESTINATION_NOT_ALLOWED` o `E_VIDEO_TOO_LARGE` (los tres errores de configuración) conserva la reserva de la persona hasta que Engine la caduca (72 horas después del aviso de fin).

## Measurement en diferido

Funciona desde 0.27.0: `triggerAnalysis: false` viaja en el manifiesto y el servicio no llama a `/analyze`. De punta a punta, el trabajo acaba `succeeded` y Engine guarda todos los frames que manda la repetición. Que transcriba depende del trabajo: con la transcripción apagada (`transcribeSteps: []`) el servicio no transcribe nada; con la transcripción activada, pide `measurement_free` en `transcribeSteps` (el único step de Measurement no es de habla, así que ninguna otra lista lo incluye) y su texto llega a Engine. Desde la 0.29.0, cuando Engine dice `interpreted: false`, el cliente de grabación reserva sin taxonomía y escribe `interpreted: false` en el manifiesto, y el replay del servicio no envía taxonomía ni pide análisis sin que pases nada. Producción aún no devuelve `interpreted`: allí, mantén `triggerAnalysis: false` en la captura.
