Saltar a contenido

API - Estados de solicitud

Esta pagina define el ciclo de vida de una solicitud de firma. Es la referencia para Business Central, la tablet y soporte operativo.

Resumen rapido

Estado Tipo Quien lo produce Significado
pending Abierto BC al crear la solicitud La solicitud esta en cola para una tablet concreta.
displayed Abierto Tablet con GET /next La tablet ha reservado el documento y puede mostrarlo.
signing Abierto Tablet con POST /start-signing El huesped ha empezado a firmar.
signed Final Tablet con POST /signed El PDF firmado esta registrado y BC puede descargarlo.
cancelled Final BC o tablet La solicitud se ha cancelado y no admite firma.
expired Final Mantenimiento/API La solicitud caduco antes de completarse.
error Final operativo API Hay un problema tecnico que requiere intervencion o reenvio.

Estados abiertos

pending

Solicitud creada correctamente por BC mediante POST /v1/signature-requests.

  • Entra en la cola FIFO del deviceId indicado.
  • No hay tablet mostrando el documento todavia.
  • BC puede cancelarla con POST /v1/signature-requests/{requestId}/cancel.
  • Puede expirar si supera expiresAt antes de ser reservada.

displayed

La tablet ha llamado a GET /v1/devices/{deviceId}/next, la API ha reservado la solicitud y ha devuelto el PDF.

  • Solo la tablet autenticada que hizo la reserva puede continuar con esa solicitud.
  • La reserva usa displayLockExpiresAt, configurado por POLLING_LOCK_SECONDS.
  • Si el lock expira sin pasar a signing, la API libera la reserva y vuelve a pending.
  • BC o la tablet pueden cancelarla.
  • GET /v1/devices/{deviceId}/active permite recuperarla tras recargar la PWA.

signing

La tablet ha confirmado que la firma ha empezado con POST /v1/signature-requests/{requestId}/start-signing.

  • Ya no se libera por expiracion del lock de display.
  • La tablet puede subir el PDF firmado con POST /v1/signature-requests/{requestId}/signed.
  • BC o la tablet pueden cancelarla si el proceso se aborta.
  • GET /active la devuelve para reanudar despues de una recarga.

Estados finales

signed

La API ha aceptado y guardado el PDF firmado.

  • BC debe descargarlo con GET /v1/signature-requests/{requestId}/result.
  • resultAvailable aparece como true en GET /v1/signature-requests si existe archivo firmado.
  • No se permite sobrescribir el PDF firmado.

cancelled

Solicitud cancelada desde BC o desde la tablet.

  • No se puede firmar ni descargar resultado.
  • Si hace falta repetir el proceso, BC debe crear una solicitud nueva.

expired

Solicitud vencida antes de completarse.

  • La expiracion se aplica sobre solicitudes pending y displayed.
  • Una solicitud en signing no expira automaticamente en la implementacion actual.
  • Si hace falta seguir, BC debe crear una solicitud nueva.

error

Estado tecnico para incidencias no recuperables automaticamente.

Casos actuales:

  • ORIGINAL_FILE_MISSING: falta el PDF original en storage cuando la tablet intenta recuperarlo.

Campos utiles:

  • errorCode
  • errorMessage
  • traceId de la respuesta que detecto el problema

Transiciones permitidas

Desde Hacia Disparador
pending displayed Tablet llama a GET /v1/devices/{deviceId}/next.
pending cancelled BC cancela la solicitud.
pending expired expiresAt queda en el pasado.
pending error Falta el PDF original al intentar reservarlo.
displayed signing Tablet llama a POST /v1/signature-requests/{requestId}/start-signing.
displayed pending Expira el lock de display antes de empezar firma.
displayed cancelled BC o tablet cancelan.
displayed expired expiresAt queda en el pasado antes de empezar firma.
displayed error Falta el PDF original al intentar recuperar activo.
signing signed Tablet sube signedPdfBase64.
signing cancelled BC o tablet cancelan.

Los estados finales no tienen transiciones de salida. Para reintentar se crea una nueva solicitud.

Que debe hacer BC

Estado recibido Accion recomendada
pending Seguir esperando o permitir cancelacion manual.
displayed Mostrar que la tablet ya tiene el documento.
signing Mostrar que el huesped esta firmando.
signed Descargar el PDF y marcar resultado como recibido.
cancelled Cerrar el flujo como cancelado.
expired Informar caducidad y ofrecer reenviar.
error Registrar errorCode, errorMessage y traceId; revisar storage/logs antes de reenviar.

Que debe hacer la tablet

  1. Consultar GET /active para recuperar una solicitud abierta tras recarga.
  2. Si no hay activa, consultar GET /next cada VITE_POLLING_INTERVAL_MS.
  3. Mostrar el PDF recibido en displayed.
  4. Llamar a start-signing con el primer trazo.
  5. Enviar signedPdfBase64 solo cuando el estado sea signing.
  6. Si recibe 401 o 403, olvidar la sesion local y pedir activacion de nuevo.

Invariantes

  • Una tablet solo puede tener un documento activo a la vez.
  • La cola es independiente por deviceId.
  • GET /next debe ser atomico ante llamadas concurrentes.
  • La tablet no puede operar solicitudes de otro deviceId.
  • Un PDF firmado no se sobrescribe.