{"openapi":"3.0.3","info":{"title":"Oktavia Connect API","version":"2026-06-01","description":"Public integration contract for POS, payroll, HR and custom systems connecting with Oktavia."},"servers":[{"url":"https://api.oktavia.app","description":"Production"},{"url":"https://api-staging.oktavia.app","description":"Staging"}],"tags":[{"name":"Inbound events","description":"Events sent by external systems into Oktavia."},{"name":"Developer metadata","description":"Public metadata and integration documentation."}],"paths":{"/connect/inbound/{connectionId}/events":{"post":{"tags":["Inbound events"],"summary":"Send an inbound integration event","description":"Receives POS daily closes, sales intervals, products, reservation forecasts or custom events. Requests must be signed with the connection HMAC secret.","operationId":"createInboundConnectEvent","parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"},"description":"Oktavia Connect connection identifier."},{"name":"x-oktavia-key","in":"header","required":true,"schema":{"type":"string"},"description":"API key generated for the connection."},{"name":"x-oktavia-signature","in":"header","required":true,"schema":{"type":"string"},"description":"HMAC-SHA256 signature in hex format."},{"name":"x-oktavia-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix timestamp in milliseconds used for the signature."},{"name":"x-idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Stable unique key for deduplicating retried events."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundConnectEvent"},"examples":{"posDailyClose":{"summary":"POS daily close","value":{"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}]}}}}}}},"responses":{"200":{"description":"Duplicate event recognized by idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundConnectEventResponse"}}}},"202":{"description":"Event accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundConnectEventResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/connect/developer/spec":{"get":{"tags":["Developer metadata"],"summary":"Get Oktavia Connect developer metadata","operationId":"getConnectDeveloperSpec","responses":{"200":{"description":"Developer metadata.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/connect/developer/openapi.json":{"get":{"tags":["Developer metadata"],"summary":"Get Oktavia Connect OpenAPI document","operationId":"getConnectDeveloperOpenApiSpec","responses":{"200":{"description":"OpenAPI document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/connect/developer/postman.json":{"get":{"tags":["Developer metadata"],"summary":"Get Oktavia Connect Postman collection","operationId":"getConnectDeveloperPostmanCollection","responses":{"200":{"description":"Postman collection v2.1.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/connect/developer/insomnia.json":{"get":{"tags":["Developer metadata"],"summary":"Get Oktavia Connect Insomnia collection","operationId":"getConnectDeveloperInsomniaCollection","responses":{"200":{"description":"Insomnia export collection.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"InboundConnectEvent":{"type":"object","required":["eventType","payload"],"properties":{"eventType":{"type":"string","enum":["pos.daily_close","pos.sales_interval","pos.products","reservations.forecast","custom.event"]},"externalId":{"type":"string","description":"Stable source identifier for this event."},"payload":{"type":"object","additionalProperties":true,"description":"Event-specific payload. Prefer ISO dates and stable center names/codes."}}},"InboundConnectEventResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["accepted","processed","duplicate","error"]},"eventType":{"type":"string"},"payloadHash":{"type":"string"},"duplicate":{"type":"boolean"}}},"ErrorResponse":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid payload or missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Invalid API key, timestamp or signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Connection inactive or missing scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}