Saltar a contenido

API - Swagger

URLs

  • Swagger UI: https://apifirma.jdmarquez.dev/swagger
  • OpenAPI JSON: https://apifirma.jdmarquez.dev/swagger/v1/swagger.json

Para que sirve

  • explorar todos los endpoints disponibles
  • validar contratos de request y response
  • probar llamadas manuales sin salir del navegador
  • entregar a Business Central una referencia viva del contrato

Requisito

  • SWAGGER_ENABLED=true en el contenedor api

Como probar endpoints desde Swagger UI

  1. abrir https://apifirma.jdmarquez.dev/swagger
  2. pulsar Authorize
  3. introducir el token requerido por el tipo de endpoint
  4. desplegar el endpoint deseado
  5. pulsar Try it out
  6. rellenar parametros y body
  7. ejecutar con Execute

Headers que vas a necesitar

Operaciones de BC

Usan:

text Authorization: Bearer <BC_BEARER_TOKEN>

En el modal Authorize de Swagger introduce solo <BC_BEARER_TOKEN>, sin el prefijo Bearer. Swagger UI anade el header completo automaticamente.

Operaciones de tablet

Usan:

text X-Device-Token: <DEVICE_TOKEN>

En el modal Authorize de Swagger introduce el valor exacto de <DEVICE_TOKEN> obtenido al activar la tablet.

Flujo recomendado de prueba con Swagger

1. Verificar salud

  • GET /health

Respuesta esperada:

json { "status": "ok", "timestamp": "2026-03-11T10:00:00Z", "databaseOk": true, "storageOk": true }

2. Registrar una tablet

  • POST /v1/devices

Body de ejemplo:

json { "deviceId": "tablet-recepcion-1", "name": "Recepcion 1" }

3. Emitir codigo de activacion

  • POST /v1/devices/{deviceId}/activation-code

Guarda activationCode.

4. Activar la tablet

  • POST /v1/devices/activate

json { "deviceId": "tablet-recepcion-1", "activationCode": "123456" }

Guarda deviceToken.

5. Crear una solicitud de firma

  • POST /v1/signature-requests

Swagger UI incluye un ejemplo listo para ejecutar con un PDF dummy de dos paginas. Ese PDF contiene el texto PRUEBA y un recuadro visible para firmar. Antes de ejecutarlo, asegúrate de que existe la tablet tablet-recepcion-1 o cambia deviceId por una tablet registrada.

json { "externalRef": "TEST-SWAGGER-001", "deviceId": "tablet-recepcion-1", "documentName": "prueba-firma.pdf", "pdfBase64": "<PDF_DUMMY_BASE64_INCLUIDO_EN_SWAGGER>", "guestName": "Prueba Swagger", "reservationRef": "SWAGGER" }

5.1. Listar solicitudes

  • GET /v1/signature-requests

Usa los filtros opcionales status, deviceId y limit para revisar la cola desde BC sin descargar PDFs.

6. Simular la tablet

  • GET /v1/devices/{deviceId}/active
  • GET /v1/devices/{deviceId}/next
  • POST /v1/signature-requests/{requestId}/start-signing
  • POST /v1/signature-requests/{requestId}/signed

7. Gestionar tablets

  • POST /v1/devices/{deviceId}/revoke desactiva la tablet y permite reactivarla con un codigo nuevo.
  • DELETE /v1/devices/{deviceId} elimina la tablet si no tiene solicitudes abiertas; devuelve 409 si hay solicitudes pending, displayed o signing.

Limitaciones practicas de Swagger

  • manejar pdfBase64 grandes es incomodo
  • no sustituye a la PWA real de tablet
  • no automatiza polling ni reintentos
  • para descargas de PDF suele ser mas comodo usar curl o Postman

Cuándo usar Swagger y cuándo no

  • usa Swagger para validar config, auth y contrato
  • usa la PWA para validar UX real de la tablet
  • usa scripts o Business Central para validar integracion extremo a extremo

Lectura relacionada