Rastrear el progreso de la carga con suscripciones

Después de subir un archivo a la URL pre-firmada de S3, la plataforma continúa procesándolo de forma asíncrona.

Usa subscribeUserFeed para recibir eventos de carga en tiempo real en lugar de hacer sondeos.

Para el esquema general de eventos, consulta Formato de Evento de Suscripción.

Feed y Categoría

Los eventos de carga se entregan en:

• subscribeUserFeed

Utilizan:

• category: "upload"

Nombres de Evento

El procesamiento de carga emite una secuencia de eventos tales como:

• uploadScanned
• uploadTypeChecked
• uploadConverting
• uploadFlattened
• uploadTagsParsed
• uploadPdfMetaExtracted
• uploadCompleted
• uploadFailed

Payload del Evento de Carga

Los payloads de carga usan esta forma base:

{
  "version": "1.0",
  "eventId": "evt...",
  "timestamp": "2026-04-24T10:38:36.822Z",
  "level": "INFO",
  "event": "uploadCompleted",
  "category": "upload",
  "groupId": null,
  "userId": "usr...",
  "requestId": null,
  "batchId": null,
  "error": null,
  "data": {
    "id": "tmp...",
    "key": "upload/usr.../tmp....pdf",
    "code": "UPLOADOK"
  }
}

data.code conserva el código de procesamiento a nivel inferior durante la migración y la compatibilidad.

Operación de Suscripción

subscription SubscribeUserFeed {
  subscribeUserFeed {
    userId
    data
  }
}

Ejemplo en JavaScript

const parseEnvelope = (payload) => {
  const raw = payload?.data;
  if (!raw) return null;
  return typeof raw === 'string' ? JSON.parse(raw) : raw;
};

const handleUserFeed = ({ data }) => {
  const wrapper = data?.subscribeUserFeed;
  const event = parseEnvelope(wrapper);

  if (event?.category !== 'upload') return;

  switch (event.event) {
    case 'uploadCompleted':
      console.log('upload complete', event.data.id, event.data.key);
      break;
    case 'uploadFailed':
      console.error('upload failed', event.data.code, event.data.key);
      break;
    default:
      console.log('upload progress', event.event, event.data.code);
  }
};

Cuándo Usarlo

Esto es más útil cuando quieres:

• mostrar un panel de progreso o una línea de tiempo del estado de la carga
• detectar fallos de validación asincrónica después de que el PUT a S3 haya concluido con éxito
• reaccionar inmediatamente cuando una plantilla o recurso cargado está listo