Saltar a contenido

API - Guia rapida BC

Esta pagina es la entrada recomendada para el desarrollador de Business Central.

URLs de pruebas

  • API base URL: https://apifirma.jdmarquez.dev
  • Swagger UI: https://apifirma.jdmarquez.dev/swagger
  • OpenAPI JSON: https://apifirma.jdmarquez.dev/swagger/v1/swagger.json
  • tablet de pruebas: https://tabletfirma.jdmarquez.dev/

Lo que necesitas para empezar

  • BC_BEARER_TOKEN valido
  • una extension AL con HttpClient habilitado
  • capacidad para convertir el PDF a Base64 antes de llamar a la API
  • un deviceId de tablet existente o uno nuevo que vayas a registrar

Autenticacion

Actor Header Uso
Business Central Authorization: Bearer <BC_BEARER_TOKEN> registrar tablets, emitir codigos, crear solicitudes, listar/consultar estado, descargar resultado
Tablet activada X-Device-Token: <DEVICE_TOKEN> active, next, start-signing, signed, cancelacion desde tablet
Activacion publica de tablet sin header deviceId + activationCode

Flujo minimo para BC

  1. Registrar la tablet con POST /v1/devices si todavia no existe.
  2. Emitir codigo con POST /v1/devices/{deviceId}/activation-code cuando la tablet se instala o se resetea.
  3. Crear la solicitud con POST /v1/signature-requests enviando pdfBase64 y deviceId.
  4. Consultar el estado con GET /v1/signature-requests/{requestId} hasta llegar a signed, cancelled o expired.
  5. Descargar el PDF final con GET /v1/signature-requests/{requestId}/result.

La API no hace callback hacia BC. Guarda el requestId y consulta estado desde BC con una accion manual, una Job Queue o un mecanismo de UI controlado. Detalle recomendado: Polling de estado en Business Central.

Endpoints que normalmente usa BC

Objetivo Endpoint
Listar tablets GET /v1/devices
Registrar tablet POST /v1/devices
Emitir codigo POST /v1/devices/{deviceId}/activation-code
Revocar tablet POST /v1/devices/{deviceId}/revoke
Eliminar tablet DELETE /v1/devices/{deviceId}
Crear solicitud POST /v1/signature-requests
Listar solicitudes GET /v1/signature-requests?status=pending&deviceId=tablet-recepcion-1&limit=50
Consultar estado GET /v1/signature-requests/{requestId}
Cancelar solicitud POST /v1/signature-requests/{requestId}/cancel
Descargar PDF firmado GET /v1/signature-requests/{requestId}/result

Orden de lectura recomendado

  1. API - Resumen
  2. API - Business Central
  3. API - Errores de integracion
  4. API - Swagger
  5. API - Ejemplos

Checklist rapido antes de integrar

  • confirmar que GET /health responde ok
  • probar POST /v1/devices desde Swagger o Postman con el bearer token
  • validar que el token BC se guarda fuera del frontend
  • registrar traceId en logs de BC cuando una llamada falle
  • usar DELETE /v1/devices/{deviceId} solo para limpieza administrativa; si devuelve 409, quedan solicitudes abiertas asociadas a esa tablet