Una aplicación recibe un archivo para procesar y muestra un indicador de carga. El usuario cierra la pestaña. Al volver, no sabe si el archivo sigue en cola, si terminó o si debe enviarlo otra vez. La tarea puede funcionar técnicamente y, aun así, dejar una experiencia imposible de operar.

Un job asíncrono necesita una identidad que sobreviva a la conexión del navegador. Su contrato debe explicar qué trabajo se aceptó, cómo consultar su estado y dónde encontrar el resultado.

Aceptar una solicitud no significa haberla completado

La API valida primero los requisitos que puede comprobar sin ejecutar el trabajo completo: formato básico, autorización, alcance y límites aplicables. Si ya sabe que la solicitud no es válida, devolver ‘procesando’ solo retrasa una respuesta necesaria.

Después registra el trabajo de forma duradera y devuelve una referencia consultable. El patrón de solicitud y respuesta asíncronas de Azure Architecture Center describe una variante con HTTP 202 y un recurso de estado independiente.

En un contrato ilustrativo, la respuesta inicial podría ser:

HTTP/1.1 202 Accepted
Location: /jobs/job-example
Content-Type: application/json

{
  "id": "job-example",
  "status": "queued",
  "statusUrl": "/jobs/job-example"
}

El identificador y las rutas son ejemplos. La garantía relevante es que el trabajo aceptado siga disponible si el receptor se reinicia. Una variable en memoria no cumple ese contrato.

Diseña los estados desde las preguntas del usuario

Una persona necesita distinguir ‘espera turno’, ‘se está ejecutando’, ‘terminó’ y ‘requiere una acción’. No tiene por qué conocer la organización interna de los workers.

Estado de ejemplo Qué comunica Acción disponible
En cola El trabajo fue aceptado Consultar o solicitar cancelación si procede
En ejecución El sistema está procesándolo Ver avance disponible
Completado El resultado fue confirmado Abrir el resultado autorizado
Fallido El intento terminó sin completar su contrato Consultar una causa útil y la recuperación permitida
Cancelación solicitada Se ha pedido detenerlo Esperar confirmación del estado final
Cancelado Se detuvo según el contrato Revisar los efectos conservados, si los hay

No declares un resultado completado antes de que el consumidor pueda acceder a él. Si publicarlo requiere otro paso, representa ese paso dentro del trabajo o identifica su estado de forma explícita.

El progreso debe tener un denominador defendible

‘Procesados 400 registros de 1.000’ solo tiene sentido si el total es conocido y estable. Un porcentaje de registros tampoco equivale necesariamente al porcentaje de tiempo restante: algunos registros pueden costar mucho más que otros.

Cuando no puedas estimarlo, muestra la fase actual y la última actualización útil. Es preferible explicar ‘validando relaciones’ que mantener un 99 % inventado durante varios minutos.

Define qué señal permite detectar un trabajo abandonado. Una marca de actividad puede ayudar, pero su ausencia no autoriza por sí sola a repetir todos los efectos. El recuperador debe saber quién conserva la propiedad del intento y qué escritura llegó a confirmarse.

Reenviar y cancelar necesitan reglas propias

Si se pierde la respuesta inicial, el cliente puede repetir la solicitud. Una clave de idempotencia permite relacionar ese reenvío con el trabajo aceptado cuando el contrato está diseñado para ello. Pulsar dos veces no debería generar dos operaciones de negocio inadvertidas.

La cancelación también tiene una carrera con la finalización. Si el trabajo terminó justo antes de la petición, la respuesta debe reflejarlo. ‘Cancelación solicitada’ no significa que el sistema haya deshecho acciones ya ejecutadas.

Documenta qué se puede interrumpir, qué se conserva y cuándo hace falta una compensación. No utilices un único botón para prometer una reversión que el destino no permite.

Protege el estado y el resultado

Un identificador difícil de adivinar no sustituye la autorización. Comprueba el acceso tanto al recurso de estado como al archivo o resultado generado. Los mensajes de error tampoco deben revelar datos de otro cliente.

Conserva el alcance del trabajo: usuario o cuenta, entradas, filtros y versión relevante. Si los permisos cambian mientras está en cola, define qué comprobación se realiza antes de ejecutar y antes de entregar el resultado.

Establece una retención para estados y salidas. Cuando un resultado haya caducado, comunícalo sin confundirlo con un trabajo todavía pendiente.

Pruebas mínimas de la experiencia completa

Cierra y reabre la aplicación; repite la solicitud; reinicia el receptor después de aceptarla; simula un fallo al publicar el resultado; pide cancelar cerca del final. Comprueba en cada caso qué ve el usuario y qué efectos persisten.

Si necesitas incorporar tareas largas a un backend para proyectos de datos, plantea a Nexeus Big Data qué entradas procesa cada trabajo y qué significa completarlo. Esa definición permite diseñar estados y recuperación con un resultado comprensible para quien utiliza la aplicación.