{"name":"Oktavia Connect","version":"2026-06-01","basePath":"/connect","authentication":{"inboundHeaders":{"apiKey":"x-oktavia-key","signature":"x-oktavia-signature","timestamp":"x-oktavia-timestamp","idempotencyKey":"x-idempotency-key"},"outboundHeaders":{"event":"x-oktavia-event","signature":"x-oktavia-signature","timestamp":"x-oktavia-timestamp","deliveryId":"x-oktavia-delivery-id"},"signature":{"algorithm":"HMAC-SHA256","format":"hex","signedPayload":"<timestamp>.<raw-json-body>"}},"endpoints":{"inboundEvents":{"method":"POST","path":"/connect/inbound/{connectionId}/events","description":"Receives events from POS, reservations, HR, payroll or custom systems."}},"scopes":["pos:daily-close:write","pos:sales:write","pos:products:write","reservations:forecast:write","custom:events:write","payroll:hours:read","payroll:absences:read","webhooks:receive"],"inboundEventTypes":["pos.daily_close","pos.sales_interval","pos.products","reservations.forecast","custom.event"],"outboundEventTypes":["schedule.published","schedule.updated","time_entry.validated","time_period.closed","absence.approved","absence.rejected","employee.created","employee.updated","payroll.hours_export","payroll.absences_export"],"retryPolicy":{"maxAttempts":5,"retryDelay":"5 to 60 minutes, increasing by attempt count","terminalStatus":"failed delivery with max attempts marks the connection as error"},"certificationChecklist":[{"area":"Credenciales","items":["Usa credenciales separadas para sandbox y produccion.","No expone apiKey ni secret en clientes publicos o repositorios.","Tiene procedimiento para rotar credenciales si hay una filtracion."]},{"area":"Firma e idempotencia","items":["Firma cada request con HMAC-SHA256 usando el body JSON exacto enviado.","Rechaza timestamps antiguos en webhooks outbound.","Envia x-idempotency-key estable para eventos que puedan reintentarse."]},{"area":"Calidad de datos","items":["Envia fechas ISO y moneda ISO cuando hay importes.","Mantiene identificadores externos estables para cierres, productos y centros.","Mapea centro, fecha operativa e importes con el cliente antes de produccion."]},{"area":"Operacion","items":["Implementa reintentos con backoff ante errores 5xx o timeouts.","Registra requestId, payloadHash y respuesta de Oktavia para soporte.","Tiene alertas si una integracion empieza a fallar en produccion."]}],"retention":{"webhookPayloadDays":30,"note":"Payload bodies may be purged after retention. Hashes, summaries and delivery metadata remain."},"examples":{"inboundPosDailyClose":{"eventType":"pos.daily_close","externalId":"close-2026-06-01-main-site","payload":{"date":"2026-06-01","center":"main-site","total":4180.5,"currency":"EUR","channels":[{"name":"Comida","total":2660.1},{"name":"Bebida","total":1520.4}]}},"outboundSchedulePublished":{"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"}}}}