Saltar a contenido

Firma de recepción: integrar desde Business Central

Esta guía describe la lógica que debe implementar la extensión que genera los documentos de check-in. Parte del recorrido rápido. Para incorporar la función AL de firma con certificado a tu extensión, sigue Integración manual desde AL.

Preparar la conexión

Configura el origen HTTPS de la API y guarda el bearer del entorno como secreto en BC. No uses localhost ni una IP privada como dirección para BC cloud.

En Extension Management → Configure → Extension Settings, activa Allow HttpClient Requests para la app que realiza las llamadas. Microsoft documenta este ajuste y el uso de HttpClient en AL.

Operación Cabecera
Gestión de tablets, solicitudes y resultados desde BC Authorization: Bearer <BC_BEARER_TOKEN>
Operaciones de la PWA activada X-Device-Token: <deviceToken>

El token de tablet no debe utilizarse como credencial de BC.

Separar administración y documentos

La administración registra tablets, emite códigos, revoca o elimina. El proceso de check-in reutiliza una tablet activada y solo crea/consulta/cancela/descarga solicitudes. Registrar la tablet en cada firma produce conflictos; emitir códigos en cada firma corta su sesión.

La tabla de negocio debe conservar, como mínimo:

Dato Propósito
externalRef Referencia del documento/check-in de BC
deviceId Tablet elegida
requestId Identificador devuelto por la API
status Estado observado
Fecha de última consulta Control del proceso de actualización
Error y traceId Diagnóstico
Resultado archivado Evitar descargas duplicadas y registrar el adjunto

Esta tabla es una propuesta de integración; el repositorio no incluye una tabla AL para la cola manuscrita.

Crear y guardar la solicitud

Convierte el stream del PDF a Base64, construye el JSON según Ejemplos REST, envía POST /v1/signature-requests y analiza la respuesta 201. Guarda el requestId asociado a tu documento.

externalRef facilita buscar y conciliar, pero no es una clave única ni hace idempotente la creación. Si se pierde la respuesta, consulta solicitudes recientes por tablet y concilia sus referencias antes de crear otra. No hay filtro HTTP por externalRef; el listado es limitado, así que la conciliación no garantiza recuperar cualquier solicitud histórica.

Polling de estado en Business Central

Implementa una acción Actualizar estado o una Job Queue que consulte solicitudes abiertas. Como punto de partida operativo, una Job Queue cada minuto suele ser suficiente; adapta la frecuencia al proceso. Este intervalo es una recomendación, no una función implementada por la extensión del repositorio.

  1. Para cada solicitud abierta, envía GET /v1/signature-requests/{requestId}.
  2. Analiza JSON y guarda estado, fechas y datos de error.
  3. Si está signed y aún no has archivado el resultado, descárgalo y guarda el adjunto.
  4. Si está cancelled, expired o error, finaliza el seguimiento automático y ofrece la acción de negocio correspondiente.

No mantengas un bucle AL bloqueante esperando al huésped. La máquina de estados explica caducidad y recuperación.

Para paneles de soporte:

GET /v1/signature-requests?status=pending&deviceId=tablet-recepcion-1&limit=50
Authorization: Bearer <token>

El listado ordena por creación descendente, admite límite 1–100 y no devuelve PDFs. No hay paginación por cursor. resultAvailable indica un estado/ruta registrado; la descarga sigue siendo la comprobación efectiva de disponibilidad.

Descargar el resultado

La siguiente parte AL se inserta después de comprobar una respuesta HTTP satisfactoria y Content-Type: application/pdf:

Response.Content.ReadAs(PdfIn);
PdfFirmado.CreateOutStream(PdfOut);
CopyStream(PdfOut, PdfIn);

Response es HttpResponseMessage, PdfIn un InStream, PdfOut un OutStream y PdfFirmado un codeunit Temp Blob. La petición previa es GET /v1/signature-requests/{requestId}/result con bearer. Persiste el adjunto antes de marcar el resultado como archivado.

Cancelar y resolver errores

BC puede cancelar una solicitud abierta con POST /v1/signature-requests/{requestId}/cancel. Tras 409 INVALID_STATE, vuelve a consultar: podría haberse firmado antes de la cancelación.

Registra el código HTTP, code, traceId y las referencias de negocio; omite tokens y Base64 de documentos. La guía de errores distingue operaciones reintentables y creación potencialmente duplicable.