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. desplegar el endpoint deseado
  3. pulsar Try it out
  4. rellenar parametros, body y headers necesarios
  5. ejecutar con Execute

Headers que vas a necesitar

Operaciones de BC

Usan:

Authorization: Bearer <BC_BEARER_TOKEN>

Operaciones de tablet

Usan:

X-Device-Token: <DEVICE_TOKEN>

Flujo recomendado de prueba con Swagger

1. Verificar salud

  • GET /health

Respuesta esperada:

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

2. Registrar una tablet

  • POST /v1/devices

Body de ejemplo:

{
  "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
{
  "deviceId": "tablet-recepcion-1",
  "activationCode": "ABCD2345"
}

Guarda deviceToken.

5. Crear una solicitud de firma

  • POST /v1/signature-requests
{
  "externalRef": "BC-1001",
  "deviceId": "tablet-recepcion-1",
  "documentName": "autorizacion.pdf",
  "pdfBase64": "<BASE64_PDF>",
  "guestName": "John Doe",
  "reservationRef": "RES-1001"
}

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

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