Developer docs

Integra POS, nominas y sistemas externos con Oktavia.

Oktavia Connect es la capa de integracion para enviar datos operativos a Oktavia y recibir eventos firmados desde Oktavia. Esta documentacion esta pensada para partners POS, herramientas de nomina, gestorias y sistemas internos de cadenas hosteleras.

Quickstart de integracion

El flujo recomendado es empezar siempre en sandbox, validar mapeos con el cliente y solo despues activar produccion. Las credenciales se generan por conexion y por entorno.

Modelo cliente-partner

Un partner puede desarrollar contra sandbox sin acceder a datos reales. Las credenciales productivas siempre las emite el cliente desde su cuenta Oktavia y quedan limitadas a una conexión, un entorno y unos permisos concretos.

Autenticacion, firma e idempotencia

Las llamadas inbound usan API key y firma HMAC. Los webhooks outbound de Oktavia tambien viajan firmados para que el partner pueda validar origen e integridad. La idempotencia evita duplicar cierres diarios o importes si el partner reintenta.

const body = JSON.stringify(payload);
const signedPayload = `${timestamp}.${body}`;
const signature = hmacSha256(secret, signedPayload);

import crypto from 'node:crypto';

function verifyOktaviaSignature(secret, timestamp, body, signature) {
  const expected = crypto.createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

API Reference

Esta es la zona de trabajo para el desarrollador externo: contrato OpenAPI, colecciones importables, guia plana y estado publico. La referencia interactiva completa puede vivir en `developers.oktavia.app` cuando separemos el portal en subdominio propio.

Eventos inbound

Envia eventos POS y demanda a este endpoint con firma HMAC, idempotencia y un `eventType` soportado. Todos los eventos usan la misma envolvente; el contenido de `payload` depende del tipo de evento.

{
  "eventType": "pos.daily_close",
  "externalId": "close-2026-06-01-main-site",
  "occurredAt": "2026-06-01T23:05:00.000Z",
  "payload": {
    "date": "2026-06-01",
    "center": "main-site",
    "total": 4180.5,
    "currency": "EUR",
    "channels": [
      {
        "name": "Comida",
        "total": 2660.1
      },
      {
        "name": "Bebida",
        "total": 1520.4
      }
    ]
  }
}

Envolvente comun

Payloads por tipo de evento

{
  "eventType": "pos.daily_close",
  "externalId": "close-2026-06-01-main-site",
  "occurredAt": "2026-06-01T23:05:00.000Z",
  "payload": {
    "date": "2026-06-01",
    "center": "main-site",
    "total": 4180.5,
    "currency": "EUR",
    "channels": [
      {
        "name": "Comida",
        "total": 2660.1
      },
      {
        "name": "Bebida",
        "total": 1520.4
      }
    ]
  }
}

{
  "eventType": "pos.sales_interval",
  "externalId": "sales-2026-06-01-main-site-15-00",
  "occurredAt": "2026-06-01T15:05:00.000Z",
  "payload": {
    "date": "2026-06-01",
    "center": "main-site",
    "intervals": [
      {
        "start": "13:00",
        "end": "14:00",
        "total": 910.2,
        "food": 620.1,
        "drinks": 290.1,
        "tickets": 34
      },
      {
        "start": "14:00",
        "end": "15:00",
        "total": 1240.4,
        "food": 870.2,
        "drinks": 370.2,
        "tickets": 41
      }
    ],
    "currency": "EUR"
  }
}

curl -X POST "https://api.oktavia.app/connect/inbound/{connectionId}/events" \
  -H "content-type: application/json" \
  -H "x-oktavia-key: ok_live_..." \
  -H "x-oktavia-timestamp: 1780300800000" \
  -H "x-idempotency-key: close-2026-06-01-main-site" \
  -H "x-oktavia-signature: <hmac-sha256>" \
  -d '{"eventType":"pos.daily_close","externalId":"close-2026-06-01-main-site","occurredAt":"2026-06-01T23:05:00.000Z","payload":{"date":"2026-06-01","center":"main-site","total":4180.5,"currency":"EUR"}}'

Respuestas y errores

Un evento aceptado no significa necesariamente que ya haya impactado en planificacion; significa que Oktavia lo ha recibido, verificado y registrado para procesarlo.

{
  "id": "evt_01J...",
  "status": "accepted",
  "eventType": "pos.daily_close",
  "payloadHash": "sha256_hash",
  "duplicate": false
}

Nomina y gestoria

Las conexiones de tipo nomina son salientes desde Oktavia: el cliente genera paquetes firmados con horas validadas y ausencias aprobadas para que gestoria, ERP o proveedor laboral los consuma sin rehacer calculos manuales.

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31"
}

{
  "format": "oktavia.payroll.hours.v1",
  "period": {
    "startDate": "2026-05-01",
    "endDate": "2026-05-31"
  },
  "rows": [
    {
      "employeeCode": "employee-001",
      "employeeName": "Trabajador de ejemplo",
      "center": "main-site",
      "ordinaryMinutes": 9120,
      "complementaryMinutes": 0,
      "overtimeMinutes": 120,
      "nightMinutes": 90,
      "holidayMinutes": 0
    }
  ]
}

{
  "format": "oktavia.payroll.absences.v1",
  "period": {
    "startDate": "2026-05-01",
    "endDate": "2026-05-31"
  },
  "rows": [
    {
      "employeeCode": "employee-003",
      "employeeName": "Responsable de ejemplo",
      "type": "vacation",
      "startDate": "2026-05-20",
      "endDate": "2026-05-24",
      "approvedAt": "2026-05-12T10:30:00.000Z"
    }
  ]
}

Webhooks outbound

Configura una URL HTTPS para recibir eventos firmados de Oktavia cuando se publiquen cuadrantes, se validen fichajes, se aprueben ausencias o se generen exportaciones de nomina.

{
  "type": "schedule.published",
  "occurredAt": "2026-06-01T08:00:00.000Z",
  "data": {
    "scheduleId": "schedule_id",
    "centerId": "center_id",
    "weekStart": "2026-06-15",
    "weekEnd": "2026-06-21"
  }
}

Operacion, reintentos y retencion

Checklist de seguridad y versionado

Herramienta local de firma HMAC

Usa este bloque para comprobar si tu firma coincide con la que espera Oktavia. El secret no se envia al servidor: el calculo se hace en tu navegador.

Soporte para integradores

Si una integracion falla, Oktavia puede diagnosticarla mucho mas rapido si el partner aporta los identificadores tecnicos correctos. No hace falta enviar secretos ni payloads completos por correo.