Estado del trabajo

URL base https://api.accessful.de/api/v1/upload-service. Cada petición necesita la cabecera X-API-Key — consulta Autenticación.

GET /job-status/{caseId}

200 OK — un caso terminado:

{ "jobStatus": "completed", "stage": "finished", "score": 87 }

score es la calidad de accesibilidad del resultado, 0–100 (significativo una vez completed). Se devuelve 404 para un caseId desconocido.

jobStatus	Significado
queued	En espera en la cola.
running	Procesándose actualmente.
completed	Terminado — resultado listo para descargar.	final
failed	El procesamiento falló.	final
analyzer_failed	El paso de análisis de accesibilidad falló.	final
canceled	El trabajo fue cancelado.	final
quota_pending	A la espera de una comprobación de cuota asíncrona.
quota_exceeded	Rechazado — cuota del contrato agotada.	final

Al sondear, detente en cuanto veas un estado final.

Fase de procesamiento

Junto a jobStatus, cada respuesta incluye un campo stage — la fase detallada de la canalización, ortogonal al estado general. Úsalo para mostrar el progreso más allá de un simple «en ejecución»: la larga fase de remediación con IA se distingue del análisis.

stage	Significado
queued	Aceptado, esperando a que empiece el primer análisis.
analyzing	El análisis inicial del archivo subido está en curso.
resolving	La remediación con IA del archivo está en curso.
revalidating	El reanálisis del archivo remediado está en curso.
finished	Procesamiento terminado; score refleja el archivo final.
failed	El procesamiento se detuvo por un error irrecuperable.

Posición en la cola

Mientras un caso está queued, la respuesta también te indica en qué lugar de la cola de análisis se encuentra — la misma «posición en cola» en tiempo real que muestra la interfaz web — para que puedas mostrar un significativo «7 de 23, ~5 min» en lugar de un estático «queued».

200 OK — un caso que sigue esperando:

{
  "jobStatus": "queued",
  "stage": "queued",
  "score": 0,
  "queuePosition": 7,
  "queueTotal": 23,
  "estimatedWaitSeconds": 300
}

Campo	Tipo	Notas
queuePosition	integer	Rango en la cola, empezando en 1 (1 = el siguiente en procesarse).
queueTotal	integer	Número total de casos que esperan actualmente (la longitud de la cola).
estimatedWaitSeconds	integer	Estimación aproximada de la espera en segundos, derivada de la profundidad de la cola y del rendimiento del analizador. Puede faltar si no hay ninguna estimación disponible.

Nota

Los tres campos queue* están presentes solo mientras el caso está queued. En cuanto el analizador lo toma (o el caso alcanza cualquier otro estado), se omiten del JSON — nunca aparecen como null. Trata su ausencia como «no está esperando». Esto es aditivo: un cliente que solo lee jobStatus/score no se ve afectado.

La posición es una instantánea en tiempo real de tipo «mejor esfuerzo» que se recalcula en cada petición: solo disminuye a medida que se procesan los casos que van por delante, y un único procesamiento desplaza a todos los que están detrás. Como alternativa basada en push, registra el webhook case.queued para recibir la posición inicial en el momento en que se acepta un caso.