API de integración de NexaLab

Empezar

La integración va en dos direcciones, y una implementación completa suele usar las dos.

Los tres pasos

1. Pide la credencial. La emite un administrador del laboratorio desde Integraciones → Credenciales. Recibirás un client_id y una clave secreta que solo se muestra una vez.
2. Comprueba que funciona. Llama a GET /api/v1/me: te dice el laboratorio, los alcances concedidos y la lista exacta de operaciones que tienes permitidas.
3. Integra. Usa el spec OpenAPI para generar un cliente, o llama directo con la cabecera X-API-Key.

curl -H "X-API-Key: nxk_live_…" \
  https://nexalaboratories.com/api/v1/me

Autenticación

La misma credencial se presenta de dos formas. Elige la que soporte tu plataforma; no conceden nada distinto.

Opción A — Clave directa

Lo que usan Power Apps, la mayoría de ERP y cualquier herramienta que sepa poner una cabecera fija.

GET /api/v1/inventory/items
X-API-Key: nxk_live_…

También se acepta Authorization: Bearer nxk_live_….

Opción B — OAuth2 client_credentials

Para SAP y plataformas corporativas que prohíben guardar un secreto permanente en el cliente. El token dura una hora.

curl -X POST https://nexalaboratories.com/api/v1/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=nxc_…" \
  -d "client_secret=nxk_live_…"

{
  "access_token": "eyJhbGciOi…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "inventory:read purchasing:write"
}

Modelo de permisos

Tres reglas gobiernan todo lo que puede hacer una integración.

1. Una credencial pertenece a un laboratorio. Una institución con tres laboratorios emite tres credenciales. El alcance nunca es ambiguo.
2. Una credencial nunca puede hacer más que una persona identificable. Sus permisos efectivos son la intersección de los alcances concedidos con lo que puede hacer hoy el usuario responsable de esa credencial. Conceder inventory:write a una credencial cuyo responsable solo puede leer inventario no habilita nada.
3. Todo queda en la bitácora. Una solicitud de compra creada por SAP pasa por las mismas validaciones, los mismos flujos y el mismo registro de auditoría que una creada a mano. No existe un camino «de servicio» que se salte reglas.

Operaciones

102 operaciones agrupadas por módulo. Cada una indica el alcance que necesita. Todas cuelgan de https://nexalaboratories.com/api/v1.

Paginación

Añade limit (1-500, por omisión 100) y offset a cualquier colección. La respuesta incluye un objeto pagination con el total.

GET /api/v1/inventory/items?limit=50&offset=100

Límite de llamadas

Por omisión 120 por minuto y credencial, configurable al emitirla. Al superarlo se devuelve 429 con retryAfterSeconds.

Alcances

Un alcance de escritura incluye siempre su lectura. Pide lo mínimo: un ERP de compras normalmente solo necesita inventario, compras y catálogo.

Webhooks

Un administrador los registra en Integraciones → Webhooks, indicando la URL de destino (HTTPS obligatorio) y los eventos. Se admiten comodines: * para todo, INVENTORY_* para un módulo entero, o el nombre exacto de una acción.

Forma del envío

POST https://tu-erp.institucion.com/hooks/nexalab
Content-Type: application/json
x-nexalab-event: INVENTORY_ITEM_CREATED
x-nexalab-delivery: 6f1c…
x-nexalab-timestamp: 1753900000
x-nexalab-signature: v1=<hmac-sha256-hex>

{
  "id": "…",
  "type": "INVENTORY_ITEM_CREATED",
  "createdAt": "2026-07-30T18:22:11.000Z",
  "data": { "action": "…", "entityId": "…", "newValue": { … } }
}

Verifica la firma siempre

Calcula el HMAC sobre el cuerpo crudo, antes de parsear el JSON, y compara con tiempo constante.

const esperado = "v1=" + crypto
  .createHmac("sha256", SECRETO)
  .update(`${headers["x-nexalab-timestamp"]}.${cuerpoCrudo}`)
  .digest("hex");

Reintentos e idempotencia

Si no respondes 2xx, NexaLab reintenta hasta 5 veces con espera creciente (1, 5, 15 y 60 minutos). El campo id es estable entre reintentos: úsalo para descartar duplicados. Responde 2xx en cuanto recibas el evento y procésalo después; si tardas más de 10 segundos, el envío se da por fallido.

Errores

Siempre con la forma { "error": "<código>", "message": "<explicación>" }.

Los errores de validación de negocio llegan tal cual del módulo, con message e issues señalando exactamente qué campo falta.

Cada respuesta lleva x-nexalab-request-id. Cítalo al reportar un problema: la llamada queda registrada con su duración y su resultado.

Guías por plataforma

Power Apps y Power Automate

1. Descarga el archivo del conector.
2. En Power Apps: Conectores personalizados → Nuevo conector → Importar un archivo OpenAPI.
3. En Seguridad, elige Clave de API, parámetro X-API-Key, ubicación Encabezado.
4. Crea la conexión pegando la clave emitida en NexaLab.

Se publica en Swagger 2.0 porque es el único formato que acepta ese importador. Para todo lo demás, usa el OpenAPI 3.1.

SAP

Usa el flujo OAuth2 client_credentials contra /api/v1/oauth/token. Registra el destino con la URL base https://nexalaboratories.com/api/v1 y renueva el token cuando expire. Para el sentido contrario, registra un webhook apuntando al endpoint de tu middleware.

Cualquier otro ERP o desarrollo propio

Envía X-API-Key en cada llamada y genera el cliente desde el spec OpenAPI. Ejemplo de sincronización de existencias:

BASE="https://nexalaboratories.com/api/v1"
CLAVE="nxk_live_…"

# Traer el inventario
curl -H "X-API-Key: $CLAVE" "$BASE/inventory/items?limit=200"

# Registrar una entrada tras recibir una compra
curl -X POST "$BASE/inventory/movements" \
  -H "X-API-Key: $CLAVE" -H "Content-Type: application/json" \
  -d '{"inventoryItemId":"<uuid>","movementType":"IN","quantity":10,"reason":"Recepción OC-4471"}'