Referencia API: rutas y autenticación
openapi.yaml en la raíz es el contrato HTTP canónico: contiene esquemas, campos, códigos y ejemplos. Swagger se genera desde el código de la instancia; usa Swagger para comprobar el entorno concreto.
Las rutas principales empiezan por /v1. Los PDFs se envían como Base64 dentro de JSON y se descargan como application/pdf. Fechas UTC ISO 8601, IDs de solicitudes/jobs UUID y errores con code, message y traceId.
Autenticación
| Actor | Credencial |
|---|---|
| Business Central | Authorization: Bearer <BC_BEARER_TOKEN> |
| Tablet activada | X-Device-Token: <deviceToken> |
| Activación | Sin token previo; deviceId + activationCode |
| Salud | Sin autenticación |
Un token de tablet ausente devuelve 401; uno inválido, revocado o ajeno a la ruta devuelve 403. El token BC identifica una integración del entorno, no un usuario individual.
Administración de dispositivos — bearer BC
| Método y ruta | Resultado |
|---|---|
GET /v1/devices |
Tablets y lastSeenAt |
POST /v1/devices |
Registrar tablet |
POST /v1/devices/{deviceId}/activation-code |
Código nuevo; invalida token anterior |
POST /v1/devices/{deviceId}/revoke |
Cortar acceso y conservar registro |
DELETE /v1/devices/{deviceId} |
Eliminar registro sin solicitudes abiertas |
Firma manuscrita — bearer BC
| Método y ruta | Resultado |
|---|---|
POST /v1/signature-requests |
Crear solicitud; 201 |
GET /v1/signature-requests |
Listado con filtros status, deviceId, limit |
GET /v1/signature-requests/{requestId} |
Estado |
POST /v1/signature-requests/{requestId}/cancel |
Cancelación |
GET /v1/signature-requests/{requestId}/result |
PDF firmado |
Consulta Integración BC, Estados y Ejemplos REST.
Operaciones tablet — token de dispositivo
| Método y ruta | Resultado |
|---|---|
POST /v1/devices/activate |
Obtener sesión; única ruta pública de activación |
POST /v1/devices/{deviceId}/deactivate |
Desactivar la propia tablet si no tiene documento activo |
GET /v1/devices/{deviceId}/active |
Recuperar activo o 204 |
GET /v1/devices/{deviceId}/next |
Reservar siguiente o 204 |
POST /v1/signature-requests/{requestId}/start-signing |
Iniciar firma |
POST /v1/signature-requests/{requestId}/signed |
Subir PDF final |
POST /v1/devices/{deviceId}/signature-requests/{requestId}/cancel |
Cancelar reserva propia |
activate no lleva token; las otras rutas de esta tabla sí. La gestión operativa está en Operación de tablets.
PAdES — bearer BC
| Método y ruta | Resultado |
|---|---|
POST /v1/pades-signature-requests/prepare |
Preparación; requiere Idempotency-Key |
POST /v1/pades-signature-requests/{requestId}/complete |
Completar con firma RSA |
GET /v1/pades-signature-requests/{requestId} |
Estado, hashes y disponibilidad |
GET /v1/pades-signature-requests/{requestId}/result |
PDF firmado |
Usa Integración manual desde AL para copiar el código completo a tu extensión y Protocolo PAdES para el intercambio HTTP.
Texto y OCR — bearer BC
| Método y ruta | Resultado |
|---|---|
POST /v1/pdf-text-extractions |
Texto embebido en respuesta 200 |
POST /v1/pdf-ocr-extractions |
Trabajo OCR en memoria; 202 |
GET /v1/pdf-ocr-extractions/{jobId} |
Estado y resultado OCR |
Guía: Extracción y OCR.
Salud y diagnóstico
GET /health devuelve 200 o 503 y comprueba PostgreSQL y escritura en storage. X-Trace-Id identifica la llamada. Los errores de aplicación repiten ese valor en el cuerpo; errores del proxy o de enlace/formato pueden tener otra forma.
Guía: Errores y recuperación.