Has creado un trabajo de aprovisionamiento y has recibido un ID de trabajo pjb_ y un ID de motor eng_ en milisegundos. El motor ya se puede usar, pero aún se está completando: un agente de IA está rastreando tus fuentes y escribiendo voces de marca, términos del glosario e instrucciones en él. Mientras eso ocurre, quieres mostrar el progreso: una línea del tipo "Rastreando tu guía de estilo… configurando el motor… listo", como haría un asistente de instalación, en lugar de un spinner que no dice nada.
El WebSocket te da exactamente ese flujo. Te conectas al trabajo y el servidor te envía una instantánea del estado actual y, después, un evento provisioning.progress cada vez que el flujo de trabajo pasa a una nueva fase. Y como el servidor envía el estado actual al conectar y cierra un trabajo terminado justo después, puedes conectarte en cualquier momento, incluso después de que termine: no hay ninguna ventana que tengas que acertar.
GET /jobs/provisioning/:jobId/wsEl jobId es el valor pjb_ de la llamada de creación. ¿No conoces aún el aprovisionamiento asíncrono? Empieza por la Descripción general para hacerte una idea del modelo mental.
En esta página
- Tipos de mensajes
- Instantánea al conectar
- Eventos de progreso
- Conectarte después de que termine el trabajo
- Integrarlo en tu interfaz
- Mantén tu clave de API en el servidor
Tipos de mensajes#
Hay dos tipos de mensajes que viajan por el socket. El primero llega una sola vez, al conectar; el segundo llega de forma recurrente, a medida que avanza el trabajo.
| Tipo | Cuándo | Campos clave |
|---|---|---|
provisioning.snapshot | En la conexión inicial | jobId, status, errorMessage |
provisioning.progress | Cuando cada paso del flujo de trabajo empieza o termina | jobId, step, detail |
Esto es un flujo de estado, no un flujo de resultados: te dice en qué punto está el trabajo y si ha fallado, no qué registros ha creado la IA. El resumen de todo lo aprovisionado —los ID de voz de marca, glosario e instrucciones— llega por separado, en el webhook de finalización o consultando el trabajo una vez haya terminado. Usa el socket para la barra de progreso; recurre al webhook para la carga útil.
Instantánea al conectar#
En cuanto te conectas, el servidor lee el estado actual del trabajo en la base de datos y lo envía. No hace falta que llegue antes ningún evento de progreso: la instantánea se basta por sí sola.
{
"type": "provisioning.snapshot",
"jobId": "pjb_A1b2C3d4E5f6G7h8",
"status": "in_progress",
"errorMessage": null
}| Campo | Descripción |
|---|---|
status | in_progress, completed o failed. |
errorMessage | La descripción del error cuando status es failed; en caso contrario, null. |
La instantánea es el único mensaje que tienes garantizado recibir. Si el trabajo sigue en marcha, después recibirás eventos de progreso; si el trabajo ya ha terminado, recibirás la instantánea y nada más (consulta más abajo).
Eventos de progreso#
A medida que se ejecuta el flujo de trabajo, el servidor emite un evento provisioning.progress cada vez que entra en una nueva fase. Cada evento indica el step y lleva un detail legible para personas.
{
"type": "provisioning.progress",
"jobId": "pjb_A1b2C3d4E5f6G7h8",
"step": "crawling",
"detail": "Crawling source URLs..."
}step | Cuándo | Ejemplo de detail |
|---|---|---|
crawling | Se están obteniendo las URL de origen | "Crawling source URLs..." o "Retrying crawl (attempt 2)..." |
configuring | El agente de IA está analizando el contenido y escribiendo la configuración del motor | "AI agent analyzing content and configuring engine..." o "Retrying configuration (attempt 2)..." |
completed | El trabajo ha terminado correctamente | "Provisioning complete" |
failed | El trabajo ha fallado | Un mensaje de error que describe el fallo |
Un reintento no es un fallo
Los pasos crawling y configuring pueden activarse más de una vez: un error transitorio de obtención o análisis se reintenta, y ese reintento aparece como un evento de progreso con un detail como "Retrying crawl (attempt 2)...". Eso significa que el trabajo se está recuperando, no que haya fallado. Trata solo el paso failed como terminal; su detail contiene el motivo real.
Gestiona los pasos que no reconozcas
Con el tiempo pueden añadirse nuevos valores de step. Haz switch sobre los pasos que conozcas, trata completed y failed como los dos que cierran el socket e ignora cualquier otro como informativo: un cliente compatible con futuras versiones seguirá funcionando sin necesidad de actualizarse.
Conectarte después de que termine el trabajo#
La gran pregunta con cualquier socket de progreso es qué pasa si te conectas tarde: cuando el rastreo ya ha terminado, después de que un despliegue haya vuelto a conectar la pestaña o cuando el trabajo ya ha fallado. Aquí, la respuesta está integrada en cómo funciona la instantánea.
Si el trabajo ya ha llegado a completed o failed, el servidor envía la instantánea con ese status final (y errorMessage, si falló) y cierra la conexión de inmediato. No hay eventos de progreso que reproducir, porque el estado final ya está en la instantánea. Un trabajo que sigue en marcha mantiene la conexión abierta y transmite el progreso; un trabajo terminado te entrega el resultado y cuelga.
En cualquier caso, el primer mensaje te dice en qué punto están las cosas. Conéctate en cualquier momento, incluso después de que termine: no puedes conectarte ni demasiado pronto ni demasiado tarde.
Integrarlo en tu interfaz#
Abre el socket con el ID de trabajo pjb_, lee la instantánea para fijar el estado inicial y, después, actualiza con cada evento de progreso y cierra cuando el trabajo llegue a completed o failed:
import WebSocket from "ws";
const jobId = "pjb_A1b2C3d4E5f6G7h8";
const ws = new WebSocket(
`wss://api.lingo.dev/jobs/provisioning/${jobId}/ws`,
{ headers: { "X-API-Key": process.env.LINGO_API_KEY } }
);
ws.on("message", (raw) => {
const event = JSON.parse(raw);
switch (event.type) {
case "provisioning.snapshot":
console.log(`status: ${event.status}`);
break;
case "provisioning.progress":
console.log(`${event.step}: ${event.detail}`);
if (event.step === "completed" || event.step === "failed") {
ws.close();
}
break;
}
});Pruébalo con un trabajo que rastree sin problemas y vaya mostrando la configuración paso a paso:
status: in_progress
crawling: Crawling source URLs...
configuring: AI agent analyzing content and configuring engine...
completed: Provisioning completeEse es todo el recorrido en pantalla: el trabajo arranca en in_progress, ves cómo rastrea y después configura, y completed te indica que el motor está completamente aprovisionado. El mismo bucle también funciona si te conectas tarde: un trabajo terminado envía una única instantánea con su status final y el socket se cierra, así que el código que gestiona la ejecución en vivo también gestiona la reproducción sin necesidad de un caso especial.
Mantén tu clave de API en el servidor#
El socket se autentica con tu clave de API —la misma clave con ámbito de organización que usan los endpoints REST—. Esa clave da acceso a todos los motores de tu organización, así que el navegador es el lugar equivocado para abrir la conexión: cualquiera que vea el código fuente podría verla.
Conéctate desde tu backend, no desde el navegador
Abre el WebSocket desde tu servidor, donde la clave ya reside, y luego reenvía el progreso al navegador por tu propio canal: un WebSocket o un flujo de eventos enviados por el servidor que controles tú. Tu frontend muestra cómo se configura el motor; tu clave nunca sale de tu infraestructura.
Esto refleja el modelo de webhook: la conexión que toca Lingo.dev se ejecuta en el servidor, y lo que llega al usuario es lo que tu propia aplicación decida reenviar.
Dónde encaja esto#
El WebSocket es la vista en vivo: está vinculado a un solo trabajo y se cierra cuando ese trabajo termina. Para tener un registro duradero, de servidor a servidor, del resultado que sobreviva al cierre de una pestaña o a un despliegue, combínalo con el webhook de finalización: el socket alimenta la barra de progreso mientras el trabajo está en pantalla, y el webhook entrega el resumen de todo lo que la IA ha creado en cuanto está listo. Conecta ambos desde la misma llamada de creación.
