{ "openapi": "3.0.3", "info": { "title": "Karma Common API", "description": "# Introduction\n\nThe Karma Common API is a centralized REST API for the Karma restaurant platform, providing secure access to core resources including inventory, orders, schedules, webhooks, and more.\n\n## Features\n\n- **API Key Authentication**: Simple, long-lived access with bcrypt-hashed keys\n- **Comprehensive Access Control**: Fine-grained permissions for all resources\n- **Rate Limiting**: Automatic rate limiting based on your API key tier\n- **Webhook Support**: Real-time event notifications via webhooks\n- **TypeScript SDK**: Official SDK for JavaScript/TypeScript applications\n\n## Get Started\n\n### Installation\n\nInstall the official TypeScript/JavaScript SDK:\n\n```bash\nnpm install @karmalicious/karma-api-js\n```\n\n### Quick Start\n\n```typescript\nimport { createKarmaClient } from '@karmalicious/karma-api-js'\n\nconst client = createKarmaClient({\n apiKey: 'karma_live_your_api_key_here',\n baseUrl: 'https://common-api.karma.life' // optional, defaults to production\n})\n\n// Fetch inventory items\nconst inventory = await client.inventory.getInventoryItems({\n locationId: 100,\n limit: 50\n})\n\n// Create an order\nconst order = await client.orders.createOrder({\n locationId: 100,\n orderChannel: 'POS',\n orderType: 'DINE_IN',\n orderDestination: 'KITCHEN',\n items: [\n { itemId: 123, quantity: 2 }\n ]\n})\n```\n\n### NPM Package\n\nView the package on npm: [@karmalicious/karma-api-js](https://www.npmjs.com/package/@karmalicious/karma-api-js)\n\n## Authentication\n\nAll endpoints require an API key in the `X-API-Key` header:\n\n```\nX-API-Key: karma_live_your_api_key_here\n```\n\nAPI keys can be managed through the Karma Merchant Dashboard.\n\n## Rate Limiting\n\nRate limits are applied per API key based on your subscription tier:\n- **Standard**: 1,000 requests/hour\n- **Premium**: 10,000 requests/hour\n- **Unlimited**: 100,000 requests/hour\n\nRate limit headers are included in all responses:\n- `X-RateLimit-Limit`: Total requests allowed\n- `X-RateLimit-Remaining`: Requests remaining\n- `X-RateLimit-Reset`: Unix timestamp when limit resets\n\n## Support\n\nFor questions or issues, contact the Karma team at hello@karma.life", "version": "20260131-1317-1", "contact": { "name": "Karma Team", "email": "hello@karma.life" } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key authentication. Format: `karma_live_*` or `karma_dev_*`" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT bearer token authentication for user-specific endpoints" } }, "schemas": {} }, "paths": { "/api/v1/booking-waitlist/by-code/{code}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/booking-waitlist/by-code/{code}/accept": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/booking-waitlist/by-code/{code}/decline": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/booking-waitlist/by-code/{code}/leave": { "delete": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/bookings/{id}/pre-order": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/bookings/by-code/{code}/members": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/locations/{locationId}/report-emails": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } } } }, "meta": { "type": "object" } } } } } } } }, "patch": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "items": { "type": "string" } } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/print-jobs/terminal-pre-check": { "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "locationId", "tabId", "terminalId", "content" ], "properties": { "locationId": { "type": "number" }, "tabId": { "type": "string", "format": "uuid" }, "terminalId": { "type": "string", "format": "uuid" }, "content": { "type": "object", "required": [ "tableName", "totalAmount", "lineItems" ], "properties": { "tableName": { "type": "string" }, "totalAmount": { "type": "number" }, "lineItems": { "type": "array", "items": { "type": "object", "required": [ "name", "price", "modifications" ], "properties": { "name": { "type": "string" }, "price": { "type": "number" }, "modifications": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "number" } } } } } } } } } } } } }, "required": true }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/printer-groups/{printerGroupId}/jobs/{jobId}/preview": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "printerGroupId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "jobId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/purchases/{purchaseIntentId}/picked-up": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "purchaseIntentId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/purchases/refund-reasons": { "get": { "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/tabs/{id}/anonymous-members": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/tabs/{tabId}/recent-purchase-intent": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "tabId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/tabs/close-all": { "post": { "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/terminals/{id}": { "put": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/alerts": { "get": { "summary": "List alerts", "tags": [ "Alerts" ], "description": "List alerts with optional filtering\n\n**Permissions:** 🔵 `alerts.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "string", "enum": [ "info", "warning", "error", "critical" ] }, "in": "query", "name": "severity", "required": false, "description": "Filter by severity" }, { "schema": { "type": "string", "enum": [ "active", "acknowledged", "resolved" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by status" }, { "schema": { "type": "string" }, "in": "query", "name": "alertType", "required": false, "description": "Filter by alert type" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "alerts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique alert ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID where alert occurred" }, "alertType": { "type": "string", "description": "Type of alert (e.g., \"printer_offline\", \"payment_failed\")" }, "severity": { "type": "string", "enum": [ "info", "warning", "error", "critical" ], "description": "Alert severity level" }, "title": { "type": "string", "description": "Alert title" }, "message": { "type": "string", "nullable": true, "description": "Detailed alert message" }, "details": { "type": "object", "nullable": true, "description": "Additional alert details" }, "stackTrace": { "type": "string", "nullable": true, "description": "Stack trace (for errors)" }, "context": { "type": "object", "nullable": true, "description": "Contextual information" }, "latestStatus": { "type": "string", "enum": [ "active", "acknowledged", "resolved" ], "description": "Current alert status" }, "resolvedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Resolution timestamp" }, "resolvedBy": { "type": "number", "nullable": true, "description": "User ID who resolved alert" }, "acknowledgedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Acknowledgement timestamp" }, "acknowledgedBy": { "type": "number", "nullable": true, "description": "User ID who acknowledged alert" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "alertType", "severity", "title", "latestStatus", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "alerts", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/alerts/{id}": { "get": { "summary": "Get alert", "tags": [ "Alerts" ], "description": "Get a single alert by ID\n\n**Permissions:** 🔵 `alerts.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Alert ID (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique alert ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID where alert occurred" }, "alertType": { "type": "string", "description": "Type of alert (e.g., \"printer_offline\", \"payment_failed\")" }, "severity": { "type": "string", "enum": [ "info", "warning", "error", "critical" ], "description": "Alert severity level" }, "title": { "type": "string", "description": "Alert title" }, "message": { "type": "string", "nullable": true, "description": "Detailed alert message" }, "details": { "type": "object", "nullable": true, "description": "Additional alert details" }, "stackTrace": { "type": "string", "nullable": true, "description": "Stack trace (for errors)" }, "context": { "type": "object", "nullable": true, "description": "Contextual information" }, "latestStatus": { "type": "string", "enum": [ "active", "acknowledged", "resolved" ], "description": "Current alert status" }, "resolvedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Resolution timestamp" }, "resolvedBy": { "type": "number", "nullable": true, "description": "User ID who resolved alert" }, "acknowledgedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Acknowledgement timestamp" }, "acknowledgedBy": { "type": "number", "nullable": true, "description": "User ID who acknowledged alert" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "alertType", "severity", "title", "latestStatus", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "patch": { "summary": "Update alert status", "tags": [ "Alerts" ], "description": "Update alert status (acknowledge or resolve)\n\n**Permissions:** 🟠 `alerts.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "acknowledged", "resolved" ], "description": "New status (cannot reopen once resolved)" } }, "required": [ "status" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Alert ID (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique alert ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID where alert occurred" }, "alertType": { "type": "string", "description": "Type of alert (e.g., \"printer_offline\", \"payment_failed\")" }, "severity": { "type": "string", "enum": [ "info", "warning", "error", "critical" ], "description": "Alert severity level" }, "title": { "type": "string", "description": "Alert title" }, "message": { "type": "string", "nullable": true, "description": "Detailed alert message" }, "details": { "type": "object", "nullable": true, "description": "Additional alert details" }, "stackTrace": { "type": "string", "nullable": true, "description": "Stack trace (for errors)" }, "context": { "type": "object", "nullable": true, "description": "Contextual information" }, "latestStatus": { "type": "string", "enum": [ "active", "acknowledged", "resolved" ], "description": "Current alert status" }, "resolvedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Resolution timestamp" }, "resolvedBy": { "type": "number", "nullable": true, "description": "User ID who resolved alert" }, "acknowledgedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Acknowledgement timestamp" }, "acknowledgedBy": { "type": "number", "nullable": true, "description": "User ID who acknowledged alert" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "alertType", "severity", "title", "latestStatus", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/internal/alerts/{id}/emit": { "post": { "summary": "Emit alert.created event", "tags": [ "Alerts" ], "description": "Emit alert.created Ably event for an existing alert (internal use only — called by printer-service)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Alert ID (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "emitted": { "type": "boolean" } }, "required": [ "emitted" ] } }, "required": [ "status", "data" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/analytics/batch": { "post": { "tags": [ "Analytics" ], "description": "Execute multiple analytics queries in parallel", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "queries": { "type": "array", "items": { "type": "object", "properties": { "queryType": { "type": "string", "enum": [ "sales_hourly", "channels", "top_items", "location_performance" ], "description": "Query type" }, "locationId": { "type": "number", "description": "Location ID" }, "startDate": { "type": "string", "format": "date-time", "description": "Start date" }, "endDate": { "type": "string", "format": "date-time", "description": "End date" }, "granularity": { "type": "string", "enum": [ "hour", "day", "week" ], "description": "Time granularity" }, "includeChildren": { "type": "boolean", "description": "Include child locations" }, "filters": { "type": "object", "description": "Additional filters" } }, "required": [ "queryType", "locationId" ] } } }, "required": [ "queries" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "charts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique chart ID" }, "title": { "type": "string", "description": "Chart title" }, "type": { "type": "string", "enum": [ "line", "bar", "area", "pie", "metric", "table" ], "description": "Chart visualization type" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Data point label" }, "value": { "type": "number", "description": "Numeric value (prices in cents)" }, "timestamp": { "type": "string", "format": "date-time", "description": "Optional timestamp" }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "orderCount": { "type": "number", "description": "Number of orders" }, "orders": { "type": "number", "description": "Number of orders (alias)" }, "itemId": { "type": "number", "description": "Item ID" }, "unitsSold": { "type": "number", "description": "Units sold" } }, "description": "Additional metadata" } }, "required": [ "label", "value" ] }, "description": "Chart data points" }, "metadata": { "type": "object", "properties": { "total": { "type": "number", "description": "Total value (cents)" }, "change": { "type": "number", "description": "Change from previous period" }, "changePercent": { "type": "number", "description": "Percentage change" }, "unit": { "type": "string", "description": "Unit of measurement" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } } }, "required": [ "id", "title", "type", "data" ] }, "description": "Successful query results" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "queryIndex": { "type": "number" }, "queryType": { "type": "string" }, "error": { "type": "string" } } }, "description": "Failed queries (if any)" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" }, "totalQueries": { "type": "number", "description": "Total queries requested" }, "successfulQueries": { "type": "number", "description": "Successful queries" }, "failedQueries": { "type": "number", "description": "Failed queries" } } } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/analytics/channels": { "get": { "tags": [ "Analytics" ], "description": "Get channel behavior metrics (POS, App, Kiosk, Delivery, QR)", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "End date (ISO 8601)" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeChildren", "required": false, "description": "Include child locations" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "orderChannel": { "type": "string", "description": "Channel name (POS, App, QR, etc.)" }, "orderCount": { "type": "number", "description": "Number of orders" }, "revenue": { "type": "number", "description": "Total revenue in cents" }, "averageOrderValue": { "type": "number", "description": "Average order value in cents" }, "uniqueCustomers": { "type": "number", "description": "Unique customer count" }, "conversionRate": { "type": "number", "nullable": true, "description": "Conversion rate (null if unavailable)" } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" }, "cacheHit": { "type": "boolean" }, "bytesProcessed": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/analytics/dashboard": { "get": { "tags": [ "Analytics" ], "description": "Get comprehensive dashboard metrics in a single call. Returns sales inc/ex VAT, orders, products, tips, refunds, discounts, AOV, VAT breakdown, time series, top products, top categories, and channel breakdown.", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "End date (ISO 8601)" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeChildren", "required": false, "description": "Include child locations" }, { "schema": { "type": "string", "enum": [ "hour", "day", "week" ], "default": "hour" }, "in": "query", "name": "granularity", "required": false, "description": "Time series granularity" }, { "schema": { "type": "string" }, "in": "query", "name": "productSearch", "required": false, "description": "Search filter for product titles" }, { "schema": { "type": "number", "default": 10 }, "in": "query", "name": "productLimit", "required": false, "description": "Max products to return (default 10, max 500)" }, { "schema": { "type": "string" }, "in": "query", "name": "tableGroupIds", "required": false, "description": "Comma-separated list of table group IDs (storefront_qr_code_groups.id) to restrict results to. When set, excludes orders without a QR code (e.g. pickup, delivery)." }, { "schema": { "type": "string" }, "in": "query", "name": "costCenterIds", "required": false, "description": "Comma-separated list of cost center IDs (cost_centers.id) to restrict results to. Matches on COALESCE(tabs.cost_center_id, storefront_qr_codes.cost_center_id) — tab override beats table default. Orders without a cost center are excluded when this filter is active." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "metrics": { "type": "object", "properties": { "salesIncVat": { "type": "number", "description": "Gross sales including VAT (cents) — pre-discount" }, "salesExVat": { "type": "number", "description": "Gross sales excluding VAT (cents) — pre-discount" }, "totalVat": { "type": "number", "description": "Total VAT amount (cents)" }, "netSalesIncVat": { "type": "number", "description": "Net sales including VAT (cents) — post-discount, post-refund, matches SIE" }, "netSalesExVat": { "type": "number", "description": "Net sales excluding VAT (cents) — post-discount, post-refund, matches SIE" }, "netTotalVat": { "type": "number", "description": "Net VAT amount (cents)" }, "orderCount": { "type": "number", "description": "Total number of orders" }, "productCount": { "type": "number", "description": "Total products sold" }, "tipsTotal": { "type": "number", "description": "Total tips (cents)" }, "refundCount": { "type": "number", "description": "Number of refunds" }, "refundTotal": { "type": "number", "description": "Total refunded amount (cents)" }, "discountCount": { "type": "number", "description": "Number of discounted line items" }, "discountTotal": { "type": "number", "description": "Total discounts applied (cents)" }, "aov": { "type": "number", "description": "Average order value (cents)" } } }, "vatBreakdown": { "type": "array", "items": { "type": "object", "properties": { "vatRateBasisPoints": { "type": "number", "description": "VAT rate in basis points (e.g. 2500 = 25%)" }, "salesIncVat": { "type": "number", "description": "Sales including VAT for this rate (cents)" }, "vatAmount": { "type": "number", "description": "VAT amount for this rate (cents)" }, "salesExVat": { "type": "number", "description": "Sales excluding VAT for this rate (cents)" }, "orderCount": { "type": "number", "description": "Orders with items at this rate" } } } }, "timeSeries": { "type": "array", "description": "Time-series buckets with two parallel axes: payment time (bucketed on purchases.purchased_at — matches SIE/accounting) and kitchen time (bucketed on kitchen_dispatch_items.created_at with fallback to purchased_at — when items were sent to the kitchen). Both series cover the same set of confirmed purchases, rebucketed on different timestamps. The kitchen series filters on kitchen-time too, so late payments can retroactively shift it.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Time label (e.g. \"14:00\" or \"2025-03-25\")" }, "paymentSalesIncVat": { "type": "number", "description": "Payment-time axis: sales inc VAT (cents)" }, "paymentSalesExVat": { "type": "number", "description": "Payment-time axis: sales ex VAT (cents)" }, "paymentOrders": { "type": "number", "description": "Payment-time axis: number of orders" }, "kitchenSalesIncVat": { "type": "number", "description": "Kitchen-time axis: sales inc VAT (cents)" }, "kitchenSalesExVat": { "type": "number", "description": "Kitchen-time axis: sales ex VAT (cents)" }, "kitchenOrders": { "type": "number", "description": "Kitchen-time axis: number of orders" } } } }, "topProducts": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product title" }, "originItemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "unitsSold": { "type": "number", "description": "Total units sold" }, "revenue": { "type": "number", "description": "Total revenue inc VAT (cents)" }, "revenueExVat": { "type": "number", "description": "Total revenue ex VAT (cents)" } } } }, "topCategories": { "type": "array", "items": { "type": "object", "properties": { "categoryKey": { "type": "string", "description": "Category tag key" }, "categoryName": { "type": "string", "description": "Human-readable category name" }, "unitsSold": { "type": "number", "description": "Total units sold" }, "revenue": { "type": "number", "description": "Total revenue inc VAT (cents)" }, "revenueExVat": { "type": "number", "description": "Total revenue ex VAT (cents)" } } } }, "channels": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string", "description": "Channel name (POS, ONLINE, KIOSK, etc.)" }, "orderCount": { "type": "number", "description": "Orders via this channel" }, "revenue": { "type": "number", "description": "Revenue inc VAT (cents)" }, "revenueExVat": { "type": "number", "description": "Revenue ex VAT (cents)" }, "aov": { "type": "number", "description": "Average order value (cents)" }, "uniqueCustomers": { "type": "number", "description": "Unique customer count" } } } }, "topStaff": { "type": "array", "items": { "type": "object", "properties": { "retailUserId": { "type": "number", "description": "Staff user ID" }, "name": { "type": "string", "description": "Staff user name" }, "orderCount": { "type": "number", "description": "Orders handled" }, "revenue": { "type": "number", "description": "Revenue inc VAT (cents)" }, "revenueExVat": { "type": "number", "description": "Revenue ex VAT (cents)" } } } }, "topProductsByCategory": { "type": "array", "description": "Top products grouped by primary category (CATEGORY_PRIMARY tag). Returns up to 5 products per category, sorted by revenue.", "items": { "type": "object", "properties": { "categoryKey": { "type": "string", "description": "Category tag key" }, "categoryName": { "type": "string", "description": "Human-readable category name" }, "products": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Product title" }, "originItemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "unitsSold": { "type": "number", "description": "Total units sold" }, "revenue": { "type": "number", "description": "Total revenue inc VAT (cents)" }, "revenueExVat": { "type": "number", "description": "Total revenue ex VAT (cents)" } } } } } } }, "costCenters": { "type": "array", "description": "Revenue grouped by COALESCE(tab.cost_center_id, qr_code.cost_center_id). Rows with no cost center are returned with costCenterId=null.", "items": { "type": "object", "properties": { "costCenterId": { "type": "number", "nullable": true, "description": "Cost center ID (null when no cost center is associated)" }, "name": { "type": "string", "nullable": true, "description": "Cost center display name (null when costCenterId is null)" }, "orderCount": { "type": "number", "description": "Orders attributed to this cost center" }, "unitsSold": { "type": "number", "description": "Total units sold" }, "revenue": { "type": "number", "description": "Revenue inc VAT (cents)" }, "revenueExVat": { "type": "number", "description": "Revenue ex VAT (cents)" } } } }, "tableGroups": { "type": "array", "description": "Revenue grouped by storefront_qr_codes.group_id. Orders without a QR code (pickup, delivery, etc.) are returned with tableGroupId=null.", "items": { "type": "object", "properties": { "tableGroupId": { "type": "number", "nullable": true, "description": "Table group ID (null for orders without a QR code)" }, "name": { "type": "string", "nullable": true, "description": "Table group display name (null when tableGroupId is null)" }, "orderCount": { "type": "number", "description": "Orders attributed to this table group" }, "unitsSold": { "type": "number", "description": "Total units sold" }, "revenue": { "type": "number", "description": "Revenue inc VAT (cents)" }, "revenueExVat": { "type": "number", "description": "Revenue ex VAT (cents)" } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/analytics/datastream-latency": { "get": { "tags": [ "Analytics" ], "description": "Get DataStream latency metrics", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "avgLatencyMs": { "type": "number", "description": "Average latency in milliseconds" }, "p50LatencyMs": { "type": "number", "description": "P50 latency in milliseconds" }, "p95LatencyMs": { "type": "number", "description": "P95 latency in milliseconds" }, "p99LatencyMs": { "type": "number", "description": "P99 latency in milliseconds" }, "lastOrderLatencyMs": { "type": "number", "nullable": true, "description": "Last order latency in milliseconds" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" }, "cacheHit": { "type": "boolean" }, "bytesProcessed": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/analytics/drilldown": { "get": { "tags": [ "Analytics" ], "description": "Get drill-down analytics (Location → Hour → Item)", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "End date (ISO 8601)" }, { "schema": { "type": "number", "minimum": 0, "maximum": 23 }, "in": "query", "name": "hour", "required": false, "description": "Hour of day (0-23)" }, { "schema": { "type": "number" }, "in": "query", "name": "itemId", "required": false, "description": "Item ID for detailed orders" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "location", "hour", "item" ], "description": "Current drill-down level" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Data point label" }, "value": { "type": "number", "description": "Numeric value (prices in cents)" }, "timestamp": { "type": "string", "format": "date-time", "description": "Optional timestamp" }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "orderCount": { "type": "number", "description": "Number of orders" }, "orders": { "type": "number", "description": "Number of orders (alias)" }, "itemId": { "type": "number", "description": "Item ID" }, "unitsSold": { "type": "number", "description": "Units sold" } }, "description": "Additional metadata" } }, "required": [ "label", "value" ] }, "description": "Drill-down data points" }, "metadata": { "type": "object", "properties": { "parentLocationId": { "type": "number", "description": "Parent location ID" }, "parentLocationName": { "type": "string", "description": "Parent location name" }, "hour": { "type": "number", "description": "Hour of day (if drilling into hour)" }, "itemId": { "type": "number", "description": "Item ID (if drilling into item)" } } } }, "required": [ "level", "data", "metadata" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/analytics/locations": { "get": { "tags": [ "Analytics" ], "description": "Get location performance with hierarchy", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Parent location ID" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "End date (ISO 8601)" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeChildren", "required": false, "description": "Include child locations" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID" }, "locationName": { "type": "string", "description": "Location name" }, "totalSales": { "type": "number", "description": "Total sales in cents" }, "totalOrders": { "type": "number", "description": "Total orders" }, "averageOrderValue": { "type": "number", "description": "Average order value in cents" }, "hourlyBreakdown": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Data point label" }, "value": { "type": "number", "description": "Numeric value (prices in cents)" }, "timestamp": { "type": "string", "format": "date-time", "description": "Optional timestamp" }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "orderCount": { "type": "number", "description": "Number of orders" }, "orders": { "type": "number", "description": "Number of orders (alias)" }, "itemId": { "type": "number", "description": "Item ID" }, "unitsSold": { "type": "number", "description": "Units sold" } }, "description": "Additional metadata" } }, "required": [ "label", "value" ] }, "description": "Hourly sales breakdown" }, "alerts": { "type": "array", "items": { "type": "string" }, "description": "Performance alerts" } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" }, "cacheHit": { "type": "boolean" }, "bytesProcessed": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/analytics/overview": { "get": { "tags": [ "Analytics" ], "description": "Get overview dashboard with summary and charts", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "End date (ISO 8601)" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeChildren", "required": false, "description": "Include child locations" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "totalSales": { "type": "number", "description": "Total sales in cents" }, "totalOrders": { "type": "number", "description": "Total orders" }, "averageOrderValue": { "type": "number", "description": "Average order value in cents" }, "topChannel": { "type": "string", "description": "Top performing channel" }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update" } } }, "charts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique chart ID" }, "title": { "type": "string", "description": "Chart title" }, "type": { "type": "string", "enum": [ "line", "bar", "area", "pie", "metric", "table" ], "description": "Chart visualization type" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Data point label" }, "value": { "type": "number", "description": "Numeric value (prices in cents)" }, "timestamp": { "type": "string", "format": "date-time", "description": "Optional timestamp" }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "orderCount": { "type": "number", "description": "Number of orders" }, "orders": { "type": "number", "description": "Number of orders (alias)" }, "itemId": { "type": "number", "description": "Item ID" }, "unitsSold": { "type": "number", "description": "Units sold" } }, "description": "Additional metadata" } }, "required": [ "label", "value" ] }, "description": "Chart data points" }, "metadata": { "type": "object", "properties": { "total": { "type": "number", "description": "Total value (cents)" }, "change": { "type": "number", "description": "Change from previous period" }, "changePercent": { "type": "number", "description": "Percentage change" }, "unit": { "type": "string", "description": "Unit of measurement" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } } }, "required": [ "id", "title", "type", "data" ] }, "description": "Dashboard charts" }, "dataStreamLatency": { "type": "number", "nullable": true, "description": "DataStream latency in milliseconds" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/analytics/sales": { "get": { "tags": [ "Analytics" ], "description": "Get sales metrics with hourly breakdown", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "End date (ISO 8601)" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeChildren", "required": false, "description": "Include child locations" }, { "schema": { "type": "string", "enum": [ "hour", "day", "week" ], "default": "hour" }, "in": "query", "name": "granularity", "required": false, "description": "Time granularity" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "totalSales": { "type": "number", "description": "Total sales in cents" }, "totalOrders": { "type": "number", "description": "Total order count" }, "totalItemsSold": { "type": "number", "description": "Total items sold count" }, "averageOrderValue": { "type": "number", "description": "Average order value in cents" }, "hourlySales": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Data point label" }, "value": { "type": "number", "description": "Numeric value (prices in cents)" }, "timestamp": { "type": "string", "format": "date-time", "description": "Optional timestamp" }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "orderCount": { "type": "number", "description": "Number of orders" }, "orders": { "type": "number", "description": "Number of orders (alias)" }, "itemId": { "type": "number", "description": "Item ID" }, "unitsSold": { "type": "number", "description": "Units sold" } }, "description": "Additional metadata" } }, "required": [ "label", "value" ] }, "description": "Hourly/daily sales breakdown" }, "topItems": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Data point label" }, "value": { "type": "number", "description": "Numeric value (prices in cents)" }, "timestamp": { "type": "string", "format": "date-time", "description": "Optional timestamp" }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "orderCount": { "type": "number", "description": "Number of orders" }, "orders": { "type": "number", "description": "Number of orders (alias)" }, "itemId": { "type": "number", "description": "Item ID" }, "unitsSold": { "type": "number", "description": "Units sold" } }, "description": "Additional metadata" } }, "required": [ "label", "value" ] }, "description": "Top selling items" }, "channelBreakdown": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Data point label" }, "value": { "type": "number", "description": "Numeric value (prices in cents)" }, "timestamp": { "type": "string", "format": "date-time", "description": "Optional timestamp" }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "orderCount": { "type": "number", "description": "Number of orders" }, "orders": { "type": "number", "description": "Number of orders (alias)" }, "itemId": { "type": "number", "description": "Item ID" }, "unitsSold": { "type": "number", "description": "Units sold" } }, "description": "Additional metadata" } }, "required": [ "label", "value" ] }, "description": "Sales breakdown by channel" } }, "required": [ "totalSales", "totalOrders", "totalItemsSold", "averageOrderValue", "hourlySales", "topItems", "channelBreakdown" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" }, "cacheHit": { "type": "boolean", "description": "Whether result was cached" }, "bytesProcessed": { "type": "number", "description": "BigQuery bytes processed" } } } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/analytics/tips-by-staff": { "get": { "tags": [ "Analytics" ], "description": "Get tips totals per staff for the period. Tips are split proportionally across staff based on each staff member's share of committed-item revenue on the same tab. Unattributed share (no staff on tab) is returned with retailUserId = null.", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Start date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "End date (ISO 8601)" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeChildren", "required": false, "description": "Include child locations" }, { "schema": { "type": "string" }, "in": "query", "name": "tableGroupIds", "required": false, "description": "Comma-separated list of table group IDs to restrict to." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "tipsTotal": { "type": "number", "description": "Total tips across all purchases (cents)" }, "tippedOrderCount": { "type": "number", "description": "Number of purchases that included a tip" }, "orderCount": { "type": "number", "description": "Total confirmed purchases in range" }, "averageTip": { "type": "number", "description": "Average tip per tipped purchase (cents)" } } }, "staff": { "type": "array", "items": { "type": "object", "properties": { "retailUserId": { "type": [ "null", "number" ], "description": "Staff user ID, null = unattributed/self-service" }, "name": { "type": [ "null", "string" ], "description": "Staff user name" }, "tipsTotal": { "type": "number", "description": "Allocated tips for this staff (cents)" }, "orderCount": { "type": "number", "description": "Tipped purchases this staff received a share of" } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings": { "get": { "summary": "List bookings", "tags": [ "Bookings" ], "description": "List bookings with optional filtering and pagination\n\n**Permissions:** 🔵 `bookings.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "string" }, "in": "query", "name": "tableId", "required": false, "description": "Filter by table ID" }, { "schema": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ] }, "in": "query", "name": "status", "required": false, "description": "Booking status" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "bookingDate", "required": false, "description": "Filter by exact date" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Filter by start date (inclusive)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "Filter by end date (inclusive)" }, { "schema": { "type": "number" }, "in": "query", "name": "userId", "required": false, "description": "Filter by user ID" }, { "schema": { "type": "string" }, "in": "query", "name": "confirmationCode", "required": false, "description": "Filter by confirmation code" }, { "schema": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ] }, "in": "query", "name": "bookingSource", "required": false, "description": "Source of the booking" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "bookings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "bookings", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create booking", "tags": [ "Bookings" ], "description": "Create a new booking. The response always includes a linked `tab` (the booking creates a `pre_arrival` tab atomically) so integrations can begin committing orders against `data.tab.id` immediately. Pass `seatImmediately: true` in the body to atomically transition the new booking to `seated` and open its tab in a single call (recommended for walk-in flows). When `seatImmediately` is true and the booking has unpaid required items or its table already has an open tab, the booking is still created but seating is skipped and `seatWarning` is returned.\n\n**Permissions:** 🟢 `bookings.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": [ "string", "null" ], "format": "uuid", "description": "Legacy single-resource ID (kept for backwards compat). When `tableIds` is provided it takes precedence; otherwise `tableId` is folded into a single-element resource set." }, "tableIds": { "type": "array", "description": "Multi-resource booking (Phase 40). Array of storefront_qr_code UUIDs to reserve. The first entry is treated as primary. When provided, supersedes `tableId`.", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Tab strategy locked in at booking time (Phase 40). `single` (default) — one shared tab across all reserved resources. `per_resource` — one tab per resource opened on seat.", "default": "single" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking" }, "startTime": { "type": "string", "description": "Start time (HH:MM)" }, "endTime": { "type": "string", "description": "End time (HH:MM)" }, "timezone": { "type": "string", "description": "Timezone (e.g., Europe/Stockholm)" }, "primaryUserId": { "type": [ "number", "null" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "description": "Guest special requests" }, "internalNotes": { "type": "string", "description": "Staff-only notes" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "description": "Deposit amount in cents" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "guestName": { "type": "string", "description": "Guest contact name" }, "guestEmail": { "type": "string", "description": "Guest contact email" }, "guestPhone": { "type": "string", "description": "Guest contact phone" }, "seatImmediately": { "type": "boolean", "description": "If true, immediately seat the booking after creation. Requires a table assignment. Will check for conflicting open tabs on the table." } }, "required": [ "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" }, "tab": { "type": "object", "description": "Linked tab created with the booking. State is `pre_arrival` for normal bookings, `started` when seatImmediately=true succeeds, or `initiated` for walk-ins.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tab UUID — use this to commit orders against the tab." }, "tabMemberId": { "type": "string", "format": "uuid", "nullable": true, "description": "Tab member UUID for the primary guest (null when the booking has no primary user, e.g. walk-ins without a guest record)." } } }, "requiresPayment": { "type": "boolean", "description": "True if the booking has required items (from a booking group) that need to be paid before the guest can be seated." }, "totalRequiredItemsCents": { "type": "number", "description": "Total cents of required items added to the linked tab. Zero when the booking has no required items." }, "seated": { "type": "boolean", "description": "Only present when `seatImmediately` was passed in the request body. True if the booking was successfully transitioned to `seated` and its tab is now open." }, "seatWarning": { "type": "string", "description": "Only present when `seatImmediately` was passed and seating was skipped (e.g. payment required, or the table already has another open tab). The booking is still created." } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}": { "get": { "summary": "Get booking", "tags": [ "Bookings" ], "description": "Get a single booking by ID\n\n**Permissions:** 🔵 `bookings.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update booking", "tags": [ "Bookings" ], "description": "Update an existing booking\n\n**Permissions:** 🟠 `bookings.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Legacy single-resource ID (kept for backwards compat). When `tableIds` is provided it takes precedence; otherwise `tableId` replaces the booking resource set with a single entry." }, "tableIds": { "type": "array", "description": "Multi-resource booking (Phase 40). Array of storefront_qr_code UUIDs that replaces the booking resource set. The first entry is treated as primary. When provided, supersedes `tableId`.", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Change the booking tab strategy pre-seat (Phase 40). Staff can flip between `single` and `per_resource` until the booking is seated." }, "confirmRemoveActiveTab": { "type": "boolean", "default": false, "description": "Gates the destructive path in R8 (Phase 40): when shrinking `tableIds` would remove a resource that already has an active tab, the API only proceeds if this flag is true. Without it, the update is rejected with a 409 so staff can confirm." }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking" }, "startTime": { "type": "string", "description": "Start time" }, "endTime": { "type": "string", "description": "End time" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "description": "Guest special requests" }, "internalNotes": { "type": "string", "description": "Staff-only notes" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "description": "Deposit amount in cents" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/cancel": { "post": { "summary": "Cancel booking", "tags": [ "Bookings" ], "description": "Cancel a booking\n\n**Permissions:** ⚪ `bookings.manage`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Cancellation reason" }, "closeTab": { "type": "boolean", "description": "Whether to close the linked pre-arrival tab. Defaults to true." } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/check-in": { "post": { "summary": "Confirm booking", "tags": [ "Bookings" ], "description": "Confirm a pending booking\n\n**Permissions:** ⚪ `bookings.manage`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/complete": { "post": { "summary": "Complete booking", "tags": [ "Bookings" ], "description": "Mark a booking as completed\n\n**Permissions:** ⚪ `bookings.manage`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/confirm": { "post": { "summary": "Confirm booking", "tags": [ "Bookings" ], "description": "Confirm a pending booking\n\n**Permissions:** ⚪ `bookings.manage`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/history": { "get": { "summary": "Get booking history", "tags": [ "Bookings" ], "description": "Get audit log/history for a booking\n\n**Permissions:** 🔵 `bookings.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Audit log ID" }, "bookingId": { "type": "string", "format": "uuid", "description": "Booking ID" }, "eventType": { "type": "string", "description": "Event type" }, "eventData": { "type": "object", "description": "Event details" }, "userId": { "type": "number", "nullable": true, "description": "Guest user ID (if applicable)" }, "retailerUserId": { "type": "number", "nullable": true, "description": "Staff user ID (if applicable)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Event timestamp" } }, "required": [ "id", "bookingId", "eventType", "eventData", "createdAt" ] } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/members": { "get": { "summary": "List booking members", "tags": [ "Bookings" ], "description": "List members of a booking\n\n**Permissions:** 🔵 `bookings.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bookingId": { "type": "string", "format": "uuid" }, "userId": { "type": [ "null", "number" ] }, "isPrimary": { "type": "boolean" }, "guestName": { "type": "string", "nullable": true }, "guestEmail": { "type": "string", "nullable": true }, "rsvpStatus": { "type": "string", "enum": [ "pending", "accepted", "declined" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "bookingId", "isPrimary", "createdAt" ] } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Add booking member", "tags": [ "Bookings" ], "description": "Add a member to a booking\n\n**Permissions:** ⚪ `bookings.manage`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "number" }, "guestName": { "type": "string" }, "guestEmail": { "type": "string" }, "rsvpStatus": { "type": "string", "enum": [ "pending", "accepted", "declined" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bookingId": { "type": "string", "format": "uuid" }, "userId": { "type": [ "null", "number" ] }, "isPrimary": { "type": "boolean" }, "guestName": { "type": "string", "nullable": true }, "guestEmail": { "type": "string", "nullable": true }, "rsvpStatus": { "type": "string", "enum": [ "pending", "accepted", "declined" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "bookingId", "isPrimary", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/members/{memberId}": { "patch": { "summary": "Update booking member", "tags": [ "Bookings" ], "description": "Update a booking member RSVP status\n\n**Permissions:** ⚪ `bookings.manage`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rsvpStatus": { "type": "string", "enum": [ "pending", "accepted", "declined" ] } }, "required": [ "rsvpStatus" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "memberId", "required": true, "description": "Member ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bookingId": { "type": "string", "format": "uuid" }, "userId": { "type": [ "null", "number" ] }, "isPrimary": { "type": "boolean" }, "guestName": { "type": "string", "nullable": true }, "guestEmail": { "type": "string", "nullable": true }, "rsvpStatus": { "type": "string", "enum": [ "pending", "accepted", "declined" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "bookingId", "isPrimary", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Remove booking member", "tags": [ "Bookings" ], "description": "Remove a non-primary member from a booking\n\n**Permissions:** ⚪ `bookings.manage`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "memberId", "required": true, "description": "Member ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/no-show": { "post": { "summary": "Mark no-show", "tags": [ "Bookings" ], "description": "Mark a booking as no-show\n\n**Permissions:** ⚪ `bookings.manage`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/seat": { "post": { "summary": "Seat booking", "tags": [ "Bookings" ], "description": "Mark a booking as seated. Optionally create a linked tab for the booking.\n\n**Permissions:** ⚪ `bookings.manage`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tabId": { "type": "string", "format": "uuid", "description": "Optional existing tab ID to link" }, "createTab": { "type": "boolean", "default": false, "description": "If true, creates a new tab linked to this booking. The tab will be associated with the booking's primary user and table." } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" }, "tab": { "type": "object", "nullable": true, "description": "Linked tab information (present when booking has a pre_arrival or active tab)", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "tabMemberId": { "type": "string", "format": "uuid", "nullable": true, "description": "Tab member UUID for the primary guest" } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/split": { "post": { "summary": "Split booking into per-resource tabs", "tags": [ "Bookings" ], "description": "Phase 40 R6 — convert a seated `single`-strategy multi-resource booking into per-resource tabs. Creates N-1 new tabs (one per non-primary resource that does not yet have its own tab). The existing primary tab and any items on it are preserved. `bookings.default_tab_strategy` is NOT mutated — it records the original choice. Idempotent: re-running only creates tabs for resources missing one.\n\n**Permissions:** ⚪ `bookings.manage`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabs": { "type": "array", "description": "All non-terminal tabs linked to the booking after the split. Includes the pre-existing primary tab plus one entry per newly-created sibling tab.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid this tab is anchored on" }, "isPrimary": { "type": "boolean", "description": "True for the booking's primary resource tab" }, "created": { "type": "boolean", "description": "True if this tab was created by the split call; false if it already existed" } }, "required": [ "id", "qrCodeId", "isPrimary", "created" ] } }, "createdCount": { "type": "integer", "description": "Number of NEW tabs created by this split call (0 on idempotent re-runs)" } }, "required": [ "tabs", "createdCount" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/unseat": { "post": { "summary": "Unseat booking", "tags": [ "Bookings" ], "description": "Undo a seat operation. Reverts the booking to its prior status (checked_in or confirmed), puts the linked tab back to pre_arrival, and reverses all kitchen dispatches advanced by seating. Refuses if purchases exist, additional orders were placed, or any dispatch is past accepted.\n\n**Permissions:** ⚪ `bookings.manage`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why the booking is being unseated (shown on the kitchen correction ticket)." } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/by-code/{code}/cancel": { "post": { "summary": "Cancel booking by confirmation code", "tags": [ "Bookings" ], "description": "Public endpoint: cancel a booking using confirmation code (no auth required)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Cancellation reason" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true, "description": "Booking confirmation code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/rsvp": { "post": { "summary": "RSVP to booking", "tags": [ "Bookings" ], "description": "Public endpoint: RSVP to a booking using confirmation code (no auth required)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmationCode": { "type": "string" }, "guestName": { "type": "string" }, "guestEmail": { "type": "string" }, "rsvpStatus": { "type": "string", "enum": [ "pending", "accepted", "declined" ] } }, "required": [ "confirmationCode", "guestName", "rsvpStatus" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bookingId": { "type": "string", "format": "uuid" }, "userId": { "type": [ "null", "number" ] }, "isPrimary": { "type": "boolean" }, "guestName": { "type": "string", "nullable": true }, "guestEmail": { "type": "string", "nullable": true }, "rsvpStatus": { "type": "string", "enum": [ "pending", "accepted", "declined" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "bookingId", "isPrimary", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bookingId": { "type": "string", "format": "uuid" }, "userId": { "type": [ "null", "number" ] }, "isPrimary": { "type": "boolean" }, "guestName": { "type": "string", "nullable": true }, "guestEmail": { "type": "string", "nullable": true }, "rsvpStatus": { "type": "string", "enum": [ "pending", "accepted", "declined" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "bookingId", "isPrimary", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/booking-availability": { "get": { "summary": "Get availability", "tags": [ "Bookings" ], "description": "Get available booking slots for a date and party size\n\n**Permissions:** 🔵 `bookings.read`", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "date", "required": true, "description": "Date to check availability" }, { "schema": { "type": "number", "minimum": 1 }, "in": "query", "name": "partySize", "required": true, "description": "Number of guests" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "bookingGroupId", "required": false, "description": "Optional booking group ID to filter availability by group schedule, table pool, and settings" }, { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "partySize": { "type": "number" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique slot ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID" }, "locationId": { "type": "number", "description": "Location ID" }, "slotDate": { "type": "string", "format": "date", "description": "Date of the slot" }, "startTime": { "type": "string", "description": "Start time" }, "endTime": { "type": "string", "description": "End time" }, "durationMinutes": { "type": "number", "description": "Duration in minutes" }, "maxCapacity": { "type": "number", "description": "Maximum capacity" }, "currentBookings": { "type": "number", "description": "Current number of bookings" }, "status": { "type": "string", "enum": [ "available", "partially_booked", "fully_booked", "blocked" ], "description": "Slot status" }, "predictedDemandScore": { "type": "number", "nullable": true, "description": "AI demand prediction (0.00-1.00)" }, "optimalPartySizeMin": { "type": "number", "nullable": true, "description": "AI-suggested minimum party size" }, "optimalPartySizeMax": { "type": "number", "nullable": true, "description": "AI-suggested maximum party size" }, "scheduleId": { "type": "string", "format": "uuid", "nullable": true, "description": "Schedule that generated this slot" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "locationId", "slotDate", "startTime", "endTime", "durationMinutes", "maxCapacity", "currentBookings", "status", "createdAt" ] } }, "tables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "minCapacity": { "type": "number" }, "maxCapacity": { "type": "number" }, "availableSlots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique slot ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID" }, "locationId": { "type": "number", "description": "Location ID" }, "slotDate": { "type": "string", "format": "date", "description": "Date of the slot" }, "startTime": { "type": "string", "description": "Start time" }, "endTime": { "type": "string", "description": "End time" }, "durationMinutes": { "type": "number", "description": "Duration in minutes" }, "maxCapacity": { "type": "number", "description": "Maximum capacity" }, "currentBookings": { "type": "number", "description": "Current number of bookings" }, "status": { "type": "string", "enum": [ "available", "partially_booked", "fully_booked", "blocked" ], "description": "Slot status" }, "predictedDemandScore": { "type": "number", "nullable": true, "description": "AI demand prediction (0.00-1.00)" }, "optimalPartySizeMin": { "type": "number", "nullable": true, "description": "AI-suggested minimum party size" }, "optimalPartySizeMax": { "type": "number", "nullable": true, "description": "AI-suggested maximum party size" }, "scheduleId": { "type": "string", "format": "uuid", "nullable": true, "description": "Schedule that generated this slot" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "locationId", "slotDate", "startTime", "endTime", "durationMinutes", "maxCapacity", "currentBookings", "status", "createdAt" ] } } } } } }, "required": [ "date", "partySize", "slots" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/bookings/by-table": { "get": { "summary": "Get bookings by table", "tags": [ "Bookings" ], "description": "Get bookings grouped by table for a specific date. Useful for table map display in POS.\n\n**Permissions:** 🔵 `bookings.read`", "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "date", "required": true, "description": "Date to fetch bookings for (YYYY-MM-DD)" }, { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "object", "properties": { "tableId": { "type": "string", "format": "uuid", "description": "Table/QR code UUID" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" }, "bookings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "description": "Bookings for this table" } }, "required": [ "tableId", "bookings" ] } } }, "required": [ "tables" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/bookings/{id}/lock": { "patch": { "summary": "Toggle booking resource lock", "tags": [ "Bookings - Optimization" ], "description": "Lock or unlock a booking to its assigned table. Locked bookings will not be moved by the optimizer.\n\n**Permissions:** ⚪ `bookings.manage`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locked": { "type": "boolean", "description": "Whether to lock (true) or unlock (false) the booking" } }, "required": [ "locked" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Booking ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/bookings/optimize": { "post": { "summary": "Optimize booking table assignments", "tags": [ "Bookings - Optimization" ], "description": "Run the booking optimization algorithm to improve table utilization. Use dryRun=true to preview changes without applying them.\n\n**Permissions:** ⚪ `bookings.manage`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "dryRun": { "type": "boolean", "default": true, "description": "If true, only preview changes without applying them" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "date", "required": true, "description": "Date to optimize (YYYY-MM-DD)" }, { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "bookingId": { "type": "string", "format": "uuid", "description": "Booking ID" }, "guestName": { "type": "string", "nullable": true, "description": "Guest name" }, "partySize": { "type": "number", "description": "Party size" }, "fromTableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Original table ID" }, "fromTableName": { "type": "string", "nullable": true, "description": "Original table name" }, "toTableId": { "type": "string", "format": "uuid", "description": "New table ID" }, "toTableName": { "type": "string", "description": "New table name" }, "reason": { "type": "string", "description": "Reason for the change" } }, "required": [ "bookingId", "partySize", "toTableId", "toTableName", "reason" ] }, "description": "List of proposed or applied changes" }, "stats": { "type": "object", "properties": { "totalBookings": { "type": "number", "description": "Total bookings for the date" }, "optimizedCount": { "type": "number", "description": "Number of bookings moved" }, "lockedCount": { "type": "number", "description": "Number of locked bookings (not moved)" }, "tablesFreed": { "type": "number", "description": "Number of tables freed up" }, "utilizationImprovement": { "type": "number", "description": "Improvement in table utilization (percentage)" } }, "required": [ "totalBookings", "optimizedCount", "lockedCount", "tablesFreed", "utilizationImprovement" ] } }, "required": [ "changes", "stats" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/booking-settings": { "get": { "summary": "Get location booking settings", "tags": [ "Bookings - Settings" ], "description": "Get booking settings for a location. Creates default settings if none exist.\n\n**Permissions:** 🔵 `bookings.read`", "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Settings ID" }, "locationId": { "type": "number", "description": "Location ID" }, "bufferMinutes": { "type": "number", "description": "Time buffer between bookings on same table (minutes)" }, "defaultDurationMinutes": { "type": "number", "description": "Default booking duration (minutes)" }, "autoOptimizeEnabled": { "type": "boolean", "description": "Whether to auto-optimize table assignments" }, "maxPartySize": { "type": "number", "description": "Maximum party size allowed for online bookings" }, "minAdvanceHours": { "type": "number", "description": "Minimum hours in advance a booking must be made" }, "maxAdvanceDays": { "type": "number", "description": "Maximum days in advance a booking can be made" }, "allowedPartySizes": { "type": "array", "items": { "type": "number" }, "description": "Specific party sizes allowed (empty = all sizes up to max)" }, "operatingHours": { "type": "object", "description": "Per-day booking hours override" }, "slotIntervalMinutes": { "type": "number", "description": "Time slot interval (minutes)" }, "overbookingBufferPercentage": { "type": "number", "description": "Overbooking buffer percentage" }, "confirmationMode": { "type": "string", "enum": [ "instant", "request_based" ], "description": "Booking confirmation mode" }, "autoNoShowDelayMinutes": { "type": [ "null", "number" ], "description": "Minutes after start before auto no-show (null = disabled)" }, "cancellationPolicyHours": { "type": [ "null", "number" ], "description": "Free cancellation until X hours before (null = anytime)" }, "bookingWindowDays": { "type": [ "null", "number" ], "description": "How far ahead guests can book in days (null = use maxAdvanceDays)" }, "maxActiveBookingsPerGuest": { "type": [ "null", "number" ], "description": "Max concurrent active bookings per guest per location (null = unlimited)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "bufferMinutes", "defaultDurationMinutes", "autoOptimizeEnabled", "confirmationMode", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update location booking settings", "tags": [ "Bookings - Settings" ], "description": "Update booking settings for a location.\n\n**Permissions:** ⚪ `bookings.manage`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "bufferMinutes": { "type": "number", "minimum": 0, "maximum": 120, "description": "Time buffer between bookings (minutes)" }, "defaultDurationMinutes": { "type": "number", "minimum": 15, "maximum": 480, "description": "Default booking duration (minutes)" }, "autoOptimizeEnabled": { "type": "boolean", "description": "Enable automatic table optimization" }, "maxPartySize": { "type": "number", "minimum": 1, "maximum": 100, "description": "Maximum party size allowed" }, "minAdvanceHours": { "type": "number", "minimum": 0, "maximum": 168, "description": "Minimum hours in advance" }, "maxAdvanceDays": { "type": "number", "minimum": 1, "maximum": 365, "description": "Maximum days in advance" }, "allowedPartySizes": { "type": "array", "items": { "type": "number" }, "description": "Specific party sizes allowed" }, "operatingHours": { "type": "object", "description": "Per-day booking hours override" }, "slotIntervalMinutes": { "type": "number", "enum": [ 15, 30, 45, 60, 90 ], "description": "Time slot interval (minutes)" }, "overbookingBufferPercentage": { "type": "number", "minimum": 0, "maximum": 50, "description": "Overbooking buffer percentage" }, "confirmationMode": { "type": "string", "enum": [ "instant", "request_based" ], "description": "Booking confirmation mode" }, "autoNoShowDelayMinutes": { "type": [ "number", "null" ], "minimum": 5, "maximum": 120, "description": "Auto no-show delay (minutes)" }, "cancellationPolicyHours": { "type": [ "number", "null" ], "minimum": 0, "maximum": 168, "description": "Cancellation policy (hours before)" }, "bookingWindowDays": { "type": [ "number", "null" ], "minimum": 1, "maximum": 365, "description": "Booking window (days ahead)" }, "maxActiveBookingsPerGuest": { "type": [ "number", "null" ], "minimum": 1, "maximum": 50, "description": "Max active bookings per guest" } } } } } }, "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Settings ID" }, "locationId": { "type": "number", "description": "Location ID" }, "bufferMinutes": { "type": "number", "description": "Time buffer between bookings on same table (minutes)" }, "defaultDurationMinutes": { "type": "number", "description": "Default booking duration (minutes)" }, "autoOptimizeEnabled": { "type": "boolean", "description": "Whether to auto-optimize table assignments" }, "maxPartySize": { "type": "number", "description": "Maximum party size allowed for online bookings" }, "minAdvanceHours": { "type": "number", "description": "Minimum hours in advance a booking must be made" }, "maxAdvanceDays": { "type": "number", "description": "Maximum days in advance a booking can be made" }, "allowedPartySizes": { "type": "array", "items": { "type": "number" }, "description": "Specific party sizes allowed (empty = all sizes up to max)" }, "operatingHours": { "type": "object", "description": "Per-day booking hours override" }, "slotIntervalMinutes": { "type": "number", "description": "Time slot interval (minutes)" }, "overbookingBufferPercentage": { "type": "number", "description": "Overbooking buffer percentage" }, "confirmationMode": { "type": "string", "enum": [ "instant", "request_based" ], "description": "Booking confirmation mode" }, "autoNoShowDelayMinutes": { "type": [ "null", "number" ], "description": "Minutes after start before auto no-show (null = disabled)" }, "cancellationPolicyHours": { "type": [ "null", "number" ], "description": "Free cancellation until X hours before (null = anytime)" }, "bookingWindowDays": { "type": [ "null", "number" ], "description": "How far ahead guests can book in days (null = use maxAdvanceDays)" }, "maxActiveBookingsPerGuest": { "type": [ "null", "number" ], "description": "Max concurrent active bookings per guest per location (null = unlimited)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "bufferMinutes", "defaultDurationMinutes", "autoOptimizeEnabled", "confirmationMode", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/users/guests": { "post": { "summary": "Create guest user", "tags": [ "Bookings - Users" ], "description": "Create a new guest user. At least email or phone is required.\n\n**Permissions:** 🟢 `bookings.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Guest name" }, "email": { "type": "string", "format": "email", "description": "Guest email" }, "phone": { "type": "string", "description": "Guest phone number" } } } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "User ID" }, "email": { "type": "string", "nullable": true, "description": "User email" }, "phone": { "type": "string", "nullable": true, "description": "Effective phone (location override if set, else global)" }, "name": { "type": "string", "nullable": true, "description": "Effective display name (location override if set, else global)" }, "lastSeenDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Last activity date" }, "bookingCount": { "type": "number", "description": "Number of bookings at this location" }, "lastBookingDate": { "type": "string", "format": "date", "nullable": true, "description": "Last booking date" }, "vip": { "type": "boolean", "description": "Per-location VIP flag" }, "flags": { "type": "object", "additionalProperties": true, "description": "Per-location flags (allergies, dietary, accessibility, etc.)" }, "hasLocationOverride": { "type": "boolean", "description": "True when a per-location override exists for this user at the searched location" } }, "required": [ "id", "bookingCount", "vip", "flags", "hasLocationOverride" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/users/search": { "get": { "summary": "Search guest users", "tags": [ "Bookings - Users" ], "description": "Search for guest users by email, phone, or name. Returns users with their booking history at the location.\n\n**Permissions:** 🔵 `bookings.read`", "parameters": [ { "schema": { "type": "string", "minLength": 2 }, "in": "query", "name": "q", "required": true, "description": "Search query (email, phone, or name)" }, { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Location ID for booking history context" }, { "schema": { "type": "number", "minimum": 1, "maximum": 50, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Maximum results to return" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "User ID" }, "email": { "type": "string", "nullable": true, "description": "User email" }, "phone": { "type": "string", "nullable": true, "description": "Effective phone (location override if set, else global)" }, "name": { "type": "string", "nullable": true, "description": "Effective display name (location override if set, else global)" }, "lastSeenDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Last activity date" }, "bookingCount": { "type": "number", "description": "Number of bookings at this location" }, "lastBookingDate": { "type": "string", "format": "date", "nullable": true, "description": "Last booking date" }, "vip": { "type": "boolean", "description": "Per-location VIP flag" }, "flags": { "type": "object", "additionalProperties": true, "description": "Per-location flags (allergies, dietary, accessibility, etc.)" }, "hasLocationOverride": { "type": "boolean", "description": "True when a per-location override exists for this user at the searched location" } }, "required": [ "id", "bookingCount", "vip", "flags", "hasLocationOverride" ] } } }, "required": [ "users" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/booking-waitlist": { "get": { "summary": "List waitlist", "tags": [ "Bookings - Waitlist" ], "description": "List waitlist entries\n\n**Permissions:** 🔵 `booking_waitlist.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "string", "enum": [ "waiting", "notified", "converted", "expired", "removed" ] }, "in": "query", "name": "status", "required": false, "description": "Waitlist entry status" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "requestedDate", "required": false, "description": "Filter by requested date" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Waitlist entry ID" }, "locationId": { "type": "number", "description": "Location ID" }, "userId": { "type": "number", "description": "User ID" }, "requestedDate": { "type": "string", "format": "date", "description": "Requested date" }, "preferredStartTime": { "type": "string", "nullable": true, "description": "Preferred start time" }, "preferredEndTime": { "type": "string", "nullable": true, "description": "Preferred end time" }, "partySize": { "type": "number", "description": "Number of guests" }, "status": { "type": "string", "enum": [ "waiting", "notified", "converted", "expired", "removed" ], "description": "Waitlist entry status" }, "convertedBookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "Booking ID if converted" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiration timestamp" }, "notifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Notification timestamp" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "userName": { "type": "string", "nullable": true, "description": "User name" }, "userEmail": { "type": "string", "nullable": true, "description": "User email" }, "userPhone": { "type": "string", "nullable": true, "description": "User phone" } }, "required": [ "id", "locationId", "userId", "requestedDate", "partySize", "status", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "entries", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Add to waitlist", "tags": [ "Bookings - Waitlist" ], "description": "Add a guest to the waitlist\n\n**Permissions:** ⚪ `booking_waitlist.manage`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID" }, "userId": { "type": "number", "description": "User ID" }, "requestedDate": { "type": "string", "format": "date", "description": "Requested date" }, "partySize": { "type": "number", "minimum": 1, "description": "Number of guests" }, "preferredStartTime": { "type": "string", "description": "Preferred start time" }, "preferredEndTime": { "type": "string", "description": "Preferred end time" } }, "required": [ "locationId", "userId", "requestedDate", "partySize" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Waitlist entry ID" }, "locationId": { "type": "number", "description": "Location ID" }, "userId": { "type": "number", "description": "User ID" }, "requestedDate": { "type": "string", "format": "date", "description": "Requested date" }, "preferredStartTime": { "type": "string", "nullable": true, "description": "Preferred start time" }, "preferredEndTime": { "type": "string", "nullable": true, "description": "Preferred end time" }, "partySize": { "type": "number", "description": "Number of guests" }, "status": { "type": "string", "enum": [ "waiting", "notified", "converted", "expired", "removed" ], "description": "Waitlist entry status" }, "convertedBookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "Booking ID if converted" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiration timestamp" }, "notifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Notification timestamp" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "userName": { "type": "string", "nullable": true, "description": "User name" }, "userEmail": { "type": "string", "nullable": true, "description": "User email" }, "userPhone": { "type": "string", "nullable": true, "description": "User phone" } }, "required": [ "id", "locationId", "userId", "requestedDate", "partySize", "status", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/booking-waitlist/{id}": { "delete": { "summary": "Remove from waitlist", "tags": [ "Bookings - Waitlist" ], "description": "Remove a guest from the waitlist\n\n**Permissions:** ⚪ `booking_waitlist.manage`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Waitlist entry ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/booking-waitlist/{id}/convert": { "post": { "summary": "Convert waitlist to booking", "tags": [ "Bookings - Waitlist" ], "description": "Convert a waitlist entry to a booking\n\n**Permissions:** ⚪ `booking_waitlist.manage`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tableId": { "type": "string", "format": "uuid", "description": "Table to assign" }, "startTime": { "type": "string", "description": "Start time" }, "endTime": { "type": "string", "description": "End time" } }, "required": [ "startTime", "endTime" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Waitlist entry ID" } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique booking ID" }, "locationId": { "type": "number", "description": "Location ID" }, "tableId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/resource ID (QR code UUID)" }, "bookingDate": { "type": "string", "format": "date", "description": "Date of the booking (YYYY-MM-DD)" }, "startTime": { "type": "string", "description": "Start time (HH:MM:SS)" }, "endTime": { "type": "string", "description": "End time (HH:MM:SS)" }, "timezone": { "type": "string", "description": "Timezone for the booking" }, "primaryUserId": { "type": [ "null", "number" ], "description": "Primary guest user ID (null for walk-ins)" }, "guestCount": { "type": "number", "minimum": 0, "description": "Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)" }, "occasion": { "type": "string", "enum": [ "none", "birthday", "anniversary", "business", "date", "celebration", "other" ], "description": "Occasion for the booking" }, "specialRequests": { "type": "string", "nullable": true, "description": "Guest special requests" }, "internalNotes": { "type": "string", "nullable": true, "description": "Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array." }, "notes": { "type": "array", "description": "Staff-only notes attached to this booking (entity_type=booking in the notes table).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "note": { "type": "string" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "uuid", "note", "sortOrder", "createdAt", "updatedAt" ] } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "checked_in", "seated", "completed", "cancelled", "no_show" ], "description": "Booking status" }, "paymentType": { "type": "string", "enum": [ "none", "deposit", "full_prepayment" ], "description": "Payment type required for booking" }, "depositAmountCents": { "type": "number", "nullable": true, "description": "Deposit amount in cents" }, "purchaseId": { "type": "number", "nullable": true, "description": "Linked purchase ID" }, "confirmationCode": { "type": "string", "description": "Unique confirmation code for guest" }, "bookingSource": { "type": "string", "enum": [ "direct", "website", "phone", "walkin", "third_party" ], "description": "Source of the booking" }, "estimatedRevenueCents": { "type": "number", "nullable": true, "description": "AI-estimated revenue" }, "guestName": { "type": "string", "nullable": true, "description": "Guest contact name" }, "guestEmail": { "type": "string", "nullable": true, "description": "Guest contact email" }, "guestPhone": { "type": "string", "nullable": true, "description": "Guest contact phone" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmation timestamp" }, "seatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Seated timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Cancellation timestamp" }, "tabId": { "type": "string", "nullable": true, "description": "UUID of the linked tab (if any)" }, "defaultTabStrategy": { "type": "string", "enum": [ "single", "per_resource" ], "description": "Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat." }, "resources": { "type": "array", "description": "Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`.", "items": { "type": "object", "description": "A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40).", "properties": { "qrCodeId": { "type": "string", "format": "uuid", "description": "storefront_qr_codes.uuid for the reserved resource" }, "isPrimary": { "type": "boolean", "description": "True for the primary/anchor resource of the booking" }, "position": { "type": "integer", "minimum": 0, "description": "Stable ordering index of this resource within the booking (0-based)" } }, "required": [ "qrCodeId", "isPrimary", "position" ] } }, "userName": { "type": "string", "nullable": true, "description": "Primary guest name" }, "userEmail": { "type": "string", "nullable": true, "description": "Primary guest email" }, "userPhone": { "type": "string", "nullable": true, "description": "Primary guest phone" }, "tableName": { "type": "string", "nullable": true, "description": "Table name" } }, "required": [ "id", "locationId", "bookingDate", "startTime", "endTime", "timezone", "guestCount", "status", "confirmationCode", "createdAt", "updatedAt", "defaultTabStrategy", "resources" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/booking-waitlist/{id}/notify": { "post": { "summary": "Notify waitlist", "tags": [ "Bookings - Waitlist" ], "description": "Notify a waitlist entry of available slot\n\n**Permissions:** ⚪ `booking_waitlist.manage`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Waitlist entry ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Waitlist entry ID" }, "locationId": { "type": "number", "description": "Location ID" }, "userId": { "type": "number", "description": "User ID" }, "requestedDate": { "type": "string", "format": "date", "description": "Requested date" }, "preferredStartTime": { "type": "string", "nullable": true, "description": "Preferred start time" }, "preferredEndTime": { "type": "string", "nullable": true, "description": "Preferred end time" }, "partySize": { "type": "number", "description": "Number of guests" }, "status": { "type": "string", "enum": [ "waiting", "notified", "converted", "expired", "removed" ], "description": "Waitlist entry status" }, "convertedBookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "Booking ID if converted" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Expiration timestamp" }, "notifiedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Notification timestamp" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "userName": { "type": "string", "nullable": true, "description": "User name" }, "userEmail": { "type": "string", "nullable": true, "description": "User email" }, "userPhone": { "type": "string", "nullable": true, "description": "User phone" } }, "required": [ "id", "locationId", "userId", "requestedDate", "partySize", "status", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/capacity-settings": { "get": { "tags": [ "Capacity Settings" ], "description": "List all capacity settings for a location", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "capacitySettings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number" }, "orderCapacity": { "type": [ "null", "number" ] }, "itemCapacity": { "type": [ "null", "number" ] }, "name": { "type": "string" }, "priority": { "type": "number" }, "enabled": { "type": "boolean" }, "timeStart": { "type": [ "null", "string" ], "description": "HH:mm:ss format" }, "timeEnd": { "type": [ "null", "string" ], "description": "HH:mm:ss format" }, "validFrom": { "type": [ "null", "string" ], "description": "ISO timestamp" }, "validTo": { "type": [ "null", "string" ], "description": "ISO timestamp" }, "validOnDays": { "type": "array", "items": { "type": "number" }, "description": "Array of days (1-7, Monday-Sunday)" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "locationId", "orderCapacity", "itemCapacity", "name", "priority", "enabled", "timeStart", "timeEnd", "validFrom", "validTo", "validOnDays", "createdAt", "updatedAt" ] } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "tags": [ "Capacity Settings" ], "description": "Create a new capacity setting", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderCapacity": { "type": [ "number", "null" ], "description": "Max orders per time slot" }, "itemCapacity": { "type": [ "number", "null" ], "description": "Max items per time slot" }, "name": { "type": "string", "description": "Display name for this setting" }, "priority": { "type": "number", "description": "Sort order (lower = higher priority)" }, "enabled": { "type": "boolean", "default": true }, "timeStart": { "type": [ "string", "null" ], "description": "HH:mm:ss format" }, "timeEnd": { "type": [ "string", "null" ], "description": "HH:mm:ss format" }, "validFrom": { "type": [ "string", "null" ], "description": "ISO timestamp" }, "validTo": { "type": [ "string", "null" ], "description": "ISO timestamp" }, "validOnDays": { "type": "array", "items": { "type": "number" }, "description": "Array of days (1-7, Monday-Sunday)" } }, "required": [ "name", "validOnDays" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "capacitySetting": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number" }, "orderCapacity": { "type": [ "null", "number" ] }, "itemCapacity": { "type": [ "null", "number" ] }, "name": { "type": "string" }, "priority": { "type": "number" }, "enabled": { "type": "boolean" }, "timeStart": { "type": [ "null", "string" ], "description": "HH:mm:ss format" }, "timeEnd": { "type": [ "null", "string" ], "description": "HH:mm:ss format" }, "validFrom": { "type": [ "null", "string" ], "description": "ISO timestamp" }, "validTo": { "type": [ "null", "string" ], "description": "ISO timestamp" }, "validOnDays": { "type": "array", "items": { "type": "number" }, "description": "Array of days (1-7, Monday-Sunday)" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "locationId", "orderCapacity", "itemCapacity", "name", "priority", "enabled", "timeStart", "timeEnd", "validFrom", "validTo", "validOnDays", "createdAt", "updatedAt" ] } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/capacity-settings/{id}": { "get": { "tags": [ "Capacity Settings" ], "description": "Get a single capacity setting", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Capacity setting ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "capacitySetting": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number" }, "orderCapacity": { "type": [ "null", "number" ] }, "itemCapacity": { "type": [ "null", "number" ] }, "name": { "type": "string" }, "priority": { "type": "number" }, "enabled": { "type": "boolean" }, "timeStart": { "type": [ "null", "string" ], "description": "HH:mm:ss format" }, "timeEnd": { "type": [ "null", "string" ], "description": "HH:mm:ss format" }, "validFrom": { "type": [ "null", "string" ], "description": "ISO timestamp" }, "validTo": { "type": [ "null", "string" ], "description": "ISO timestamp" }, "validOnDays": { "type": "array", "items": { "type": "number" }, "description": "Array of days (1-7, Monday-Sunday)" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "locationId", "orderCapacity", "itemCapacity", "name", "priority", "enabled", "timeStart", "timeEnd", "validFrom", "validTo", "validOnDays", "createdAt", "updatedAt" ] } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "tags": [ "Capacity Settings" ], "description": "Update an existing capacity setting", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderCapacity": { "type": [ "number", "null" ] }, "itemCapacity": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "priority": { "type": "number" }, "enabled": { "type": "boolean" }, "timeStart": { "type": [ "string", "null" ] }, "timeEnd": { "type": [ "string", "null" ] }, "validFrom": { "type": [ "string", "null" ] }, "validTo": { "type": [ "string", "null" ] }, "validOnDays": { "type": "array", "items": { "type": "number" } } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Capacity setting ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "capacitySetting": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number" }, "orderCapacity": { "type": [ "null", "number" ] }, "itemCapacity": { "type": [ "null", "number" ] }, "name": { "type": "string" }, "priority": { "type": "number" }, "enabled": { "type": "boolean" }, "timeStart": { "type": [ "null", "string" ], "description": "HH:mm:ss format" }, "timeEnd": { "type": [ "null", "string" ], "description": "HH:mm:ss format" }, "validFrom": { "type": [ "null", "string" ], "description": "ISO timestamp" }, "validTo": { "type": [ "null", "string" ], "description": "ISO timestamp" }, "validOnDays": { "type": "array", "items": { "type": "number" }, "description": "Array of days (1-7, Monday-Sunday)" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "locationId", "orderCapacity", "itemCapacity", "name", "priority", "enabled", "timeStart", "timeEnd", "validFrom", "validTo", "validOnDays", "createdAt", "updatedAt" ] } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "tags": [ "Capacity Settings" ], "description": "Delete a capacity setting", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Capacity setting ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/capacity-settings/reorder": { "put": { "tags": [ "Capacity Settings" ], "description": "Reorder capacity settings (update priorities)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderedIds": { "type": "array", "items": { "type": "number" }, "description": "Array of capacity setting IDs in desired priority order" } }, "required": [ "orderedIds" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "capacitySettings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number" }, "orderCapacity": { "type": [ "null", "number" ] }, "itemCapacity": { "type": [ "null", "number" ] }, "name": { "type": "string" }, "priority": { "type": "number" }, "enabled": { "type": "boolean" }, "timeStart": { "type": [ "null", "string" ], "description": "HH:mm:ss format" }, "timeEnd": { "type": [ "null", "string" ], "description": "HH:mm:ss format" }, "validFrom": { "type": [ "null", "string" ], "description": "ISO timestamp" }, "validTo": { "type": [ "null", "string" ], "description": "ISO timestamp" }, "validOnDays": { "type": "array", "items": { "type": "number" }, "description": "Array of days (1-7, Monday-Sunday)" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "locationId", "orderCapacity", "itemCapacity", "name", "priority", "enabled", "timeStart", "timeEnd", "validFrom", "validTo", "validOnDays", "createdAt", "updatedAt" ] } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/channels": { "get": { "summary": "List channels", "tags": [ "Channels" ], "description": "List channels with optional filtering", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP" ] }, "in": "query", "name": "entityType", "required": false, "description": "Filter by entity type" }, { "schema": { "type": "string" }, "in": "query", "name": "entityId", "required": false, "description": "Filter by entity ID" }, { "schema": { "type": "string", "enum": [ "KIOSK", "POS", "ONLINE", "TAKEAWAY" ] }, "in": "query", "name": "channelType", "required": false, "description": "Filter by specific channel type" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isActive", "required": false, "description": "Filter by active status" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique channel ID" }, "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP" ], "description": "Type of entity this channel applies to" }, "entityId": { "type": "string", "description": "ID of the entity" }, "locationId": { "type": "number", "nullable": true, "description": "Location ID this channel applies to" }, "isActive": { "type": "boolean", "description": "Whether channel is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique assignment ID" }, "channelId": { "type": "string", "description": "Channel ID this assignment belongs to" }, "channelType": { "type": "string", "enum": [ "KIOSK", "POS", "ONLINE", "TAKEAWAY" ], "description": "Type of channel (KIOSK, POS, ONLINE, TAKEAWAY)" }, "isEnabled": { "type": "boolean", "description": "Whether this channel type is enabled" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "channelId", "channelType", "isEnabled", "createdAt" ] }, "description": "Channel type assignments" } }, "required": [ "id", "entityType", "entityId", "isActive", "createdAt", "updatedAt", "assignments" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "channels", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create channel", "tags": [ "Channels" ], "description": "Create a new channel with assignments", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP" ], "description": "Type of entity" }, "entityId": { "type": "string", "description": "ID of the entity" }, "locationId": { "type": "number", "nullable": true, "description": "Location ID" }, "isActive": { "type": "boolean", "default": true, "description": "Whether channel is active" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "channelType": { "type": "string", "enum": [ "KIOSK", "POS", "ONLINE", "TAKEAWAY" ], "description": "Type of channel" }, "isEnabled": { "type": "boolean", "default": true, "description": "Whether channel type is enabled" } }, "required": [ "channelType" ] }, "description": "Channel type assignments" } }, "required": [ "entityType", "entityId", "assignments" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique channel ID" }, "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP" ], "description": "Type of entity this channel applies to" }, "entityId": { "type": "string", "description": "ID of the entity" }, "locationId": { "type": "number", "nullable": true, "description": "Location ID this channel applies to" }, "isActive": { "type": "boolean", "description": "Whether channel is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique assignment ID" }, "channelId": { "type": "string", "description": "Channel ID this assignment belongs to" }, "channelType": { "type": "string", "enum": [ "KIOSK", "POS", "ONLINE", "TAKEAWAY" ], "description": "Type of channel (KIOSK, POS, ONLINE, TAKEAWAY)" }, "isEnabled": { "type": "boolean", "description": "Whether this channel type is enabled" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "channelId", "channelType", "isEnabled", "createdAt" ] }, "description": "Channel type assignments" } }, "required": [ "id", "entityType", "entityId", "isActive", "createdAt", "updatedAt", "assignments" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/channels/{channelId}/assignments": { "post": { "summary": "Add channel assignment", "tags": [ "Channels" ], "description": "Add a new channel type assignment to an existing channel", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "channelType": { "type": "string", "enum": [ "KIOSK", "POS", "ONLINE", "TAKEAWAY" ], "description": "Type of channel" }, "isEnabled": { "type": "boolean", "default": true, "description": "Whether channel type is enabled" } }, "required": [ "channelType" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "channelId", "required": true, "description": "Channel ID" } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique assignment ID" }, "channelId": { "type": "string", "description": "Channel ID this assignment belongs to" }, "channelType": { "type": "string", "enum": [ "KIOSK", "POS", "ONLINE", "TAKEAWAY" ], "description": "Type of channel (KIOSK, POS, ONLINE, TAKEAWAY)" }, "isEnabled": { "type": "boolean", "description": "Whether this channel type is enabled" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "channelId", "channelType", "isEnabled", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/channels/{id}": { "get": { "summary": "Get channel", "tags": [ "Channels" ], "description": "Get a single channel by ID with its assignments", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Channel ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique channel ID" }, "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP" ], "description": "Type of entity this channel applies to" }, "entityId": { "type": "string", "description": "ID of the entity" }, "locationId": { "type": "number", "nullable": true, "description": "Location ID this channel applies to" }, "isActive": { "type": "boolean", "description": "Whether channel is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique assignment ID" }, "channelId": { "type": "string", "description": "Channel ID this assignment belongs to" }, "channelType": { "type": "string", "enum": [ "KIOSK", "POS", "ONLINE", "TAKEAWAY" ], "description": "Type of channel (KIOSK, POS, ONLINE, TAKEAWAY)" }, "isEnabled": { "type": "boolean", "description": "Whether this channel type is enabled" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "channelId", "channelType", "isEnabled", "createdAt" ] }, "description": "Channel type assignments" } }, "required": [ "id", "entityType", "entityId", "isActive", "createdAt", "updatedAt", "assignments" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update channel", "tags": [ "Channels" ], "description": "Update an existing channel\n\n**Permissions:** 🟠 `channels.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "isActive": { "type": "boolean", "description": "Whether channel is active" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Channel ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique channel ID" }, "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP" ], "description": "Type of entity this channel applies to" }, "entityId": { "type": "string", "description": "ID of the entity" }, "locationId": { "type": "number", "nullable": true, "description": "Location ID this channel applies to" }, "isActive": { "type": "boolean", "description": "Whether channel is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique assignment ID" }, "channelId": { "type": "string", "description": "Channel ID this assignment belongs to" }, "channelType": { "type": "string", "enum": [ "KIOSK", "POS", "ONLINE", "TAKEAWAY" ], "description": "Type of channel (KIOSK, POS, ONLINE, TAKEAWAY)" }, "isEnabled": { "type": "boolean", "description": "Whether this channel type is enabled" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "channelId", "channelType", "isEnabled", "createdAt" ] }, "description": "Channel type assignments" } }, "required": [ "id", "entityType", "entityId", "isActive", "createdAt", "updatedAt", "assignments" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete channel", "tags": [ "Channels" ], "description": "Delete a channel and its assignments", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Channel ID" } ], "responses": { "200": { "description": "Channel successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/channels/assignments/{assignmentId}": { "put": { "summary": "Update channel assignment", "tags": [ "Channels" ], "description": "Update an existing channel assignment", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "isEnabled": { "type": "boolean", "description": "Whether channel type is enabled" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "assignmentId", "required": true, "description": "Assignment ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique assignment ID" }, "channelId": { "type": "string", "description": "Channel ID this assignment belongs to" }, "channelType": { "type": "string", "enum": [ "KIOSK", "POS", "ONLINE", "TAKEAWAY" ], "description": "Type of channel (KIOSK, POS, ONLINE, TAKEAWAY)" }, "isEnabled": { "type": "boolean", "description": "Whether this channel type is enabled" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "channelId", "channelType", "isEnabled", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete channel assignment", "tags": [ "Channels" ], "description": "Delete a channel assignment\n\n**Permissions:** 🔴 `channels.delete`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "assignmentId", "required": true, "description": "Assignment ID" } ], "responses": { "200": { "description": "Assignment successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/coursings": { "get": { "summary": "List coursings", "tags": [ "Coursings" ], "description": "List coursings with optional filtering\n\n**Permissions:** 🔵 `coursings.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "coursings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique coursing ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID this coursing belongs to" }, "title": { "type": "string", "description": "Coursing title (e.g., \"Appetizer\", \"Main\", \"Dessert\")" }, "order": { "type": "number", "minimum": 0, "maximum": 100, "description": "Display order (0-100)" }, "color": { "type": "string", "nullable": true, "description": "Hex color code (e.g., #FF5733) for visual differentiation" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "title", "order", "color", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "coursings", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create coursing", "tags": [ "Coursings" ], "description": "Create a new coursing\n\n**Permissions:** 🟢 `coursings.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID" }, "title": { "type": "string", "minLength": 1, "description": "Coursing title" }, "order": { "type": "number", "minimum": 0, "maximum": 100, "description": "Display order (0-100)" }, "color": { "type": "string", "nullable": true, "description": "Hex color code (e.g., #FF5733)" } }, "required": [ "locationId", "title", "order" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique coursing ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID this coursing belongs to" }, "title": { "type": "string", "description": "Coursing title (e.g., \"Appetizer\", \"Main\", \"Dessert\")" }, "order": { "type": "number", "minimum": 0, "maximum": 100, "description": "Display order (0-100)" }, "color": { "type": "string", "nullable": true, "description": "Hex color code (e.g., #FF5733) for visual differentiation" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "title", "order", "color", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/coursings/{id}": { "get": { "summary": "Get coursing", "tags": [ "Coursings" ], "description": "Get a single coursing by ID\n\n**Permissions:** 🔵 `coursings.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Coursing ID (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique coursing ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID this coursing belongs to" }, "title": { "type": "string", "description": "Coursing title (e.g., \"Appetizer\", \"Main\", \"Dessert\")" }, "order": { "type": "number", "minimum": 0, "maximum": 100, "description": "Display order (0-100)" }, "color": { "type": "string", "nullable": true, "description": "Hex color code (e.g., #FF5733) for visual differentiation" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "title", "order", "color", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update coursing", "tags": [ "Coursings" ], "description": "Update an existing coursing\n\n**Permissions:** 🟠 `coursings.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "order": { "type": "number", "minimum": 0, "maximum": 100 }, "color": { "type": "string", "nullable": true, "description": "Hex color code (e.g., #FF5733)" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Coursing ID (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique coursing ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID this coursing belongs to" }, "title": { "type": "string", "description": "Coursing title (e.g., \"Appetizer\", \"Main\", \"Dessert\")" }, "order": { "type": "number", "minimum": 0, "maximum": 100, "description": "Display order (0-100)" }, "color": { "type": "string", "nullable": true, "description": "Hex color code (e.g., #FF5733) for visual differentiation" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "title", "order", "color", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete coursing", "tags": [ "Coursings" ], "description": "Delete a coursing\n\n**Permissions:** 🔴 `coursings.delete`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Coursing ID (UUID)" } ], "responses": { "200": { "description": "Coursing successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/custom-tags": { "post": { "summary": "Create custom tag", "tags": [ "Custom Tags" ], "description": "Create a new custom tag and link it to an item\n\n**Permissions:** 🟢 `custom_tags.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "number", "description": "Item ID to tag" }, "categoryHandle": { "type": "string", "description": "Category handle" }, "key": { "type": "string", "minLength": 1, "description": "Tag key/name" } }, "required": [ "itemId", "categoryHandle", "key" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique tag ID" }, "key": { "type": "string", "description": "Tag key/name" }, "categoryHandle": { "type": "string", "description": "Category handle" }, "categoryId": { "type": "number", "description": "Category ID" }, "languageId": { "type": "number", "description": "Language ID" } }, "required": [ "id", "key", "categoryHandle", "categoryId", "languageId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/custom-tags/link": { "post": { "summary": "Link custom tag", "tags": [ "Custom Tags" ], "description": "Link an existing custom tag to an item\n\n**Permissions:** 🟠 `custom_tags.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "number", "description": "Item ID" }, "customTagId": { "type": "number", "description": "Custom tag ID to link" } }, "required": [ "itemId", "customTagId" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/custom-tags/search": { "get": { "summary": "Search custom tags", "tags": [ "Custom Tags" ], "description": "Search for custom tags by query string\n\n**Permissions:** 🔵 `custom_tags.read`", "parameters": [ { "schema": { "type": "string", "minLength": 3 }, "in": "query", "name": "query", "required": true, "description": "Search string (minimum 3 characters)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique tag ID" }, "key": { "type": "string", "description": "Tag key/name" }, "categoryHandle": { "type": "string", "description": "Category handle" }, "categoryId": { "type": "number", "description": "Category ID" }, "languageId": { "type": "number", "description": "Language ID" } }, "required": [ "id", "key", "categoryHandle", "categoryId", "languageId" ] } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/custom-tags/unlink": { "post": { "summary": "Unlink custom tag", "tags": [ "Custom Tags" ], "description": "Unlink a custom tag from an item\n\n**Permissions:** 🟠 `custom_tags.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "number", "description": "Item ID" }, "customTagId": { "type": "number", "description": "Custom tag ID to unlink" } }, "required": [ "itemId", "customTagId" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/cwi/items": { "put": { "summary": "Create or update a CWI item by EAN", "tags": [ "CWI" ], "description": "Create or update a CWI item by EAN.\n\nIf an item with the given EAN already exists for the company, it is updated. Otherwise, a new item is created. Returns 201 for creation, 200 for update.\n\n**Discount validation:** Must be between 50 and 90, and must end in 0 or 5 (e.g. 50, 55, 60, 65, 70, 75, 80, 85, 90).\n\n**Allergen codes:** Use two-letter codes (e.g. `AW` = Gluten, `AE` = Egg, `AM` = Milk). See the allergenCodes field for the full list.\n\n**Permissions:** ⚪ `cwi.write`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ean": { "type": "string", "description": "EAN / article number (unique per company)", "example": "7310070771223" }, "title": { "type": "string", "description": "Item title", "example": "Sourdough Bread" }, "fullPrice": { "type": "number", "description": "Full price in cents (e.g. 5900 = 59 SEK)", "example": 5900 }, "discount": { "type": "number", "description": "Discount percentage (50-90, must end in 0 or 5)", "minimum": 50, "maximum": 90, "example": 50 }, "description": { "type": "string", "description": "Item description", "example": "Freshly baked sourdough bread" }, "category": { "type": "string", "enum": [ "DRINK", "GROCERY", "FULL_MEAL", "BREAD", "SWEETS", "SNACK" ], "description": "Item category" }, "preferences": { "type": "array", "items": { "type": "string", "enum": [ "GLUTEN_FREE", "PORK", "BEEF", "CHICKEN", "VEGAN", "VEGETARIAN", "FISH_PREF", "SHELLFISH_PREF", "LACTOSE_FREE" ] }, "description": "Dietary preferences" }, "allergenCodes": { "type": "array", "items": { "type": "string", "enum": [ "AC", "AE", "AF", "AM", "AN", "AP", "AS", "AU", "AW", "AY", "BC", "BM", "GB", "GO", "GS", "ML", "NC", "NL", "NM", "NR", "SA", "SC", "SH", "SM", "SO", "SP", "SR", "ST", "SW", "UM", "UW", "NONE" ] }, "description": "Allergen codes. Common codes: AW=Gluten, AE=Egg, AF=Fish, AM=Milk, AN=Nuts, AP=Peanuts, AY=Soya, UW=Wheat" } }, "required": [ "ean", "title", "fullPrice", "discount" ] } } }, "required": true }, "responses": { "200": { "description": "Item updated successfully", "content": { "application/json": { "schema": { "description": "Item updated successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Item ID" }, "ean": { "type": "string", "nullable": true, "description": "EAN / article number" }, "title": { "type": "string", "description": "Item title" }, "fullPrice": { "type": "number", "description": "Full price in cents" }, "discount": { "type": "number", "description": "Discount percentage (50-90, must end in 0 or 5)" }, "description": { "type": "string", "nullable": true, "description": "Item description" }, "companyId": { "type": "number", "description": "Company ID" }, "locationId": { "type": "number", "nullable": true, "description": "Location ID" }, "category": { "type": "string", "nullable": true, "description": "Category tag (DRINK, GROCERY, FULL_MEAL, BREAD, SWEETS, SNACK)" }, "preferences": { "type": "array", "items": { "type": "string" }, "description": "Dietary preferences (VEGAN, VEGETARIAN, GLUTEN_FREE, etc.)" }, "allergenCodes": { "type": "array", "items": { "type": "string" }, "description": "Allergen codes (AW=GLUTEN, AE=EGG, AM=MILK, etc.)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "title", "fullPrice", "discount", "companyId", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "201": { "description": "Item created successfully", "content": { "application/json": { "schema": { "description": "Item created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Item ID" }, "ean": { "type": "string", "nullable": true, "description": "EAN / article number" }, "title": { "type": "string", "description": "Item title" }, "fullPrice": { "type": "number", "description": "Full price in cents" }, "discount": { "type": "number", "description": "Discount percentage (50-90, must end in 0 or 5)" }, "description": { "type": "string", "nullable": true, "description": "Item description" }, "companyId": { "type": "number", "description": "Company ID" }, "locationId": { "type": "number", "nullable": true, "description": "Location ID" }, "category": { "type": "string", "nullable": true, "description": "Category tag (DRINK, GROCERY, FULL_MEAL, BREAD, SWEETS, SNACK)" }, "preferences": { "type": "array", "items": { "type": "string" }, "description": "Dietary preferences (VEGAN, VEGETARIAN, GLUTEN_FREE, etc.)" }, "allergenCodes": { "type": "array", "items": { "type": "string" }, "description": "Allergen codes (AW=GLUTEN, AE=EGG, AM=MILK, etc.)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "title", "fullPrice", "discount", "companyId", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "get": { "summary": "List CWI items for company", "tags": [ "CWI" ], "description": "List all CWI items (items with EAN) for the authenticated company.\n\nSupports pagination and optional filtering by location.\n\n**Permissions:** 🔵 `cwi.read`", "parameters": [ { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" }, { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" } ], "responses": { "200": { "description": "List of CWI items", "content": { "application/json": { "schema": { "description": "List of CWI items", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Item ID" }, "ean": { "type": "string", "nullable": true, "description": "EAN / article number" }, "title": { "type": "string", "description": "Item title" }, "fullPrice": { "type": "number", "description": "Full price in cents" }, "discount": { "type": "number", "description": "Discount percentage (50-90, must end in 0 or 5)" }, "description": { "type": "string", "nullable": true, "description": "Item description" }, "companyId": { "type": "number", "description": "Company ID" }, "locationId": { "type": "number", "nullable": true, "description": "Location ID" }, "category": { "type": "string", "nullable": true, "description": "Category tag (DRINK, GROCERY, FULL_MEAL, BREAD, SWEETS, SNACK)" }, "preferences": { "type": "array", "items": { "type": "string" }, "description": "Dietary preferences (VEGAN, VEGETARIAN, GLUTEN_FREE, etc.)" }, "allergenCodes": { "type": "array", "items": { "type": "string" }, "description": "Allergen codes (AW=GLUTEN, AE=EGG, AM=MILK, etc.)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "title", "fullPrice", "discount", "companyId", "createdAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "items", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/cwi/items/{ean}": { "delete": { "summary": "Delete a CWI item by EAN", "tags": [ "CWI" ], "description": "Soft-delete a CWI item by EAN.\n\nMarks the item as deleted. The item can no longer be found via the list endpoint.\n\n**Permissions:** 🔴 `cwi.delete`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "ean", "required": true, "description": "EAN / article number of the item to delete" } ], "responses": { "200": { "description": "Item deleted successfully", "content": { "application/json": { "schema": { "description": "Item deleted successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "ean": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/data-streaming/connection": { "get": { "summary": "Get connection details including BigQuery credentials and available datasets", "tags": [ "Data Streaming" ], "description": "Get data streaming connection for current company", "responses": { "200": { "description": "Data streaming connection details", "content": { "application/json": { "schema": { "description": "Data streaming connection details", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "companyId": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended", "inactive" ] }, "bqProjectId": { "type": "string", "nullable": true }, "bqDatasetId": { "type": "string", "nullable": true }, "gcpServiceAccountEmail": { "type": "string", "nullable": true }, "availableDatasets": { "type": "array", "items": { "type": "string" } }, "currentMonthBytesScanned": { "type": "integer" }, "lastUsageSyncAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "activatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/data-streaming/usage": { "get": { "summary": "Get monthly usage history including bytes scanned and estimated costs", "tags": [ "Data Streaming" ], "description": "Get usage statistics for data streaming connection", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 24, "default": 3 }, "in": "query", "name": "months", "required": false, "description": "Number of months of usage history to return" } ], "responses": { "200": { "description": "Usage statistics", "content": { "application/json": { "schema": { "description": "Usage statistics", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "Month in YYYY-MM format" }, "bytesScanned": { "type": "integer" }, "queryCount": { "type": "integer" }, "estimatedCostSek": { "type": "number" } } } }, "totalBytesScanned": { "type": "integer" }, "totalQueryCount": { "type": "integer" }, "totalCostSek": { "type": "number" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/extended-waiting-time": { "get": { "tags": [ "Extended Waiting Time" ], "description": "Get extended waiting time for a location", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Location ID (optional if X-Location-Id header is provided)" } ], "responses": { "200": { "description": "Extended waiting time retrieved successfully", "content": { "application/json": { "schema": { "description": "Extended waiting time retrieved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "extendedWaitingTime": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "number", "description": "Extended waiting time ID" }, "locationId": { "type": "number", "description": "Location ID" }, "endsAt": { "type": "string", "format": "date-time", "description": "When the extended waiting time ends (ISO 8601)" }, "delayInMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes (optional)" } }, "required": [ "id", "locationId", "endsAt" ] }, { "type": "null", "description": "No extended waiting time set for this location" } ] } }, "required": [ "extendedWaitingTime" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "tags": [ "Extended Waiting Time" ], "description": "Create or update extended waiting time for a location", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID" }, "endsAt": { "type": "string", "format": "date-time", "description": "When the extended waiting time ends (ISO 8601)" }, "delayInMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes (optional)" } }, "required": [ "locationId", "endsAt" ] } } }, "required": true }, "responses": { "201": { "description": "Extended waiting time created/updated successfully", "content": { "application/json": { "schema": { "description": "Extended waiting time created/updated successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "extendedWaitingTime": { "type": "object", "properties": { "id": { "type": "number", "description": "Extended waiting time ID" }, "locationId": { "type": "number", "description": "Location ID" }, "endsAt": { "type": "string", "format": "date-time", "description": "When the extended waiting time ends (ISO 8601)" }, "delayInMinutes": { "type": "number", "nullable": true, "description": "Delay in minutes (optional)" } }, "required": [ "id", "locationId", "endsAt" ] } }, "required": [ "extendedWaitingTime" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "tags": [ "Extended Waiting Time" ], "description": "Delete extended waiting time by location ID", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Extended waiting time deleted successfully", "content": { "application/json": { "schema": { "description": "Extended waiting time deleted successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "number", "description": "Deleted extended waiting time ID" } }, "required": [ "deleted", "id" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/extended-waiting-time/{id}": { "delete": { "tags": [ "Extended Waiting Time" ], "description": "Delete extended waiting time by ID", "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "id", "required": true, "description": "Extended waiting time ID" } ], "responses": { "200": { "description": "Extended waiting time deleted successfully", "content": { "application/json": { "schema": { "description": "Extended waiting time deleted successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "number", "description": "Deleted extended waiting time ID" } }, "required": [ "deleted", "id" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/health": { "get": { "tags": [ "Internal" ], "description": "Simple health check endpoint. Returns basic status of database and Redis dependencies. Used for quick health verification.", "x-internal": true, "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "unhealthy" ], "description": "Overall service status" }, "checks": { "type": "object", "properties": { "database": { "type": "boolean", "description": "Database connectivity" }, "redis": { "type": "boolean", "description": "Redis connectivity" } }, "required": [ "database", "redis" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "Check timestamp" } }, "required": [ "status", "checks", "timestamp" ] }, "example": { "status": "healthy", "checks": { "database": true, "redis": true }, "timestamp": "2025-01-15T10:30:00.000Z" } } } }, "503": { "description": "Service is unhealthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unhealthy" ] }, "checks": { "type": "object", "properties": { "database": { "type": "boolean" }, "redis": { "type": "boolean" } } }, "timestamp": { "type": "string", "format": "date-time" } } }, "example": { "status": "unhealthy", "checks": { "database": true, "redis": false }, "timestamp": "2025-01-15T10:30:00.000Z" } } } } } } }, "/live": { "get": { "tags": [ "Internal" ], "description": "Kubernetes liveness probe. Lightweight check that the service process is running. Does not check external dependencies. Use to determine if the service should be restarted.", "x-internal": true, "responses": { "200": { "description": "Service is alive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "alive" ], "description": "Process status" }, "timestamp": { "type": "string", "format": "date-time", "description": "Check timestamp" }, "uptime": { "type": "number", "description": "Service uptime in seconds" } }, "required": [ "status", "timestamp", "uptime" ] }, "example": { "status": "alive", "timestamp": "2025-01-15T10:30:00.000Z", "uptime": 3600 } } } } } } }, "/ready": { "get": { "tags": [ "Internal" ], "description": "Kubernetes readiness probe with detailed dependency status. Returns response times and error details for each dependency. Use for determining if the service is ready to receive traffic.", "x-internal": true, "responses": { "200": { "description": "Service is ready to receive traffic", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded", "unhealthy" ], "description": "Overall status" }, "timestamp": { "type": "string", "format": "date-time", "description": "Check timestamp" }, "uptime": { "type": "number", "description": "Service uptime in seconds" }, "dependencies": { "type": "object", "properties": { "database": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "unhealthy", "degraded" ], "description": "Dependency health status" }, "responseTimeMs": { "type": "number", "description": "Response time to check dependency in milliseconds" }, "error": { "type": "string", "description": "Error message if unhealthy" } }, "required": [ "status" ] }, "redis": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "unhealthy", "degraded" ], "description": "Dependency health status" }, "responseTimeMs": { "type": "number", "description": "Response time to check dependency in milliseconds" }, "error": { "type": "string", "description": "Error message if unhealthy" } }, "required": [ "status" ] } }, "required": [ "database", "redis" ] } }, "required": [ "status", "timestamp", "uptime", "dependencies" ] }, "example": { "status": "healthy", "timestamp": "2025-01-15T10:30:00.000Z", "uptime": 3600, "dependencies": { "database": { "status": "healthy", "responseTimeMs": 5 }, "redis": { "status": "healthy", "responseTimeMs": 2 } } } } } }, "503": { "description": "Service is not ready", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "degraded", "unhealthy" ] }, "timestamp": { "type": "string", "format": "date-time" }, "uptime": { "type": "number" }, "dependencies": { "type": "object", "properties": { "database": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "unhealthy", "degraded" ], "description": "Dependency health status" }, "responseTimeMs": { "type": "number", "description": "Response time to check dependency in milliseconds" }, "error": { "type": "string", "description": "Error message if unhealthy" } }, "required": [ "status" ] }, "redis": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "unhealthy", "degraded" ], "description": "Dependency health status" }, "responseTimeMs": { "type": "number", "description": "Response time to check dependency in milliseconds" }, "error": { "type": "string", "description": "Error message if unhealthy" } }, "required": [ "status" ] } } } } }, "example": { "status": "unhealthy", "timestamp": "2025-01-15T10:30:00.000Z", "uptime": 3600, "dependencies": { "database": { "status": "healthy", "responseTimeMs": 5 }, "redis": { "status": "unhealthy", "responseTimeMs": 1000, "error": "Connection refused" } } } } } } } } }, "/api/v1/inventory": { "get": { "summary": "List inventory items", "tags": [ "Inventory" ], "description": "Retrieve a paginated list of inventory items with filtering and search capabilities\n\n**Permissions:** 🔵 `inventory.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" }, { "schema": { "type": "string", "default": "title" }, "in": "query", "name": "sort", "required": false, "description": "Field to sort by (title, basePrice, createdAt, etc.)" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Sort order" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "deleted", "required": false, "description": "Include deleted items" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Search term for title/description" }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "tags", "required": false, "description": "Filter by tags" }, { "schema": { "type": "string" }, "in": "query", "name": "itemType", "required": false, "description": "Filter by item type" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "excludeUnmapped", "required": false, "description": "When true and the location has an active POS integration, drop items that lack an integration_resource_mappings row. Used by storefront-web to hide items that would otherwise produce empty kitchen tickets." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique inventory item ID" }, "locationId": { "type": "number", "description": "Location ID this item belongs to" }, "title": { "type": "string", "description": "Item title/name" }, "description": { "type": "string", "nullable": true, "description": "Item description" }, "basePrice": { "type": "number", "nullable": true, "description": "Base price in cents (deprecated - use calculatedPrice)" }, "calculatedPrice": { "type": "number", "description": "Final calculated price in cents after applying all pricings" }, "itemType": { "type": "string", "nullable": true, "description": "Item type (food, beverage, etc.)" }, "vatId": { "type": "integer", "nullable": true, "description": "VAT ID" }, "vatValue": { "type": "number", "nullable": true, "description": "VAT value" }, "takeawayVatId": { "type": "integer", "nullable": true, "description": "Takeaway VAT ID" }, "takeawayVatValue": { "type": "number", "nullable": true, "description": "Takeaway VAT value" }, "isAvailable": { "type": "boolean", "description": "Whether item is available for ordering" }, "deleted": { "type": "boolean", "description": "Whether item is soft-deleted" }, "madeToOrder": { "type": "boolean", "description": "Whether item is made to order" }, "tags": { "type": "object", "description": "Item tags grouped by type" }, "createdDate": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "channelAvailability": { "type": "object", "description": "Channel availability flags", "properties": { "online": { "type": "boolean", "description": "Available on online channel" }, "qr": { "type": "boolean", "description": "Available on QR channel" }, "kiosk": { "type": "boolean", "description": "Available on kiosk channel" }, "pos": { "type": "boolean", "description": "Available on POS channel" } } }, "posIntegration": { "type": "object", "description": "POS integration mapping status. Present only when the location has an enabled integration_type='pos' config (e.g. Trivec, Domino). When isMapped is false, the item is missing an integration_resource_mappings row and orders containing it will reach the POS as an empty kitchen ticket.", "properties": { "integrationConfigId": { "type": "number", "description": "integration_configs.id of the active POS integration" }, "provider": { "type": "string", "description": "Human-readable integration name, e.g. \"Trivec\" or \"Domino\"" }, "externalItemId": { "type": "string", "nullable": true, "description": "External POS item id if mapped, null otherwise" }, "isMapped": { "type": "boolean", "description": "True iff an integration_resource_mappings row exists for this item under the active POS config" } }, "required": [ "integrationConfigId", "provider", "externalItemId", "isMapped" ] } }, "required": [ "id", "locationId", "title", "deleted", "createdDate", "madeToOrder" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "items", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create inventory item", "tags": [ "Inventory" ], "description": "Add a new menu item or product to the inventory\n\n**Permissions:** 🟢 `inventory.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID" }, "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Item title" }, "description": { "type": "string", "nullable": true, "maxLength": 255, "description": "Item description" }, "basePrice": { "type": "number", "minimum": 0, "description": "Base price in cents" }, "itemType": { "type": "string", "maxLength": 255, "description": "Item type" }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": true } ], "description": "Item tags (array of strings or grouped tags object)" }, "vatId": { "type": "integer", "nullable": true, "description": "VAT ID" }, "vatValue": { "type": "number", "nullable": true, "description": "VAT value (legacy)" }, "accountIds": { "type": "array", "items": { "type": "string" }, "description": "Bookkeeping account IDs" }, "printerGroupIds": { "type": "array", "items": { "type": "string" }, "description": "Printer group IDs" }, "variantGroupIds": { "type": "array", "items": { "type": "number" }, "description": "Variant group IDs" }, "visibility": { "type": "array", "items": { "type": "string" }, "description": "Visibility settings" } }, "additionalProperties": true, "required": [ "locationId", "title", "basePrice", "itemType" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique inventory item ID" }, "locationId": { "type": "number", "description": "Location ID this item belongs to" }, "title": { "type": "string", "description": "Item title/name" }, "description": { "type": "string", "nullable": true, "description": "Item description" }, "basePrice": { "type": "number", "nullable": true, "description": "Base price in cents (deprecated - use calculatedPrice)" }, "calculatedPrice": { "type": "number", "description": "Final calculated price in cents after applying all pricings" }, "itemType": { "type": "string", "nullable": true, "description": "Item type (food, beverage, etc.)" }, "vatId": { "type": "integer", "nullable": true, "description": "VAT ID" }, "vatValue": { "type": "number", "nullable": true, "description": "VAT value" }, "takeawayVatId": { "type": "integer", "nullable": true, "description": "Takeaway VAT ID" }, "takeawayVatValue": { "type": "number", "nullable": true, "description": "Takeaway VAT value" }, "isAvailable": { "type": "boolean", "description": "Whether item is available for ordering" }, "deleted": { "type": "boolean", "description": "Whether item is soft-deleted" }, "madeToOrder": { "type": "boolean", "description": "Whether item is made to order" }, "tags": { "type": "object", "description": "Item tags grouped by type" }, "createdDate": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "channelAvailability": { "type": "object", "description": "Channel availability flags", "properties": { "online": { "type": "boolean", "description": "Available on online channel" }, "qr": { "type": "boolean", "description": "Available on QR channel" }, "kiosk": { "type": "boolean", "description": "Available on kiosk channel" }, "pos": { "type": "boolean", "description": "Available on POS channel" } } }, "posIntegration": { "type": "object", "description": "POS integration mapping status. Present only when the location has an enabled integration_type='pos' config (e.g. Trivec, Domino). When isMapped is false, the item is missing an integration_resource_mappings row and orders containing it will reach the POS as an empty kitchen ticket.", "properties": { "integrationConfigId": { "type": "number", "description": "integration_configs.id of the active POS integration" }, "provider": { "type": "string", "description": "Human-readable integration name, e.g. \"Trivec\" or \"Domino\"" }, "externalItemId": { "type": "string", "nullable": true, "description": "External POS item id if mapped, null otherwise" }, "isMapped": { "type": "boolean", "description": "True iff an integration_resource_mappings row exists for this item under the active POS config" } }, "required": [ "integrationConfigId", "provider", "externalItemId", "isMapped" ] } }, "required": [ "id", "locationId", "title", "deleted", "createdDate", "madeToOrder" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/inventory/{id}": { "get": { "summary": "Get inventory item", "tags": [ "Inventory" ], "description": "Retrieve detailed information about a specific inventory item by its ID\n\n**Permissions:** 🔵 `inventory.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Inventory item ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique inventory item ID" }, "locationId": { "type": "number", "description": "Location ID this item belongs to" }, "title": { "type": "string", "description": "Item title/name" }, "description": { "type": "string", "nullable": true, "description": "Item description" }, "basePrice": { "type": "number", "nullable": true, "description": "Base price in cents (deprecated - use calculatedPrice)" }, "calculatedPrice": { "type": "number", "description": "Final calculated price in cents after applying all pricings" }, "itemType": { "type": "string", "nullable": true, "description": "Item type (food, beverage, etc.)" }, "vatId": { "type": "integer", "nullable": true, "description": "VAT ID" }, "vatValue": { "type": "number", "nullable": true, "description": "VAT value" }, "takeawayVatId": { "type": "integer", "nullable": true, "description": "Takeaway VAT ID" }, "takeawayVatValue": { "type": "number", "nullable": true, "description": "Takeaway VAT value" }, "isAvailable": { "type": "boolean", "description": "Whether item is available for ordering" }, "deleted": { "type": "boolean", "description": "Whether item is soft-deleted" }, "madeToOrder": { "type": "boolean", "description": "Whether item is made to order" }, "tags": { "type": "object", "description": "Item tags grouped by type" }, "createdDate": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "channelAvailability": { "type": "object", "description": "Channel availability flags", "properties": { "online": { "type": "boolean", "description": "Available on online channel" }, "qr": { "type": "boolean", "description": "Available on QR channel" }, "kiosk": { "type": "boolean", "description": "Available on kiosk channel" }, "pos": { "type": "boolean", "description": "Available on POS channel" } } }, "posIntegration": { "type": "object", "description": "POS integration mapping status. Present only when the location has an enabled integration_type='pos' config (e.g. Trivec, Domino). When isMapped is false, the item is missing an integration_resource_mappings row and orders containing it will reach the POS as an empty kitchen ticket.", "properties": { "integrationConfigId": { "type": "number", "description": "integration_configs.id of the active POS integration" }, "provider": { "type": "string", "description": "Human-readable integration name, e.g. \"Trivec\" or \"Domino\"" }, "externalItemId": { "type": "string", "nullable": true, "description": "External POS item id if mapped, null otherwise" }, "isMapped": { "type": "boolean", "description": "True iff an integration_resource_mappings row exists for this item under the active POS config" } }, "required": [ "integrationConfigId", "provider", "externalItemId", "isMapped" ] } }, "required": [ "id", "locationId", "title", "deleted", "createdDate", "madeToOrder" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update inventory item", "tags": [ "Inventory" ], "description": "Modify an existing inventory item's details\n\n**Permissions:** 🟠 `inventory.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "nullable": true, "maxLength": 255 }, "basePrice": { "type": "number", "minimum": 0 }, "itemType": { "type": "string", "maxLength": 255 }, "available": { "type": "boolean" }, "takeawayVatId": { "type": "integer", "nullable": true }, "integrationId": { "type": "string", "nullable": true, "maxLength": 255 }, "integrationItemId": { "type": "string", "nullable": true, "maxLength": 255 }, "imageUrl": { "type": "string", "nullable": true, "maxLength": 255 }, "externalImageUrl": { "type": "string", "nullable": true, "maxLength": 255 }, "context": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "string" }, { "type": "null" } ] }, "titlePrep": { "type": "string", "nullable": true, "maxLength": 255 }, "color": { "type": "string", "nullable": true, "maxLength": 255 }, "kitchenSortOrder": { "type": "integer", "nullable": true, "description": "Sort order within groups on printed kitchen tickets and KDS. Lower numbers appear first. NULL = sort last alphabetically." } }, "additionalProperties": true } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Inventory item ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique inventory item ID" }, "locationId": { "type": "number", "description": "Location ID this item belongs to" }, "title": { "type": "string", "description": "Item title/name" }, "description": { "type": "string", "nullable": true, "description": "Item description" }, "basePrice": { "type": "number", "nullable": true, "description": "Base price in cents (deprecated - use calculatedPrice)" }, "calculatedPrice": { "type": "number", "description": "Final calculated price in cents after applying all pricings" }, "itemType": { "type": "string", "nullable": true, "description": "Item type (food, beverage, etc.)" }, "vatId": { "type": "integer", "nullable": true, "description": "VAT ID" }, "vatValue": { "type": "number", "nullable": true, "description": "VAT value" }, "takeawayVatId": { "type": "integer", "nullable": true, "description": "Takeaway VAT ID" }, "takeawayVatValue": { "type": "number", "nullable": true, "description": "Takeaway VAT value" }, "isAvailable": { "type": "boolean", "description": "Whether item is available for ordering" }, "deleted": { "type": "boolean", "description": "Whether item is soft-deleted" }, "madeToOrder": { "type": "boolean", "description": "Whether item is made to order" }, "tags": { "type": "object", "description": "Item tags grouped by type" }, "createdDate": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "channelAvailability": { "type": "object", "description": "Channel availability flags", "properties": { "online": { "type": "boolean", "description": "Available on online channel" }, "qr": { "type": "boolean", "description": "Available on QR channel" }, "kiosk": { "type": "boolean", "description": "Available on kiosk channel" }, "pos": { "type": "boolean", "description": "Available on POS channel" } } }, "posIntegration": { "type": "object", "description": "POS integration mapping status. Present only when the location has an enabled integration_type='pos' config (e.g. Trivec, Domino). When isMapped is false, the item is missing an integration_resource_mappings row and orders containing it will reach the POS as an empty kitchen ticket.", "properties": { "integrationConfigId": { "type": "number", "description": "integration_configs.id of the active POS integration" }, "provider": { "type": "string", "description": "Human-readable integration name, e.g. \"Trivec\" or \"Domino\"" }, "externalItemId": { "type": "string", "nullable": true, "description": "External POS item id if mapped, null otherwise" }, "isMapped": { "type": "boolean", "description": "True iff an integration_resource_mappings row exists for this item under the active POS config" } }, "required": [ "integrationConfigId", "provider", "externalItemId", "isMapped" ] } }, "required": [ "id", "locationId", "title", "deleted", "createdDate", "madeToOrder" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete inventory item", "tags": [ "Inventory" ], "description": "Soft-delete an inventory item (marks as deleted without removing from database)\n\n**Permissions:** 🔴 `inventory.delete`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Inventory item ID" } ], "responses": { "200": { "description": "Item successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/inventory/{id}/inheritance": { "put": { "summary": "Update item inheritance", "tags": [ "Inventory" ], "description": "Update inheritance settings for an inventory item in a multi-location hierarchy\n\n**Permissions:** 🟠 `inventory.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "inheritToChildren": { "type": "boolean", "description": "Whether this item should be inherited to child locations" }, "allowedOverrides": { "type": "array", "items": { "type": "string" }, "description": "Fields that child locations are allowed to override" } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Inventory item ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "inheritToChildren": { "type": "boolean" }, "allowedOverrides": { "type": "array", "items": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/inventory/{id}/overrides": { "get": { "summary": "Get item overrides", "tags": [ "Inventory" ], "description": "Get all location-specific overrides for an inherited inventory item\n\n**Permissions:** 🔵 `inventory.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter overrides by location ID" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Inventory item ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "overrides": { "type": "array", "items": { "type": "object", "properties": { "locationId": { "type": "number" }, "field": { "type": "string" }, "value": { "type": "object", "additionalProperties": true } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update item overrides", "tags": [ "Inventory" ], "description": "Update location-specific overrides for an inherited inventory item\n\n**Permissions:** 🟠 `inventory.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Fields to override at this location" } } }, "description": "Fields to override at this location" }, "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Location ID for the override" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Inventory item ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "overrides": { "type": "object", "additionalProperties": true } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/inventory/{itemId}/availability": { "post": { "summary": "Toggle item availability", "tags": [ "Inventory" ], "description": "Enable or disable an inventory item for customer ordering\n\n**Permissions:** 🟠 `inventory.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "ACTIVATE", "DEACTIVATE" ], "description": "Action to perform: ACTIVATE to make item available, DEACTIVATE to hide it" } }, "required": [ "action" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "itemId", "required": true, "description": "Inventory item ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "itemId": { "type": "number", "description": "Inventory item ID" }, "action": { "type": "string", "enum": [ "ACTIVATE", "DEACTIVATE" ], "description": "Action performed" }, "isAvailable": { "type": "boolean", "description": "Current availability status" } }, "required": [ "itemId", "action", "isAvailable" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/inventory/validate": { "post": { "summary": "Validate inventory items", "tags": [ "Inventory" ], "description": "Validate inventory items and variants before creating an order. Returns validation results for each item.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "locationId", "items" ], "properties": { "locationId": { "type": "number", "minimum": 1 }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "itemId" ], "properties": { "itemId": { "type": "number", "minimum": 1 }, "variants": { "type": "array", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "type": "number", "minimum": 1 }, "quantity": { "type": "number", "minimum": 0.01 } } } }, "quantity": { "type": "number", "minimum": 1 }, "menuId": { "type": "string" } } } }, "validateMenu": { "type": "boolean" } } } } }, "required": true }, "responses": { "200": { "description": "Validation response containing valid and invalid items with nested variant structures", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Validation response containing valid and invalid items with nested variant structures" } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoice-location-settings": { "get": { "summary": "Get invoice location settings", "tags": [ "Invoices" ], "description": "Retrieve invoice settings for a specific location. Creates default settings if none exist.\n\n**Permissions:** 🔵 `invoices.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID to fetch settings for (required)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Settings UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "defaultPaymentTermsDays": { "type": "number", "description": "Default payment terms in days", "default": 30 }, "invoiceNumberPrefix": { "type": "string", "nullable": true, "description": "Prefix for invoice numbers (e.g., \"INV\")" }, "invoiceNumberCounter": { "type": "number", "description": "Current invoice number counter" }, "minInvoiceAmount": { "type": "number", "description": "Minimum amount for invoicing" }, "senderName": { "type": "string", "nullable": true, "description": "Sender/company name" }, "senderAddressLine1": { "type": "string", "nullable": true, "description": "Sender address line 1" }, "senderAddressLine2": { "type": "string", "nullable": true, "description": "Sender address line 2" }, "senderPostalCode": { "type": "string", "nullable": true, "description": "Sender postal code" }, "senderCity": { "type": "string", "nullable": true, "description": "Sender city" }, "senderCountry": { "type": "string", "nullable": true, "description": "Sender country" }, "senderEmail": { "type": "string", "nullable": true, "description": "Sender email address" }, "senderPhone": { "type": "string", "nullable": true, "description": "Sender phone number" }, "senderOrganizationNumber": { "type": "string", "nullable": true, "description": "Sender organization number" }, "senderVatNumber": { "type": "string", "nullable": true, "description": "Sender VAT number" }, "bankAccountNumber": { "type": "string", "nullable": true, "description": "Bank account number" }, "bankName": { "type": "string", "nullable": true, "description": "Bank name" }, "swiftBic": { "type": "string", "nullable": true, "description": "SWIFT/BIC code" }, "iban": { "type": "string", "nullable": true, "description": "IBAN" }, "paymentReferencePrefix": { "type": "string", "nullable": true, "description": "Payment reference prefix" }, "invoiceFooterText": { "type": "string", "nullable": true, "description": "Footer text for invoices" }, "invoiceTermsText": { "type": "string", "nullable": true, "description": "Terms and conditions text" }, "latePaymentFee": { "type": "number", "description": "Late payment fee amount" }, "latePaymentInterestRate": { "type": "number", "description": "Late payment interest rate (percentage)" }, "autoGenerateEnabled": { "type": "boolean", "description": "Enable automatic invoice generation" }, "autoSendOnGeneration": { "type": "boolean", "description": "Automatically send invoices when generated" }, "collectionPeriodType": { "type": "string", "enum": [ "calendar_month", "rolling_30_days", "weekly" ], "description": "Collection period type for auto-invoicing" }, "reminderEnabled": { "type": "boolean", "description": "Enable payment reminders" }, "firstReminderDaysAfterDue": { "type": "number", "description": "Days after due date for first reminder" }, "secondReminderDaysAfterDue": { "type": "number", "description": "Days after due date for second reminder" }, "thirdReminderDaysAfterDue": { "type": "number", "description": "Days after due date for third reminder" }, "reminderFeeAmount": { "type": "number", "description": "Fee amount added per reminder" }, "autoMarkOverdueDays": { "type": "number", "description": "Days after due date to auto-mark as overdue" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, EUR)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "defaultPaymentTermsDays", "invoiceNumberCounter", "minInvoiceAmount", "latePaymentFee", "latePaymentInterestRate", "autoGenerateEnabled", "autoSendOnGeneration", "collectionPeriodType", "reminderEnabled", "firstReminderDaysAfterDue", "secondReminderDaysAfterDue", "thirdReminderDaysAfterDue", "reminderFeeAmount", "autoMarkOverdueDays", "currency", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update invoice location settings", "tags": [ "Invoices" ], "description": "Update invoice settings for a specific location. Creates settings if they do not exist (upsert). All fields except locationId are optional for partial updates.\n\n**Permissions:** 🟠 `invoices.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID (required)" }, "defaultPaymentTermsDays": { "type": "number", "description": "Default payment terms in days" }, "invoiceNumberPrefix": { "type": "string", "nullable": true, "description": "Prefix for invoice numbers" }, "minInvoiceAmount": { "type": "number", "description": "Minimum amount for invoicing" }, "senderName": { "type": "string", "nullable": true, "description": "Sender/company name" }, "senderAddressLine1": { "type": "string", "nullable": true, "description": "Sender address line 1" }, "senderAddressLine2": { "type": "string", "nullable": true, "description": "Sender address line 2" }, "senderPostalCode": { "type": "string", "nullable": true, "description": "Sender postal code" }, "senderCity": { "type": "string", "nullable": true, "description": "Sender city" }, "senderCountry": { "type": "string", "nullable": true, "description": "Sender country" }, "senderEmail": { "type": "string", "nullable": true, "description": "Sender email address" }, "senderPhone": { "type": "string", "nullable": true, "description": "Sender phone number" }, "senderOrganizationNumber": { "type": "string", "nullable": true, "description": "Sender organization number" }, "senderVatNumber": { "type": "string", "nullable": true, "description": "Sender VAT number" }, "bankAccountNumber": { "type": "string", "nullable": true, "description": "Bank account number" }, "bankName": { "type": "string", "nullable": true, "description": "Bank name" }, "swiftBic": { "type": "string", "nullable": true, "description": "SWIFT/BIC code" }, "iban": { "type": "string", "nullable": true, "description": "IBAN" }, "paymentReferencePrefix": { "type": "string", "nullable": true, "description": "Payment reference prefix" }, "invoiceFooterText": { "type": "string", "nullable": true, "description": "Footer text for invoices" }, "invoiceTermsText": { "type": "string", "nullable": true, "description": "Terms and conditions text" }, "latePaymentFee": { "type": "number", "description": "Late payment fee amount" }, "latePaymentInterestRate": { "type": "number", "description": "Late payment interest rate (percentage)" }, "autoGenerateEnabled": { "type": "boolean", "description": "Enable automatic invoice generation" }, "autoSendOnGeneration": { "type": "boolean", "description": "Automatically send invoices when generated" }, "collectionPeriodType": { "type": "string", "enum": [ "calendar_month", "rolling_30_days", "weekly" ], "description": "Collection period type for auto-invoicing" }, "reminderEnabled": { "type": "boolean", "description": "Enable payment reminders" }, "firstReminderDaysAfterDue": { "type": "number", "description": "Days after due date for first reminder" }, "secondReminderDaysAfterDue": { "type": "number", "description": "Days after due date for second reminder" }, "thirdReminderDaysAfterDue": { "type": "number", "description": "Days after due date for third reminder" }, "reminderFeeAmount": { "type": "number", "description": "Fee amount added per reminder" }, "autoMarkOverdueDays": { "type": "number", "description": "Days after due date to auto-mark as overdue" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, EUR)" } }, "required": [ "locationId" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Settings UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "defaultPaymentTermsDays": { "type": "number", "description": "Default payment terms in days", "default": 30 }, "invoiceNumberPrefix": { "type": "string", "nullable": true, "description": "Prefix for invoice numbers (e.g., \"INV\")" }, "invoiceNumberCounter": { "type": "number", "description": "Current invoice number counter" }, "minInvoiceAmount": { "type": "number", "description": "Minimum amount for invoicing" }, "senderName": { "type": "string", "nullable": true, "description": "Sender/company name" }, "senderAddressLine1": { "type": "string", "nullable": true, "description": "Sender address line 1" }, "senderAddressLine2": { "type": "string", "nullable": true, "description": "Sender address line 2" }, "senderPostalCode": { "type": "string", "nullable": true, "description": "Sender postal code" }, "senderCity": { "type": "string", "nullable": true, "description": "Sender city" }, "senderCountry": { "type": "string", "nullable": true, "description": "Sender country" }, "senderEmail": { "type": "string", "nullable": true, "description": "Sender email address" }, "senderPhone": { "type": "string", "nullable": true, "description": "Sender phone number" }, "senderOrganizationNumber": { "type": "string", "nullable": true, "description": "Sender organization number" }, "senderVatNumber": { "type": "string", "nullable": true, "description": "Sender VAT number" }, "bankAccountNumber": { "type": "string", "nullable": true, "description": "Bank account number" }, "bankName": { "type": "string", "nullable": true, "description": "Bank name" }, "swiftBic": { "type": "string", "nullable": true, "description": "SWIFT/BIC code" }, "iban": { "type": "string", "nullable": true, "description": "IBAN" }, "paymentReferencePrefix": { "type": "string", "nullable": true, "description": "Payment reference prefix" }, "invoiceFooterText": { "type": "string", "nullable": true, "description": "Footer text for invoices" }, "invoiceTermsText": { "type": "string", "nullable": true, "description": "Terms and conditions text" }, "latePaymentFee": { "type": "number", "description": "Late payment fee amount" }, "latePaymentInterestRate": { "type": "number", "description": "Late payment interest rate (percentage)" }, "autoGenerateEnabled": { "type": "boolean", "description": "Enable automatic invoice generation" }, "autoSendOnGeneration": { "type": "boolean", "description": "Automatically send invoices when generated" }, "collectionPeriodType": { "type": "string", "enum": [ "calendar_month", "rolling_30_days", "weekly" ], "description": "Collection period type for auto-invoicing" }, "reminderEnabled": { "type": "boolean", "description": "Enable payment reminders" }, "firstReminderDaysAfterDue": { "type": "number", "description": "Days after due date for first reminder" }, "secondReminderDaysAfterDue": { "type": "number", "description": "Days after due date for second reminder" }, "thirdReminderDaysAfterDue": { "type": "number", "description": "Days after due date for third reminder" }, "reminderFeeAmount": { "type": "number", "description": "Fee amount added per reminder" }, "autoMarkOverdueDays": { "type": "number", "description": "Days after due date to auto-mark as overdue" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, EUR)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "defaultPaymentTermsDays", "invoiceNumberCounter", "minInvoiceAmount", "latePaymentFee", "latePaymentInterestRate", "autoGenerateEnabled", "autoSendOnGeneration", "collectionPeriodType", "reminderEnabled", "firstReminderDaysAfterDue", "secondReminderDaysAfterDue", "thirdReminderDaysAfterDue", "reminderFeeAmount", "autoMarkOverdueDays", "currency", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoice-recipients": { "get": { "summary": "List invoice recipients", "tags": [ "Invoices" ], "description": "List all invoice recipients for a location with optional filtering and pagination.\n\n**Permissions:** 🔵 `invoices.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID (required)" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isActive", "required": false, "description": "Filter by active status" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Recipient name" }, "email": { "type": "string", "description": "Email address" }, "organizationName": { "type": "string", "nullable": true, "description": "Organization/company name" }, "organizationNumber": { "type": "string", "nullable": true, "description": "Organization number" }, "phone": { "type": "string", "nullable": true, "description": "Phone number" }, "billingAddressLine1": { "type": "string", "nullable": true, "description": "Address line 1" }, "billingAddressLine2": { "type": "string", "nullable": true, "description": "Address line 2" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code" }, "city": { "type": "string", "nullable": true, "description": "City" }, "country": { "type": "string", "nullable": true, "description": "Country" }, "reference": { "type": "string", "nullable": true, "description": "Reference/PO number" }, "contactPerson": { "type": "string", "nullable": true, "description": "Contact person name" }, "vatNumber": { "type": "string", "nullable": true, "description": "VAT number" }, "totalInvoicedAmount": { "type": "number", "description": "Total amount invoiced to this recipient" }, "totalPaidAmount": { "type": "number", "description": "Total amount paid by this recipient" }, "outstandingAmount": { "type": "number", "description": "Outstanding amount (unpaid)" }, "invoiceCount": { "type": "number", "description": "Number of invoices sent to this recipient" }, "isActive": { "type": "boolean", "description": "Whether the recipient is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "name", "email", "totalInvoicedAmount", "totalPaidAmount", "outstandingAmount", "invoiceCount", "isActive", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "items", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create invoice recipient", "tags": [ "Invoices" ], "description": "Create a new invoice recipient for a location.\n\n**Permissions:** 🟢 `invoices.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID (required)" }, "name": { "type": "string", "description": "Recipient name (required)" }, "email": { "type": "string", "description": "Email address (required)" }, "organizationName": { "type": "string", "description": "Organization/company name" }, "organizationNumber": { "type": "string", "description": "Organization number" }, "phone": { "type": "string", "description": "Phone number" }, "billingAddressLine1": { "type": "string", "description": "Address line 1" }, "billingAddressLine2": { "type": "string", "description": "Address line 2" }, "postalCode": { "type": "string", "description": "Postal code" }, "city": { "type": "string", "description": "City" }, "country": { "type": "string", "description": "Country" }, "reference": { "type": "string", "description": "Reference/PO number" }, "contactPerson": { "type": "string", "description": "Contact person name" }, "vatNumber": { "type": "string", "description": "VAT number" } }, "required": [ "locationId", "name", "email" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Recipient name" }, "email": { "type": "string", "description": "Email address" }, "organizationName": { "type": "string", "nullable": true, "description": "Organization/company name" }, "organizationNumber": { "type": "string", "nullable": true, "description": "Organization number" }, "phone": { "type": "string", "nullable": true, "description": "Phone number" }, "billingAddressLine1": { "type": "string", "nullable": true, "description": "Address line 1" }, "billingAddressLine2": { "type": "string", "nullable": true, "description": "Address line 2" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code" }, "city": { "type": "string", "nullable": true, "description": "City" }, "country": { "type": "string", "nullable": true, "description": "Country" }, "reference": { "type": "string", "nullable": true, "description": "Reference/PO number" }, "contactPerson": { "type": "string", "nullable": true, "description": "Contact person name" }, "vatNumber": { "type": "string", "nullable": true, "description": "VAT number" }, "totalInvoicedAmount": { "type": "number", "description": "Total amount invoiced to this recipient" }, "totalPaidAmount": { "type": "number", "description": "Total amount paid by this recipient" }, "outstandingAmount": { "type": "number", "description": "Outstanding amount (unpaid)" }, "invoiceCount": { "type": "number", "description": "Number of invoices sent to this recipient" }, "isActive": { "type": "boolean", "description": "Whether the recipient is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "name", "email", "totalInvoicedAmount", "totalPaidAmount", "outstandingAmount", "invoiceCount", "isActive", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoice-recipients/{recipientId}": { "get": { "summary": "Get invoice recipient", "tags": [ "Invoices" ], "description": "Get a single invoice recipient by ID.\n\n**Permissions:** 🔵 `invoices.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "recipientId", "required": true, "description": "Recipient UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Recipient name" }, "email": { "type": "string", "description": "Email address" }, "organizationName": { "type": "string", "nullable": true, "description": "Organization/company name" }, "organizationNumber": { "type": "string", "nullable": true, "description": "Organization number" }, "phone": { "type": "string", "nullable": true, "description": "Phone number" }, "billingAddressLine1": { "type": "string", "nullable": true, "description": "Address line 1" }, "billingAddressLine2": { "type": "string", "nullable": true, "description": "Address line 2" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code" }, "city": { "type": "string", "nullable": true, "description": "City" }, "country": { "type": "string", "nullable": true, "description": "Country" }, "reference": { "type": "string", "nullable": true, "description": "Reference/PO number" }, "contactPerson": { "type": "string", "nullable": true, "description": "Contact person name" }, "vatNumber": { "type": "string", "nullable": true, "description": "VAT number" }, "totalInvoicedAmount": { "type": "number", "description": "Total amount invoiced to this recipient" }, "totalPaidAmount": { "type": "number", "description": "Total amount paid by this recipient" }, "outstandingAmount": { "type": "number", "description": "Outstanding amount (unpaid)" }, "invoiceCount": { "type": "number", "description": "Number of invoices sent to this recipient" }, "isActive": { "type": "boolean", "description": "Whether the recipient is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "name", "email", "totalInvoicedAmount", "totalPaidAmount", "outstandingAmount", "invoiceCount", "isActive", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update invoice recipient", "tags": [ "Invoices" ], "description": "Update an existing invoice recipient. All fields are optional for partial updates.\n\n**Permissions:** 🟠 `invoices.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Recipient name" }, "email": { "type": "string", "description": "Email address" }, "organizationName": { "type": "string", "nullable": true, "description": "Organization/company name" }, "organizationNumber": { "type": "string", "nullable": true, "description": "Organization number" }, "phone": { "type": "string", "nullable": true, "description": "Phone number" }, "billingAddressLine1": { "type": "string", "nullable": true, "description": "Address line 1" }, "billingAddressLine2": { "type": "string", "nullable": true, "description": "Address line 2" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code" }, "city": { "type": "string", "nullable": true, "description": "City" }, "country": { "type": "string", "nullable": true, "description": "Country" }, "reference": { "type": "string", "nullable": true, "description": "Reference/PO number" }, "contactPerson": { "type": "string", "nullable": true, "description": "Contact person name" }, "vatNumber": { "type": "string", "nullable": true, "description": "VAT number" }, "isActive": { "type": "boolean", "description": "Whether the recipient is active" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "recipientId", "required": true, "description": "Recipient UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Recipient name" }, "email": { "type": "string", "description": "Email address" }, "organizationName": { "type": "string", "nullable": true, "description": "Organization/company name" }, "organizationNumber": { "type": "string", "nullable": true, "description": "Organization number" }, "phone": { "type": "string", "nullable": true, "description": "Phone number" }, "billingAddressLine1": { "type": "string", "nullable": true, "description": "Address line 1" }, "billingAddressLine2": { "type": "string", "nullable": true, "description": "Address line 2" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code" }, "city": { "type": "string", "nullable": true, "description": "City" }, "country": { "type": "string", "nullable": true, "description": "Country" }, "reference": { "type": "string", "nullable": true, "description": "Reference/PO number" }, "contactPerson": { "type": "string", "nullable": true, "description": "Contact person name" }, "vatNumber": { "type": "string", "nullable": true, "description": "VAT number" }, "totalInvoicedAmount": { "type": "number", "description": "Total amount invoiced to this recipient" }, "totalPaidAmount": { "type": "number", "description": "Total amount paid by this recipient" }, "outstandingAmount": { "type": "number", "description": "Outstanding amount (unpaid)" }, "invoiceCount": { "type": "number", "description": "Number of invoices sent to this recipient" }, "isActive": { "type": "boolean", "description": "Whether the recipient is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "name", "email", "totalInvoicedAmount", "totalPaidAmount", "outstandingAmount", "invoiceCount", "isActive", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete invoice recipient", "tags": [ "Invoices" ], "description": "Soft-delete an invoice recipient (sets isActive to false).\n\n**Permissions:** 🔴 `invoices.delete`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "recipientId", "required": true, "description": "Recipient UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoice-recipients/{recipientId}/rules": { "get": { "summary": "List recipient rules", "tags": [ "Invoices" ], "description": "List all active eligibility rules for an invoice recipient.\n\n**Permissions:** 🔵 `invoices.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "recipientId", "required": true, "description": "Recipient UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Rule UUID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "ruleType": { "type": "string", "enum": [ "email_exact", "email_wildcard", "user_id" ], "description": "Type of rule: email_exact (exact match), email_wildcard (pattern match), user_id (user ID match)" }, "ruleValue": { "type": "string", "description": "Rule value (email, pattern, or user ID)" }, "isActive": { "type": "boolean", "description": "Whether the rule is active" }, "maxCreditLimit": { "type": "number", "nullable": true, "description": "Maximum credit limit for auto-invoicing" }, "autoApprove": { "type": "boolean", "description": "Auto-approve invoices matching this rule" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "recipientId", "locationId", "ruleType", "ruleValue", "isActive", "autoApprove", "createdAt", "updatedAt" ] } } }, "required": [ "rules" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create recipient rule", "tags": [ "Invoices" ], "description": "Create a new eligibility rule for automatic invoice assignment.\n\n**Permissions:** 🟢 `invoices.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID (required)" }, "ruleType": { "type": "string", "enum": [ "email_exact", "email_wildcard", "user_id" ], "description": "Type of rule (required)" }, "ruleValue": { "type": "string", "description": "Rule value - email, pattern (*@company.com), or user ID (required)" }, "maxCreditLimit": { "type": "number", "description": "Maximum credit limit for auto-invoicing" }, "autoApprove": { "type": "boolean", "description": "Auto-approve invoices matching this rule" } }, "required": [ "locationId", "ruleType", "ruleValue" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "recipientId", "required": true, "description": "Recipient UUID" } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Rule UUID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "ruleType": { "type": "string", "enum": [ "email_exact", "email_wildcard", "user_id" ], "description": "Type of rule: email_exact (exact match), email_wildcard (pattern match), user_id (user ID match)" }, "ruleValue": { "type": "string", "description": "Rule value (email, pattern, or user ID)" }, "isActive": { "type": "boolean", "description": "Whether the rule is active" }, "maxCreditLimit": { "type": "number", "nullable": true, "description": "Maximum credit limit for auto-invoicing" }, "autoApprove": { "type": "boolean", "description": "Auto-approve invoices matching this rule" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "recipientId", "locationId", "ruleType", "ruleValue", "isActive", "autoApprove", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoice-recipients/{recipientId}/rules/{ruleId}": { "delete": { "summary": "Delete recipient rule", "tags": [ "Invoices" ], "description": "Delete an eligibility rule.\n\n**Permissions:** 🔴 `invoices.delete`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "recipientId", "required": true, "description": "Recipient UUID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "ruleId", "required": true, "description": "Rule UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices": { "get": { "summary": "List invoices", "tags": [ "Invoices" ], "description": "List all invoices for a location with optional filtering and pagination.\n\n**Permissions:** 🔵 `invoices.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID (required)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "recipientId", "required": false, "description": "Filter by recipient" }, { "schema": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by status" }, { "schema": { "type": "string", "enum": [ "manual", "auto_generated" ] }, "in": "query", "name": "invoiceType", "required": false, "description": "Filter by invoice type" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Filter by start date" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "Filter by end date" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invoice UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "invoiceNumber": { "type": "string", "description": "Invoice number (unique per location)" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type" }, "collectionPeriodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period start (for auto-generated)" }, "collectionPeriodEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period end (for auto-generated)" }, "totalAmount": { "type": "number", "description": "Total invoice amount (including tax)" }, "taxAmount": { "type": "number", "description": "Total tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal (before tax)" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference code" }, "notes": { "type": "string", "nullable": true, "description": "Additional notes" }, "createdBy": { "type": "number", "nullable": true, "description": "User ID who created the invoice" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "recipientId", "invoiceNumber", "status", "invoiceType", "totalAmount", "taxAmount", "subtotalAmount", "currency", "dueDate", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "items", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create invoice", "tags": [ "Invoices" ], "description": "Create a new invoice. Invoice number is automatically generated.\n\n**Permissions:** 🟢 `invoices.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID (required)" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID (required)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date YYYY-MM-DD (required)" }, "currency": { "type": "string", "description": "Currency code (optional - defaults to location currency)" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type (default: manual)" }, "collectionPeriodStart": { "type": "string", "format": "date-time", "description": "Collection period start" }, "collectionPeriodEnd": { "type": "string", "format": "date-time", "description": "Collection period end" }, "totalAmount": { "type": "number", "description": "Total amount" }, "taxAmount": { "type": "number", "description": "Tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal amount" }, "issuedDate": { "type": "string", "format": "date", "description": "Issue date" }, "paymentReference": { "type": "string", "description": "Payment reference" }, "notes": { "type": "string", "description": "Notes" }, "purchaseIds": { "type": "array", "items": { "type": "number" }, "description": "Purchase IDs to link to invoice" } }, "required": [ "locationId", "recipientId", "dueDate" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invoice UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "invoiceNumber": { "type": "string", "description": "Invoice number (unique per location)" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type" }, "collectionPeriodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period start (for auto-generated)" }, "collectionPeriodEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period end (for auto-generated)" }, "totalAmount": { "type": "number", "description": "Total invoice amount (including tax)" }, "taxAmount": { "type": "number", "description": "Total tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal (before tax)" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference code" }, "notes": { "type": "string", "nullable": true, "description": "Additional notes" }, "createdBy": { "type": "number", "nullable": true, "description": "User ID who created the invoice" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "recipientId", "invoiceNumber", "status", "invoiceType", "totalAmount", "taxAmount", "subtotalAmount", "currency", "dueDate", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/{invoiceId}": { "get": { "summary": "Get invoice", "tags": [ "Invoices" ], "description": "Get a single invoice by ID.\n\n**Permissions:** 🔵 `invoices.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invoice UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "invoiceNumber": { "type": "string", "description": "Invoice number (unique per location)" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type" }, "collectionPeriodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period start (for auto-generated)" }, "collectionPeriodEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period end (for auto-generated)" }, "totalAmount": { "type": "number", "description": "Total invoice amount (including tax)" }, "taxAmount": { "type": "number", "description": "Total tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal (before tax)" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference code" }, "notes": { "type": "string", "nullable": true, "description": "Additional notes" }, "createdBy": { "type": "number", "nullable": true, "description": "User ID who created the invoice" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "recipientId", "invoiceNumber", "status", "invoiceType", "totalAmount", "taxAmount", "subtotalAmount", "currency", "dueDate", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update invoice", "tags": [ "Invoices" ], "description": "Update an existing invoice. All fields are optional for partial updates.\n\n**Permissions:** 🟠 `invoices.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "dueDate": { "type": "string", "format": "date", "description": "Due date" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference" }, "notes": { "type": "string", "nullable": true, "description": "Notes" }, "totalAmount": { "type": "number", "description": "Total amount" }, "taxAmount": { "type": "number", "description": "Tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal amount" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invoice UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "invoiceNumber": { "type": "string", "description": "Invoice number (unique per location)" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type" }, "collectionPeriodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period start (for auto-generated)" }, "collectionPeriodEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period end (for auto-generated)" }, "totalAmount": { "type": "number", "description": "Total invoice amount (including tax)" }, "taxAmount": { "type": "number", "description": "Total tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal (before tax)" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference code" }, "notes": { "type": "string", "nullable": true, "description": "Additional notes" }, "createdBy": { "type": "number", "nullable": true, "description": "User ID who created the invoice" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "recipientId", "invoiceNumber", "status", "invoiceType", "totalAmount", "taxAmount", "subtotalAmount", "currency", "dueDate", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete invoice", "tags": [ "Invoices" ], "description": "Delete a draft invoice. Only draft or auto_draft invoices can be deleted.\n\n**Permissions:** 🔴 `invoices.delete`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/{invoiceId}/cancel": { "post": { "summary": "Cancel invoice", "tags": [ "Invoices" ], "description": "Cancel an invoice. Cannot cancel paid invoices.\n\n**Permissions:** 🟠 `invoices.update`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invoice UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "invoiceNumber": { "type": "string", "description": "Invoice number (unique per location)" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type" }, "collectionPeriodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period start (for auto-generated)" }, "collectionPeriodEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period end (for auto-generated)" }, "totalAmount": { "type": "number", "description": "Total invoice amount (including tax)" }, "taxAmount": { "type": "number", "description": "Total tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal (before tax)" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference code" }, "notes": { "type": "string", "nullable": true, "description": "Additional notes" }, "createdBy": { "type": "number", "nullable": true, "description": "User ID who created the invoice" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "recipientId", "invoiceNumber", "status", "invoiceType", "totalAmount", "taxAmount", "subtotalAmount", "currency", "dueDate", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/{invoiceId}/mark-paid": { "post": { "summary": "Mark invoice as paid", "tags": [ "Invoices" ], "description": "Mark an invoice as paid. Cannot mark cancelled invoices as paid.\n\n**Permissions:** 🟠 `invoices.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentReference": { "type": "string", "description": "Payment reference (optional)" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invoice UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "invoiceNumber": { "type": "string", "description": "Invoice number (unique per location)" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type" }, "collectionPeriodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period start (for auto-generated)" }, "collectionPeriodEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period end (for auto-generated)" }, "totalAmount": { "type": "number", "description": "Total invoice amount (including tax)" }, "taxAmount": { "type": "number", "description": "Total tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal (before tax)" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference code" }, "notes": { "type": "string", "nullable": true, "description": "Additional notes" }, "createdBy": { "type": "number", "nullable": true, "description": "User ID who created the invoice" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "recipientId", "invoiceNumber", "status", "invoiceType", "totalAmount", "taxAmount", "subtotalAmount", "currency", "dueDate", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/{invoiceId}/pdf-data": { "get": { "summary": "Get invoice PDF data", "tags": [ "Invoices" ], "description": "Get all data needed for PDF generation (invoice, recipient, settings, location, purchases).\n\n**Permissions:** 🔵 `invoices.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invoice UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "invoiceNumber": { "type": "string", "description": "Invoice number (unique per location)" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type" }, "collectionPeriodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period start (for auto-generated)" }, "collectionPeriodEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period end (for auto-generated)" }, "totalAmount": { "type": "number", "description": "Total invoice amount (including tax)" }, "taxAmount": { "type": "number", "description": "Total tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal (before tax)" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference code" }, "notes": { "type": "string", "nullable": true, "description": "Additional notes" }, "createdBy": { "type": "number", "nullable": true, "description": "User ID who created the invoice" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "recipientId", "invoiceNumber", "status", "invoiceType", "totalAmount", "taxAmount", "subtotalAmount", "currency", "dueDate", "createdAt", "updatedAt" ] }, "recipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Recipient name" }, "email": { "type": "string", "description": "Email address" }, "organizationName": { "type": "string", "nullable": true, "description": "Organization/company name" }, "organizationNumber": { "type": "string", "nullable": true, "description": "Organization number" }, "phone": { "type": "string", "nullable": true, "description": "Phone number" }, "billingAddressLine1": { "type": "string", "nullable": true, "description": "Address line 1" }, "billingAddressLine2": { "type": "string", "nullable": true, "description": "Address line 2" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code" }, "city": { "type": "string", "nullable": true, "description": "City" }, "country": { "type": "string", "nullable": true, "description": "Country" }, "reference": { "type": "string", "nullable": true, "description": "Reference/PO number" }, "contactPerson": { "type": "string", "nullable": true, "description": "Contact person name" }, "vatNumber": { "type": "string", "nullable": true, "description": "VAT number" }, "totalInvoicedAmount": { "type": "number", "description": "Total amount invoiced to this recipient" }, "totalPaidAmount": { "type": "number", "description": "Total amount paid by this recipient" }, "outstandingAmount": { "type": "number", "description": "Outstanding amount (unpaid)" }, "invoiceCount": { "type": "number", "description": "Number of invoices sent to this recipient" }, "isActive": { "type": "boolean", "description": "Whether the recipient is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "name", "email", "totalInvoicedAmount", "totalPaidAmount", "outstandingAmount", "invoiceCount", "isActive", "createdAt", "updatedAt" ], "nullable": true }, "settings": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Settings UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "defaultPaymentTermsDays": { "type": "number", "description": "Default payment terms in days", "default": 30 }, "invoiceNumberPrefix": { "type": "string", "nullable": true, "description": "Prefix for invoice numbers (e.g., \"INV\")" }, "invoiceNumberCounter": { "type": "number", "description": "Current invoice number counter" }, "minInvoiceAmount": { "type": "number", "description": "Minimum amount for invoicing" }, "senderName": { "type": "string", "nullable": true, "description": "Sender/company name" }, "senderAddressLine1": { "type": "string", "nullable": true, "description": "Sender address line 1" }, "senderAddressLine2": { "type": "string", "nullable": true, "description": "Sender address line 2" }, "senderPostalCode": { "type": "string", "nullable": true, "description": "Sender postal code" }, "senderCity": { "type": "string", "nullable": true, "description": "Sender city" }, "senderCountry": { "type": "string", "nullable": true, "description": "Sender country" }, "senderEmail": { "type": "string", "nullable": true, "description": "Sender email address" }, "senderPhone": { "type": "string", "nullable": true, "description": "Sender phone number" }, "senderOrganizationNumber": { "type": "string", "nullable": true, "description": "Sender organization number" }, "senderVatNumber": { "type": "string", "nullable": true, "description": "Sender VAT number" }, "bankAccountNumber": { "type": "string", "nullable": true, "description": "Bank account number" }, "bankName": { "type": "string", "nullable": true, "description": "Bank name" }, "swiftBic": { "type": "string", "nullable": true, "description": "SWIFT/BIC code" }, "iban": { "type": "string", "nullable": true, "description": "IBAN" }, "paymentReferencePrefix": { "type": "string", "nullable": true, "description": "Payment reference prefix" }, "invoiceFooterText": { "type": "string", "nullable": true, "description": "Footer text for invoices" }, "invoiceTermsText": { "type": "string", "nullable": true, "description": "Terms and conditions text" }, "latePaymentFee": { "type": "number", "description": "Late payment fee amount" }, "latePaymentInterestRate": { "type": "number", "description": "Late payment interest rate (percentage)" }, "autoGenerateEnabled": { "type": "boolean", "description": "Enable automatic invoice generation" }, "autoSendOnGeneration": { "type": "boolean", "description": "Automatically send invoices when generated" }, "collectionPeriodType": { "type": "string", "enum": [ "calendar_month", "rolling_30_days", "weekly" ], "description": "Collection period type for auto-invoicing" }, "reminderEnabled": { "type": "boolean", "description": "Enable payment reminders" }, "firstReminderDaysAfterDue": { "type": "number", "description": "Days after due date for first reminder" }, "secondReminderDaysAfterDue": { "type": "number", "description": "Days after due date for second reminder" }, "thirdReminderDaysAfterDue": { "type": "number", "description": "Days after due date for third reminder" }, "reminderFeeAmount": { "type": "number", "description": "Fee amount added per reminder" }, "autoMarkOverdueDays": { "type": "number", "description": "Days after due date to auto-mark as overdue" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, EUR)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "defaultPaymentTermsDays", "invoiceNumberCounter", "minInvoiceAmount", "latePaymentFee", "latePaymentInterestRate", "autoGenerateEnabled", "autoSendOnGeneration", "collectionPeriodType", "reminderEnabled", "firstReminderDaysAfterDue", "secondReminderDaysAfterDue", "thirdReminderDaysAfterDue", "reminderFeeAmount", "autoMarkOverdueDays", "currency", "createdAt", "updatedAt" ], "nullable": true }, "location": { "type": "object", "properties": { "id": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "nullable": true, "description": "Location name" }, "address": { "type": "string", "nullable": true, "description": "Address" }, "postalCode": { "type": "string", "nullable": true, "description": "Postal code" }, "city": { "type": "string", "nullable": true, "description": "City" }, "country": { "type": "string", "nullable": true, "description": "Country" }, "phone": { "type": "string", "nullable": true, "description": "Phone" }, "organizationNumber": { "type": "string", "nullable": true, "description": "Organization number" }, "email": { "type": "string", "nullable": true, "description": "Email" }, "vatNumber": { "type": "string", "nullable": true, "description": "VAT number" } }, "required": [ "id" ], "nullable": true }, "purchaseDetails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Purchase ID" }, "intentId": { "type": "string", "description": "Intent ID" }, "purchasedAt": { "type": "string", "format": "date-time", "description": "Purchase timestamp" }, "totalAmountCents": { "type": "number", "description": "Total amount in cents" }, "vatAmountCents": { "type": "number", "description": "VAT amount in cents" }, "items": { "type": "string", "nullable": true, "description": "Items description" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Line item ID" }, "type": { "type": "string", "description": "Item type" }, "title": { "type": "string", "description": "Item title" }, "quantity": { "type": "number", "description": "Quantity" }, "finalAmountCents": { "type": "number", "description": "Final amount in cents" }, "vatRateBasisPoints": { "type": "number", "nullable": true, "description": "VAT rate in basis points" }, "vatAmountCents": { "type": "number", "description": "VAT amount in cents" }, "articleNo": { "type": "string", "nullable": true, "description": "Article number" } }, "required": [ "id", "type", "title", "quantity", "finalAmountCents", "vatAmountCents" ] }, "description": "Line items" } }, "required": [ "id", "intentId", "purchasedAt", "totalAmountCents", "vatAmountCents", "lineItems" ] } } }, "required": [ "invoice", "purchaseDetails" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/{invoiceId}/purchases": { "post": { "summary": "Add purchases to invoice", "tags": [ "Invoices" ], "description": "Add purchases to an invoice. Only draft invoices can have purchases added.\n\n**Permissions:** 🟠 `invoices.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseIds": { "type": "array", "items": { "type": "number" }, "description": "Array of purchase IDs to add to the invoice" } }, "required": [ "purchaseIds" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invoice UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "invoiceNumber": { "type": "string", "description": "Invoice number (unique per location)" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type" }, "collectionPeriodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period start (for auto-generated)" }, "collectionPeriodEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period end (for auto-generated)" }, "totalAmount": { "type": "number", "description": "Total invoice amount (including tax)" }, "taxAmount": { "type": "number", "description": "Total tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal (before tax)" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference code" }, "notes": { "type": "string", "nullable": true, "description": "Additional notes" }, "createdBy": { "type": "number", "nullable": true, "description": "User ID who created the invoice" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "recipientId", "invoiceNumber", "status", "invoiceType", "totalAmount", "taxAmount", "subtotalAmount", "currency", "dueDate", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/{invoiceId}/purchases/{purchaseId}": { "delete": { "summary": "Remove purchase from invoice", "tags": [ "Invoices" ], "description": "Remove a purchase from an invoice. Only draft invoices can have purchases removed.\n\n**Permissions:** 🟠 `invoices.update`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" }, { "schema": { "type": "number" }, "in": "path", "name": "purchaseId", "required": true, "description": "Purchase ID to remove" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invoice UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "invoiceNumber": { "type": "string", "description": "Invoice number (unique per location)" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type" }, "collectionPeriodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period start (for auto-generated)" }, "collectionPeriodEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period end (for auto-generated)" }, "totalAmount": { "type": "number", "description": "Total invoice amount (including tax)" }, "taxAmount": { "type": "number", "description": "Total tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal (before tax)" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference code" }, "notes": { "type": "string", "nullable": true, "description": "Additional notes" }, "createdBy": { "type": "number", "nullable": true, "description": "User ID who created the invoice" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "recipientId", "invoiceNumber", "status", "invoiceType", "totalAmount", "taxAmount", "subtotalAmount", "currency", "dueDate", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/{invoiceId}/send": { "post": { "summary": "Send invoice", "tags": [ "Invoices" ], "description": "Send an invoice to the recipient. Only draft invoices can be sent.\n\n**Permissions:** 🟠 `invoices.update`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invoice UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Recipient UUID" }, "invoiceNumber": { "type": "string", "description": "Invoice number (unique per location)" }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled", "auto_draft" ], "description": "Invoice status" }, "invoiceType": { "type": "string", "enum": [ "manual", "auto_generated" ], "description": "Invoice type" }, "collectionPeriodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period start (for auto-generated)" }, "collectionPeriodEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Collection period end (for auto-generated)" }, "totalAmount": { "type": "number", "description": "Total invoice amount (including tax)" }, "taxAmount": { "type": "number", "description": "Total tax amount" }, "subtotalAmount": { "type": "number", "description": "Subtotal (before tax)" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "dueDate": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "issuedDate": { "type": "string", "nullable": true, "format": "date", "description": "Issue date" }, "paidDate": { "type": "string", "nullable": true, "format": "date", "description": "Payment date" }, "paymentReference": { "type": "string", "nullable": true, "description": "Payment reference code" }, "notes": { "type": "string", "nullable": true, "description": "Additional notes" }, "createdBy": { "type": "number", "nullable": true, "description": "User ID who created the invoice" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Updated timestamp" } }, "required": [ "id", "locationId", "recipientId", "invoiceNumber", "status", "invoiceType", "totalAmount", "taxAmount", "subtotalAmount", "currency", "dueDate", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/{invoiceId}/send-reminder": { "post": { "summary": "Send invoice reminder", "tags": [ "Invoices" ], "description": "Send a payment reminder for an overdue invoice.\n\n**Permissions:** 🟠 `invoices.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reminderNumber": { "type": "number", "minimum": 1, "maximum": 3, "description": "Reminder number (1, 2, or 3)" } }, "required": [ "reminderNumber" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "sent": { "type": "boolean" }, "reminderNumber": { "type": "number" } }, "required": [ "sent", "reminderNumber" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/{invoiceId}/upload-pdf": { "post": { "summary": "Upload invoice PDF", "tags": [ "Invoices" ], "description": "Upload a generated PDF for an invoice. The PDF should be base64-encoded.\n\n**Permissions:** 🟠 `invoices.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "pdfBase64": { "type": "string", "description": "Base64-encoded PDF content" } }, "required": [ "pdfBase64" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "invoiceId", "required": true, "description": "Invoice UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "PDF storage record ID" }, "invoiceId": { "type": "string", "format": "uuid", "description": "Invoice ID" }, "pdfUrl": { "type": "string", "description": "URL to the PDF" }, "cdnPath": { "type": "string", "description": "CDN path" }, "fileSize": { "type": "number", "description": "File size in bytes" }, "generatedAt": { "type": "string", "format": "date-time", "description": "Generation timestamp" } }, "required": [ "id", "invoiceId", "pdfUrl", "cdnPath", "fileSize", "generatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/check-eligibility": { "get": { "summary": "Check invoice eligibility", "tags": [ "Invoices" ], "description": "Check if a user/email is eligible for invoice payment at a location.\n\n**Permissions:** 🔵 `invoices.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID (required)" }, { "schema": { "type": "string" }, "in": "query", "name": "email", "required": true, "description": "Email to check eligibility for (required)" }, { "schema": { "type": "number" }, "in": "query", "name": "userId", "required": false, "description": "User ID to check eligibility for (optional)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "eligible": { "type": "boolean", "description": "Whether the user is eligible for invoice payment" }, "recipientId": { "type": "string", "nullable": true, "description": "Matched recipient ID" }, "creditLimit": { "type": "number", "nullable": true, "description": "Credit limit for this user" }, "outstandingAmount": { "type": "number", "nullable": true, "description": "Current outstanding amount" } }, "required": [ "eligible" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/start-purchase": { "post": { "summary": "Start invoice purchase (POS)", "tags": [ "Invoices" ], "description": "Start an invoice-based purchase from POS. Creates a tab settlement and initiates payment via the invoice PSP.\n\n**Permissions:** 🟢 `invoices.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID to pay" }, "locationId": { "type": "number", "description": "Location ID" }, "recipientId": { "type": "string", "format": "uuid", "description": "Invoice recipient UUID" }, "selectedKitchenDispatchItemIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional: specific kitchen dispatch item IDs to pay. If omitted, pays all unpaid items." }, "voucherCodes": { "type": "array", "items": { "type": "string" }, "description": "Optional: voucher codes to apply to this payment." } }, "required": [ "tabId", "locationId" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "purchaseIntentId": { "type": "string", "format": "uuid" }, "invoiceReference": { "type": "string", "nullable": true } }, "required": [ "success", "purchaseIntentId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/invoices/unclaimed-purchases": { "get": { "summary": "Get unclaimed invoice purchases", "tags": [ "Invoices" ], "description": "Get purchases that were made with invoice payment but not yet assigned to an invoice.\n\n**Permissions:** 🔵 `invoices.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID (required)" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Purchase ID" }, "intentId": { "type": "string", "description": "Intent ID" }, "purchasedAt": { "type": "string", "format": "date-time", "description": "Purchase timestamp" }, "payingUserId": { "type": "number", "nullable": true, "description": "Paying user ID" }, "state": { "type": "string", "description": "Purchase state" }, "currencyCode": { "type": "string", "description": "Currency code" }, "totalAmountCents": { "type": "number", "description": "Total amount in cents" }, "vatAmountCents": { "type": "number", "description": "VAT amount in cents" }, "items": { "type": "string", "nullable": true, "description": "Comma-separated list of items" }, "userEmail": { "type": "string", "nullable": true, "description": "User email" }, "userName": { "type": "string", "nullable": true, "description": "User name" } }, "required": [ "id", "intentId", "purchasedAt", "state", "currencyCode", "totalAmountCents", "vatAmountCents" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "items", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/location-maps": { "get": { "summary": "List location maps", "tags": [ "Location Maps" ], "description": "List location maps with optional filtering\n\n**Permissions:** 🔵 `location_maps.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "maps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique location map ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID" }, "context": { "type": "object", "additionalProperties": true, "description": "JSON object with map configuration and layout data" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "context", "createdAt", "updatedAt" ] } } }, "required": [ "maps" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create location map", "tags": [ "Location Maps" ], "description": "Create a new location map\n\n**Permissions:** 🟢 `location_maps.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID" }, "context": { "type": "object", "additionalProperties": true, "description": "JSON object with map configuration" } }, "required": [ "locationId", "context" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique location map ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID" }, "context": { "type": "object", "additionalProperties": true, "description": "JSON object with map configuration and layout data" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "context", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/location-maps/{id}": { "get": { "summary": "Get location map", "tags": [ "Location Maps" ], "description": "Get a single location map by ID\n\n**Permissions:** 🔵 `location_maps.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Location map UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique location map ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID" }, "context": { "type": "object", "additionalProperties": true, "description": "JSON object with map configuration and layout data" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "context", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update location map", "tags": [ "Location Maps" ], "description": "Update an existing location map\n\n**Permissions:** 🟠 `location_maps.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "object", "additionalProperties": true, "description": "Updated JSON object with map configuration" } }, "required": [ "context" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Location map UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique location map ID (UUID)" }, "locationId": { "type": "number", "description": "Location ID" }, "context": { "type": "object", "additionalProperties": true, "description": "JSON object with map configuration and layout data" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "locationId", "context", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete location map", "tags": [ "Location Maps" ], "description": "Delete a location map\n\n**Permissions:** 🔴 `location_maps.delete`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Location map UUID" } ], "responses": { "200": { "description": "Location map successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations": { "post": { "summary": "Create a new location", "tags": [ "Locations" ], "description": "Create a new location for the merchant. The location will be linked to the same company as the user's current active location.\n\n**Hierarchy Options:**\n- **Standalone** (default): Independent location with no parent\n- **Parent**: Set `isRootCompany: true` to mark as a parent/root location\n- **Child**: Provide `parentLocationId` to create as a child of another location\n\n**Payout Account:**\nA payout account will be created with the specified PSP (STRIPE or ADYEN). For Adyen, `billingEmail` is required.\n\n**Required Fields:**\n- `name`: Location name (1-255 characters)\n- `address`: Street address\n- `city`: City name\n- `country`: Country code (e.g., SE, NO)\n- `psp`: Payment Service Provider (STRIPE or ADYEN)\n\n**Permissions:** 🟢 `locations.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Location name (1-255 characters)" }, "address": { "type": "string", "minLength": 1, "description": "Street address" }, "city": { "type": "string", "minLength": 1, "description": "City name" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Country code (e.g., SE, NO, DK)" }, "psp": { "type": "string", "enum": [ "STRIPE", "ADYEN" ], "description": "Payment Service Provider for payout account (STRIPE or ADYEN)" }, "parentLocationId": { "type": "number", "description": "Parent location ID (required for child locations)" }, "locationType": { "type": "string", "enum": [ "company_hq", "division", "region", "area", "city", "store", "warehouse", "kitchen", "office", "other" ], "description": "Type of location in the organization hierarchy" }, "isRootCompany": { "type": "boolean", "description": "Set to true to mark this as a parent/root company location" }, "timezone": { "type": "string", "description": "Timezone name (e.g., Europe/Stockholm). Defaults to parent location or company default." }, "currency": { "type": "string", "description": "Currency code (e.g., SEK). Defaults to parent location or company default." }, "zip": { "type": "string", "description": "ZIP/postal code" }, "billingEmail": { "type": "string", "format": "email", "description": "Billing email address (required if psp is ADYEN)" } }, "required": [ "name", "address", "city", "country", "psp" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique location ID" }, "name": { "type": "string", "description": "Location name" }, "companyId": { "type": "number", "description": "Company ID this location belongs to" }, "address": { "type": "string", "nullable": true, "description": "Street address" }, "city": { "type": "string", "nullable": true, "description": "City name" }, "zip": { "type": "string", "nullable": true, "description": "ZIP/postal code" }, "country": { "type": "string", "nullable": true, "description": "Country code (SE, NO, etc.)" }, "timezone": { "type": "string", "nullable": true, "description": "Timezone name (e.g., Europe/Stockholm)" }, "currency": { "type": "string", "nullable": true, "description": "Currency code (e.g., SEK)" }, "parentLocationId": { "type": "number", "nullable": true, "description": "Parent location ID for hierarchy" }, "locationType": { "type": "string", "enum": [ "company_hq", "division", "region", "area", "city", "store", "warehouse", "kitchen", "office", "other" ], "description": "Type of location in the hierarchy", "nullable": true }, "isRootCompany": { "type": "boolean", "nullable": true, "description": "Whether this is a root company location" }, "hierarchyMetadata": { "type": "object", "nullable": true, "description": "Hierarchy metadata (level, path, etc.)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "companyId", "createdAt", "updatedAt" ] }, "payoutAccount": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "Payout account ID" }, "psp": { "type": "string", "enum": [ "STRIPE", "ADYEN" ], "description": "Payment Service Provider for payout account" } }, "required": [ "id", "psp" ] } }, "required": [ "location", "payoutAccount" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}": { "get": { "summary": "Get a location by ID", "tags": [ "Locations" ], "description": "Get detailed information about a specific location, including its feature toggles.\n\n**Features:**\nBy default, the response includes all available features and their status for this location.\nSet `includeFeatures=false` to exclude features from the response.\n\n**Response includes:**\n- Location details (name, address, timezone, currency, etc.)\n- Feature toggles with enabled status and optional metadata\n- Hierarchy information if applicable\n\n**Permissions:** 🔵 `locations.read`", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "includeFeatures", "required": false, "description": "Include feature toggles in response (default: true)" }, { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "location": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique location ID" }, "name": { "type": "string", "description": "Location name" }, "companyId": { "type": "number", "description": "Company ID this location belongs to" }, "address": { "type": "string", "nullable": true, "description": "Street address" }, "city": { "type": "string", "nullable": true, "description": "City name" }, "zip": { "type": "string", "nullable": true, "description": "ZIP/postal code" }, "country": { "type": "string", "nullable": true, "description": "Country code (SE, NO, etc.)" }, "timezone": { "type": "string", "nullable": true, "description": "Timezone name (e.g., Europe/Stockholm)" }, "currency": { "type": "string", "nullable": true, "description": "Currency code (e.g., SEK)" }, "parentLocationId": { "type": "number", "nullable": true, "description": "Parent location ID for hierarchy" }, "locationType": { "type": "string", "enum": [ "company_hq", "division", "region", "area", "city", "store", "warehouse", "kitchen", "office", "other" ], "description": "Type of location in the hierarchy", "nullable": true }, "isRootCompany": { "type": "boolean", "nullable": true, "description": "Whether this is a root company location" }, "hierarchyMetadata": { "type": "object", "nullable": true, "description": "Hierarchy metadata (level, path, etc.)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "features": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Feature key identifier" }, "category": { "type": "string", "enum": [ "ordering", "kitchen", "loyalty", "payments", "inventory", "integrations", "storefront", "operations" ], "description": "Feature category" }, "enabled": { "type": "boolean", "description": "Whether the feature is enabled for this location" }, "metadata": { "type": "object", "nullable": true, "description": "Optional feature configuration metadata" } }, "required": [ "key", "category", "enabled" ] }, "description": "List of features and their status for this location" } }, "required": [ "id", "name", "companyId", "createdAt", "updatedAt" ] } }, "required": [ "location" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/features/{featureKey}": { "get": { "summary": "Check if a feature is enabled for a location", "tags": [ "Locations" ], "description": "Quick check if a specific feature is enabled for a location.\n\n**Use cases:**\n- Feature gating in UI components\n- Conditional logic based on feature availability\n- Quick feature checks without fetching full location data\n\n**Permissions:** 🔵 `locations.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string" }, "in": "path", "name": "featureKey", "required": true, "description": "Feature key to check (e.g., loyalty, kds, pos)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "featureKey": { "type": "string", "description": "Feature key that was checked" }, "enabled": { "type": "boolean", "description": "Whether the feature is enabled" }, "source": { "type": "string", "enum": [ "location_override", "subscription_override", "plan_included", "feature_default" ], "description": "Where this feature setting comes from" } }, "required": [ "featureKey", "enabled" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/hierarchy": { "get": { "summary": "Get location hierarchy tree", "tags": [ "Locations" ], "description": "Get the location hierarchy tree starting from a specific location. Returns the location and all its descendants in a tree structure.\n\n**Permissions:** 🔵 `locations.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Root location ID to get hierarchy for" } ], "responses": { "200": { "description": "Location hierarchy retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Location name" }, "type": { "type": "string", "nullable": true, "description": "Location type (restaurant, kitchen, etc.)" }, "level": { "type": "number", "description": "Hierarchy level (0 = root)" }, "children": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "type": { "type": "string", "nullable": true }, "level": { "type": "number" } } }, "description": "Child locations" } }, "required": [ "id", "name", "level" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] }, "example": { "status": "success", "data": { "id": 100, "name": "Main Restaurant", "type": "restaurant", "level": 0, "children": [ { "id": 101, "name": "Kitchen 1", "type": "kitchen", "level": 1 }, { "id": 102, "name": "Bar", "type": "bar", "level": 1 } ] }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 15 } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/hours": { "get": { "summary": "Get location opening hours", "tags": [ "Locations" ], "description": "Get opening hours for a location including weekly schedule, exceptions, and current open/closed status", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "scheduleId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the underlying schedule (null if no hours defined)" }, "isOpenNow": { "type": "boolean", "description": "Whether the location is currently open based on these hours" }, "nextStatusChange": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO 8601 timestamp of when the open/closed status will next change" }, "weeklyHours": { "type": "object", "description": "Opening hours for each day of the week", "properties": { "monday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "tuesday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "wednesday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "thursday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "friday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "saturday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "sunday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] } } }, "exceptions": { "type": "array", "items": { "type": "object", "description": "Holiday or special hours exception", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique exception ID (for existing exceptions)" }, "name": { "type": "string", "description": "Name of the exception (e.g., \"Christmas Day\")" }, "date": { "type": "string", "format": "date", "description": "Single date in YYYY-MM-DD format (mutually exclusive with startDate/endDate)" }, "startDate": { "type": "string", "format": "date", "description": "Start date for a date range (use with endDate)" }, "endDate": { "type": "string", "format": "date", "description": "End date for a date range (use with startDate)" }, "closed": { "type": "boolean", "description": "Whether the location is closed during this exception" }, "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time if not closed (HH:MM format)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time if not closed (HH:MM format)" } }, "required": [ "name", "closed" ] }, "description": "List of exceptions (holidays, special hours)" } }, "required": [ "scheduleId", "isOpenNow", "nextStatusChange", "weeklyHours", "exceptions" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update location opening hours", "tags": [ "Locations" ], "description": "Update or create opening hours for a location. This replaces the entire schedule.\n\n**Permissions:** 🟠 `schedules.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "weeklyHours": { "type": "object", "description": "Opening hours for each day of the week. Days not provided will be left unchanged.", "properties": { "monday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "tuesday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "wednesday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "thursday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "friday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "saturday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "sunday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] } } }, "exceptions": { "type": "array", "items": { "type": "object", "description": "Holiday or special hours exception", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique exception ID (for existing exceptions)" }, "name": { "type": "string", "description": "Name of the exception (e.g., \"Christmas Day\")" }, "date": { "type": "string", "format": "date", "description": "Single date in YYYY-MM-DD format (mutually exclusive with startDate/endDate)" }, "startDate": { "type": "string", "format": "date", "description": "Start date for a date range (use with endDate)" }, "endDate": { "type": "string", "format": "date", "description": "End date for a date range (use with startDate)" }, "closed": { "type": "boolean", "description": "Whether the location is closed during this exception" }, "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time if not closed (HH:MM format)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time if not closed (HH:MM format)" } }, "required": [ "name", "closed" ] }, "description": "List of exceptions to set (replaces all existing exceptions)" } }, "required": [ "weeklyHours" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "scheduleId": { "type": "string", "nullable": true, "format": "uuid", "description": "ID of the underlying schedule (null if no hours defined)" }, "isOpenNow": { "type": "boolean", "description": "Whether the location is currently open based on these hours" }, "nextStatusChange": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO 8601 timestamp of when the open/closed status will next change" }, "weeklyHours": { "type": "object", "description": "Opening hours for each day of the week", "properties": { "monday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "tuesday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "wednesday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "thursday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "friday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "saturday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] }, "sunday": { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time in HH:MM format (e.g., 08:00)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time in HH:MM format (e.g., 22:00)" }, "closed": { "type": "boolean", "description": "Whether the location is closed on this day" } }, "required": [ "closed" ] } } }, "exceptions": { "type": "array", "items": { "type": "object", "description": "Holiday or special hours exception", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique exception ID (for existing exceptions)" }, "name": { "type": "string", "description": "Name of the exception (e.g., \"Christmas Day\")" }, "date": { "type": "string", "format": "date", "description": "Single date in YYYY-MM-DD format (mutually exclusive with startDate/endDate)" }, "startDate": { "type": "string", "format": "date", "description": "Start date for a date range (use with endDate)" }, "endDate": { "type": "string", "format": "date", "description": "End date for a date range (use with startDate)" }, "closed": { "type": "boolean", "description": "Whether the location is closed during this exception" }, "open": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Opening time if not closed (HH:MM format)" }, "close": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$", "description": "Closing time if not closed (HH:MM format)" } }, "required": [ "name", "closed" ] }, "description": "List of exceptions (holidays, special hours)" } }, "required": [ "scheduleId", "isOpenNow", "nextStatusChange", "weeklyHours", "exceptions" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete location opening hours", "tags": [ "Locations" ], "description": "Remove opening hours for a location (makes it always open)\n\n**Permissions:** 🔴 `schedules.delete`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "deleted", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/pickup-settings": { "get": { "summary": "Get pickup settings for a location", "tags": [ "Locations" ], "description": "Get pickup settings and exceptional sale times for a location.\n\n**Response includes:**\n- `pickupSettings`: Configuration for time slot selection (enabled, days in advance)\n- `exceptionalSaleTimes`: Special dates with modified hours or closures (holidays, events, etc.)\n\n**Use cases:**\n- Displaying time slot picker in checkout flow\n- Determining if pickup time selection is available\n- Showing modified hours for upcoming dates\n\n**Permissions:** 🔵 `locations.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "exceptionalSaleTimes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier for the exceptional sale time" }, "name": { "type": "string", "nullable": true, "description": "Name/description of the exceptional period" }, "startDate": { "type": "string", "format": "date", "description": "Start date (YYYY-MM-DD)" }, "endDate": { "type": "string", "format": "date", "description": "End date (YYYY-MM-DD)" }, "closed": { "type": "boolean", "description": "Whether the location is closed during this period" }, "saleStartLocal": { "type": "string", "description": "Sale start time in local timezone (HH:MM:SS)" }, "saleEndLocal": { "type": "string", "description": "Sale end time in local timezone (HH:MM:SS)" }, "pickupStartLocal": { "type": "string", "description": "Pickup start time in local timezone (HH:MM:SS)" }, "pickupEndLocal": { "type": "string", "description": "Pickup end time in local timezone (HH:MM:SS)" } }, "required": [ "id", "startDate", "endDate", "closed", "saleStartLocal", "saleEndLocal", "pickupStartLocal", "pickupEndLocal" ] }, "description": "List of exceptional sale times (holidays, special hours, closures)" }, "pickupSettings": { "type": "object", "properties": { "pickupTimeEnabled": { "type": "boolean", "description": "Whether time slot selection is enabled" }, "pickupDaysInAdvanceAllowed": { "type": "number", "description": "Number of days in advance customers can select pickup time" }, "takeawayEnabled": { "type": "boolean", "description": "Whether takeaway is enabled" }, "defaultPreparationTimeSeconds": { "type": "number", "description": "Default preparation time in seconds" }, "autoacceptMinutesBeforePickup": { "type": "number", "description": "Minutes before pickup when orders are automatically accepted" }, "pickupInformation": { "type": "string", "nullable": true, "description": "Pickup information text" }, "defaultTakeawayVatId": { "type": "number", "nullable": true, "description": "Default VAT rate ID for takeaway orders" } }, "required": [ "pickupTimeEnabled", "pickupDaysInAdvanceAllowed", "takeawayEnabled", "defaultPreparationTimeSeconds", "autoacceptMinutesBeforePickup", "pickupInformation", "defaultTakeawayVatId" ], "nullable": true, "description": "Pickup time slot configuration" } }, "required": [ "exceptionalSaleTimes", "pickupSettings" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/qr-codes": { "get": { "summary": "Get QR codes for a location", "tags": [ "Locations" ], "description": "Get all active QR codes (tables) for a location.\n\n**Response includes:**\n- Array of QR codes with uuid and name\n- Only active QR codes are returned\n- Sorted alphabetically by name\n\n**Use cases:**\n- Displaying table selection in storefront\n- Managing table orders\n- QR code scanning for dine-in orders\n\n**Permissions:** 🔵 `locations.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Unique identifier for the QR code" }, "name": { "type": "string", "description": "Name/label for the QR code (e.g., table number)" }, "groupId": { "type": [ "null", "integer" ], "description": "Group/section id (e.g. \"Fönsterbord\")" }, "groupName": { "type": [ "null", "string" ], "description": "Group/section display name" }, "payment_flow": { "type": [ "null", "string" ], "enum": [ "pay_upfront", "open_tab", null ], "description": "Forced payment flow for this QR" }, "kiosk": { "type": [ "null", "boolean" ], "description": "Kiosk-mode QR (shared terminal)" }, "limitation": { "type": [ "null", "string" ], "enum": [ "view", "order", null ], "description": "Viewing-only vs. ordering QR" }, "joinTabLimitations": { "type": [ "null", "string" ], "enum": [ "join_order_and_pay", "join_pay_only", "join_disabled", null ] }, "menuLayoutId": { "type": [ "null", "string" ], "description": "Pin this QR to a specific menu layout (UUID)" }, "room": { "type": [ "null", "string" ], "description": "Room identifier (hotel room service)" }, "newTabPerGuest": { "type": [ "null", "boolean" ], "description": "Force a new tab per scan (shared QRs)" }, "terminal": { "type": [ "null", "string" ], "description": "Attached Adyen card reader UUID (kiosk only)" }, "printer": { "type": [ "null", "string" ], "description": "Attached receipt printer UUID (kiosk only)" } }, "required": [ "uuid", "name" ] }, "description": "List of QR codes for the location" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/set-parent": { "post": { "summary": "Set parent location", "tags": [ "Locations" ], "description": "Set or change the parent location for a location. This updates the location hierarchy and refreshes the materialized access view.\n\n**Permissions:** 🟠 `locations.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "parentLocationId": { "type": "number", "nullable": true, "description": "Parent location ID (null to make root location)" } }, "required": [ "parentLocationId" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID to update" } ], "responses": { "200": { "description": "Location parent updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Location name" }, "parentLocationId": { "type": "number", "nullable": true, "description": "New parent location ID" }, "hierarchyMetadata": { "type": "object", "properties": { "level": { "type": "number", "description": "Hierarchy level" }, "path": { "type": "array", "items": { "type": "number" }, "description": "Array of location IDs from root to this location" }, "is_root": { "type": "boolean", "description": "Whether this is a root location" } }, "description": "Updated hierarchy metadata" } }, "required": [ "id", "name" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] }, "example": { "status": "success", "data": { "id": 101, "name": "Kitchen 1", "parentLocationId": 100, "hierarchyMetadata": { "level": 1, "path": [ 100, 101 ], "is_root": false } }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 25 } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/settings": { "patch": { "summary": "Update location settings", "tags": [ "Locations" ], "description": "Update settings for a specific location. Supports partial updates - only provided fields will be updated.\n\n**Supported fields:**\n- `phone`: Phone number (set to null to clear)\n- `website`: Website URL (set to null to clear, max 248 chars)\n- `description`: Location description (set to null to clear, max 1000 chars)\n- `pickupInformation`: Pickup information text\n- `context`: Location context JSON (features, configuration, etc.)\n- `isItemCommentAllowed`: Whether item comments are allowed\n- `orderPlacements`: Order placement configuration per channel\n- `paymentFlow`: Default payment flow (`open_tab` or `pay_upfront`, set to null to clear)\n- `defaultPreparationTimeSeconds`: Default preparation time\n- `takeawayEnabled`: Whether takeaway is enabled\n- `autoacceptMinutesBeforePickup`: Minutes before pickup for auto-accept\n- `pickupTimeEnabled`: Whether time slot selection is enabled\n- `pickupDaysInAdvanceAllowed`: Days in advance for pickup time selection\n\n**Permissions:** 🟠 `locations.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "nullable": true, "description": "Phone number" }, "website": { "type": "string", "nullable": true, "maxLength": 248, "description": "Website URL" }, "description": { "type": "string", "nullable": true, "maxLength": 1000, "description": "Location description" }, "pickupInformation": { "type": "string", "nullable": true, "description": "Pickup information text" }, "context": { "oneOf": [ { "type": "object", "description": "Context JSON object" }, { "type": "string", "description": "Context as JSON string" }, { "type": "null" } ], "description": "Location context (JSON)" }, "isItemCommentAllowed": { "type": "boolean", "description": "Whether item comments are allowed" }, "orderPlacements": { "type": "object", "description": "Order placement configuration per channel" }, "paymentFlow": { "oneOf": [ { "type": "string", "enum": [ "open_tab", "pay_upfront" ] }, { "type": "null" } ], "description": "Default payment flow for this location" }, "defaultPreparationTimeSeconds": { "type": "number", "description": "Default preparation time in seconds" }, "takeawayEnabled": { "type": "boolean", "description": "Whether takeaway is enabled" }, "autoacceptMinutesBeforePickup": { "type": "number", "description": "Minutes before pickup when orders are automatically accepted" }, "pickupTimeEnabled": { "type": "boolean", "description": "Whether time slot selection is enabled" }, "pickupDaysInAdvanceAllowed": { "type": "number", "description": "Number of days in advance customers can select pickup time" }, "defaultTakeawayVatId": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Default VAT rate ID for takeaway orders" }, "logoImageUrl": { "type": "string", "nullable": true, "description": "URL of the location logo image (empty string or null to clear)" }, "featureImageUrl": { "type": "string", "nullable": true, "description": "URL of the location feature/background image (empty string or null to clear)" }, "businessDayStartMinutes": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 1439 }, { "type": "null" } ], "description": "Analytics business-day rollover, in minutes from local-time midnight (Europe/Stockholm), 0-1439. null = midnight rollover. Affects /analytics display only — SIE, payouts, receipts use the legal calendar day." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/storefront": { "get": { "summary": "Get location storefront data", "tags": [ "Locations" ], "description": "Get comprehensive storefront data for a location by its ID.\n\n**Response includes:**\n- Location details (name, address, coordinates, contact info)\n- Current sale status and times\n- Opening hours (weekly hours, exceptions, schedule ID)\n- Theme and branding configuration\n- Feature flags and settings\n- Loyalty program information\n- Extended waiting time (if set)\n\nThis returns the same enriched data as the slug-based endpoint, but uses the numeric location ID.\n\n**Permissions:** 🔵 `locations.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "location": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Unique location identifier" }, "name": { "type": "string", "description": "Store name" }, "description": { "type": "string", "nullable": true, "description": "Store description" }, "latitude": { "type": "number", "description": "Latitude coordinate" }, "longitude": { "type": "number", "description": "Longitude coordinate" }, "streetAdress": { "type": "string", "nullable": true, "description": "Street address" }, "zip": { "type": "string", "nullable": true, "description": "ZIP/postal code" }, "city": { "type": "string", "nullable": true, "description": "City" }, "website": { "type": "string", "nullable": true, "description": "Website URL" }, "phone": { "type": "string", "nullable": true, "description": "Phone number" }, "currencyCode": { "type": "string", "enum": [ "SEK", "GBP", "EUR", "DKK", "NOK", "ISK", "JPY" ], "description": "Currency code" }, "logoImageUrl": { "type": "string", "nullable": true, "description": "Logo image URL" }, "featureImageUrl": { "type": "string", "nullable": true, "description": "Feature image URL" }, "pickupInformation": { "type": "string", "nullable": true, "description": "Pickup instructions" }, "averageRating": { "type": "number", "nullable": true, "description": "Average customer rating" }, "saleStatus": { "type": "string", "enum": [ "open", "closed", "delivering", "paused", "undecided", "waiting" ], "description": "Current sale status" }, "saleStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Sale start time" }, "saleEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Sale end time" }, "salePickupStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Pickup window start" }, "salePickupEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Pickup window end" }, "defaultPreparationTimeSeconds": { "type": "number", "description": "Default order prep time in seconds" }, "timeSlotDurationInMinutes": { "type": "number", "nullable": true, "description": "Time slot duration" }, "psp": { "type": "string", "enum": [ "adyen" ], "description": "Payment service provider" }, "extendedWaitingTime": { "type": "object", "nullable": true, "properties": { "id": { "type": "number" }, "locationId": { "type": "number" }, "endsAt": { "type": "string", "format": "date-time" }, "delayInMinutes": { "type": "number", "nullable": true } }, "required": [ "id", "locationId", "endsAt" ] }, "isItemCommentAllowed": { "type": "boolean", "description": "Whether item comments are allowed" }, "takeawayEnabled": { "type": "boolean", "description": "Whether takeaway is enabled" }, "isMigratedToPurchase": { "type": "boolean", "description": "Whether migrated to purchase payments" }, "isDiscountsEnabled": { "type": "boolean", "description": "Whether discounts are enabled" }, "isScanToTabEnabled": { "type": "boolean", "description": "Whether scan-to-tab is enabled" }, "isSplitItemEnabled": { "type": "boolean", "description": "Whether split item is enabled" }, "isUserSessionsEnabled": { "type": "boolean", "description": "Whether user sessions are enabled" }, "defaultTakeawayVatValue": { "type": "number", "nullable": true, "description": "Default takeaway VAT rate for this location (basis points). When set and no item-specific takeaway VAT is defined, this rate applies to takeaway orders." }, "orderPlacements": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Order placement configuration" }, "timezone": { "type": "string", "description": "Timezone (e.g., Europe/Stockholm)" }, "context": { "type": "string", "nullable": true, "description": "Location context JSON string" }, "smsNotifications": { "type": "boolean", "description": "Whether SMS notifications are enabled" }, "swishConfig": { "type": "object", "nullable": true, "properties": { "number": { "type": "number", "description": "Swish number" } } }, "themes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "brandPrimaryColor": { "type": "string", "nullable": true }, "brandColorTextOnPrimary": { "type": "string", "nullable": true }, "brandFontPath": { "type": "string", "nullable": true }, "brandFontFamily": { "type": "string", "nullable": true } }, "required": [ "id" ] }, "description": "Location themes" }, "locationCenters": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "logo": { "type": "string", "nullable": true }, "visibleMenuGroups": { "type": "array", "items": { "type": "number" } }, "themeId": { "type": "number", "nullable": true } }, "required": [ "id", "name", "visibleMenuGroups" ] }, "description": "Location centers" }, "tip": { "type": "boolean", "description": "Whether tipping is enabled" }, "externalName": { "type": "string", "nullable": true, "description": "External display name" }, "externalTos": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string" }, "link": { "type": "string" } }, "required": [ "name", "link" ] }, "description": "External terms of service links" }, "loyaltyProgram": { "type": "object", "properties": { "programId": { "type": "number" }, "name": { "type": "string" }, "slug": { "type": "string" }, "baseColor": { "type": "string" }, "pointConversion": { "type": "object", "nullable": true, "properties": { "everyXCents": { "type": "number" }, "earnYPoints": { "type": "number" } } } }, "required": [ "programId", "name", "slug", "baseColor" ], "description": "Loyalty program information" }, "isOpenNow": { "type": "boolean", "description": "Whether the location is currently open based on opening hours schedule" }, "nextStatusChange": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO 8601 timestamp of when the open/closed status will next change" }, "scheduleId": { "type": "string", "nullable": true, "description": "Schedule ID for the location hours" }, "weeklyHours": { "type": "object", "properties": { "monday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "tuesday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "wednesday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "thursday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "friday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "saturday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "sunday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] } }, "description": "Weekly opening hours from the schedules system" }, "exceptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "closed": { "type": "boolean" }, "date": { "type": "string", "description": "YYYY-MM-DD for single date" }, "startDate": { "type": "string", "description": "YYYY-MM-DD for date range start" }, "endDate": { "type": "string", "description": "YYYY-MM-DD for date range end" }, "open": { "type": "string", "description": "HH:MM if not closed" }, "close": { "type": "string", "description": "HH:MM if not closed" } }, "required": [ "name", "closed" ] }, "description": "Exceptions to regular hours (holidays, special hours)" }, "features": { "type": "array", "items": { "type": "string" }, "description": "Enabled feature keys for this location (e.g. [\"reservations\", \"pos\"]). Storefronts gate optional UI on these — e.g. the booking page requires \"reservations\"." }, "pickupDaysInAdvanceAllowed": { "type": "number", "description": "Number of days in advance customers can select a pickup time slot for takeaway orders" } }, "required": [ "locationId", "name", "latitude", "longitude", "currencyCode", "averageRating", "saleStatus", "defaultPreparationTimeSeconds", "psp", "isItemCommentAllowed", "takeawayEnabled", "isMigratedToPurchase", "isDiscountsEnabled", "isScanToTabEnabled", "isSplitItemEnabled", "orderPlacements", "timezone" ] } }, "required": [ "location" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/voucher-provider": { "get": { "summary": "Get a location's voucher provider and display name", "tags": [ "Locations" ], "description": "Returns the location's voucher provider type and a ready-to-render display name.\n\n**Behavior:**\n- `voucher_provider='trivec'` → `providerDisplayName: 'Trivec'` (hardcoded, never leaks voucherService)\n- `voucher_provider='custom'` with valid displayName → `providerDisplayName: `\n- `voucher_provider='custom'` with displayName containing the forbidden third-party vendor substring (case-insensitive) → `providerDisplayName: null`\n- No integration_configs row OR `voucher_provider IS NULL` → `{ voucherProvider: 'karma', providerDisplayName: null }`\n\n**Permissions:** 🔵 `locations.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "voucherProvider", "providerDisplayName" ], "properties": { "voucherProvider": { "type": "string", "enum": [ "karma", "trivec", "custom" ], "description": "The location's voucher provider type" }, "providerDisplayName": { "type": [ "null", "string" ], "description": "Ready-to-render display name (null when unknown or filtered)" } } }, "meta": { "type": "object" } } } } } } } }, "put": { "summary": "Update voucher provider configuration for a location", "tags": [ "Locations" ], "description": "Upserts integration_configs.voucher_provider and settings in a single transaction.\n\n**Body is a tagged union by provider:**\n- `{ provider: 'karma' }` — switch back to native Karma vouchers (no settings)\n- `{ provider: 'trivec' }` — enable Trivec; credentials are provisioned out-of-band, never via merchant PUT (CRED-02)\n- `{ provider: 'custom', settings: {...} }` — configure a custom HTTP voucher provider\n\n**Server-side behaviour:**\n- Custom provider secrets are AES-256-CBC encrypted server-side; plaintext is expected in the request body over HTTPS.\n- Requests containing the forbidden third-party vendor substring (case-insensitive) in any string value are rejected with 400 before reaching the DB.\n- In-flight voucher reservations or a non-empty DLQ block provider switches with 409 to prevent double-spend.\n\n**Permissions:** 🟠 `locations.update`", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "karma" ] } }, "required": [ "provider" ], "additionalProperties": false }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "trivec" ] } }, "required": [ "provider" ], "additionalProperties": false }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom" ] }, "settings": { "type": "object", "properties": { "displayName": { "type": "string" }, "checkUrl": { "type": "string", "format": "uri" }, "commitUrl": { "type": "string", "format": "uri" }, "reactivateUrl": { "type": "string", "format": "uri" }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "basic" ] }, "username": { "type": "string" }, "password": { "type": "string", "description": "Plaintext; server-side AES-256-CBC encrypts before storage. Omit to preserve stored ciphertext (D-03)." } }, "required": [ "type", "username" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "headers" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Plaintext header map; each value encrypted server-side. Omit to preserve stored ciphertext (D-03)." } }, "required": [ "type" ], "additionalProperties": false } ] } }, "required": [ "displayName", "checkUrl", "commitUrl", "reactivateUrl", "auth" ], "additionalProperties": false } }, "required": [ "provider", "settings" ], "additionalProperties": false } ], "description": "Voucher provider write body — tagged union by provider. Karma and Trivec variants accept only { provider }; any settings field is rejected (CRED-02). Custom variant requires a settings object." } } }, "description": "Voucher provider write body — tagged union by provider. Karma and Trivec variants accept only { provider }; any settings field is rejected (CRED-02). Custom variant requires a settings object." }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "karma", "trivec", "custom" ], "description": "Voucher provider type" }, "displayName": { "type": [ "null", "string" ], "description": "Ready-to-render display name (null when unknown or filtered)" }, "checkUrl": { "type": "string", "description": "Custom provider check URL (custom only)" }, "commitUrl": { "type": "string", "description": "Custom provider commit URL (custom only)" }, "reactivateUrl": { "type": "string", "description": "Custom provider reactivate URL (custom only)" }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "basic" ] }, "username": { "type": "string" }, "passwordSet": { "type": "boolean", "enum": [ true ] } }, "required": [ "type", "username", "passwordSet" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "headers" ] }, "passwordSet": { "type": "boolean", "enum": [ true ] } }, "required": [ "type", "passwordSet" ], "additionalProperties": false } ] }, "lastTestedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Timestamp of the most recent /test invocation (D-14). Null when never tested." }, "lastTestReachable": { "type": [ "null", "boolean" ], "description": "Outcome of the most recent /test invocation (D-14). Null when never tested." } }, "required": [ "provider" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] } } } } } } }, "/api/v1/locations/{locationId}/voucher-provider/test": { "post": { "summary": "Test connectivity to the configured Trivec voucher provider", "tags": [ "Locations" ], "description": "Calls Trivec /voucher/services via integrations-service using the currently-saved config.\n\n**Behaviour:**\n- Persists `last_tested_at` and `last_test_reachable` on integration_configs.\n- Non-Trivec providers return 400 INVALID_PROVIDER_FOR_TEST.\n- Does not emit platform_events (D-08).\n\n**Permissions:** 🟠 `locations.update`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "reachable": { "type": "boolean", "description": "True if the provider responded successfully" }, "latencyMs": { "type": "number", "description": "Round-trip latency in milliseconds" }, "error": { "type": "string", "description": "Error message when reachable=false" } }, "required": [ "reachable", "latencyMs" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] } } } } } } }, "/api/v1/locations/slug/{slug}": { "get": { "summary": "Get location by slug", "tags": [ "Locations" ], "description": "Get comprehensive location information by its URL slug.\n\n**Response includes:**\n- Location details (name, address, coordinates, contact info)\n- Current sale status and times\n- Opening hours (weekly hours, exceptions, schedule ID)\n- Theme and branding configuration\n- Feature flags and settings (discounts, scan-to-tab, split items, etc.)\n- Loyalty program information\n- Extended waiting time (if set)\n\nThis is the primary endpoint for storefront applications to fetch location data.\nThe slug is the URL-friendly identifier for the location (e.g., \"joes-pizza\").\n\n**Permissions:** 🔵 `locations.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "slug", "required": true, "description": "Location URL slug (e.g., \"joes-pizza\")" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "location": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Unique location identifier" }, "name": { "type": "string", "description": "Store name" }, "description": { "type": "string", "nullable": true, "description": "Store description" }, "latitude": { "type": "number", "description": "Latitude coordinate" }, "longitude": { "type": "number", "description": "Longitude coordinate" }, "streetAdress": { "type": "string", "nullable": true, "description": "Street address" }, "zip": { "type": "string", "nullable": true, "description": "ZIP/postal code" }, "city": { "type": "string", "nullable": true, "description": "City" }, "website": { "type": "string", "nullable": true, "description": "Website URL" }, "phone": { "type": "string", "nullable": true, "description": "Phone number" }, "currencyCode": { "type": "string", "enum": [ "SEK", "GBP", "EUR", "DKK", "NOK", "ISK", "JPY" ], "description": "Currency code" }, "logoImageUrl": { "type": "string", "nullable": true, "description": "Logo image URL" }, "featureImageUrl": { "type": "string", "nullable": true, "description": "Feature image URL" }, "pickupInformation": { "type": "string", "nullable": true, "description": "Pickup instructions" }, "averageRating": { "type": "number", "nullable": true, "description": "Average customer rating" }, "saleStatus": { "type": "string", "enum": [ "open", "closed", "delivering", "paused", "undecided", "waiting" ], "description": "Current sale status" }, "saleStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Sale start time" }, "saleEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Sale end time" }, "salePickupStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Pickup window start" }, "salePickupEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Pickup window end" }, "defaultPreparationTimeSeconds": { "type": "number", "description": "Default order prep time in seconds" }, "timeSlotDurationInMinutes": { "type": "number", "nullable": true, "description": "Time slot duration" }, "psp": { "type": "string", "enum": [ "adyen" ], "description": "Payment service provider" }, "extendedWaitingTime": { "type": "object", "nullable": true, "properties": { "id": { "type": "number" }, "locationId": { "type": "number" }, "endsAt": { "type": "string", "format": "date-time" }, "delayInMinutes": { "type": "number", "nullable": true } }, "required": [ "id", "locationId", "endsAt" ] }, "isItemCommentAllowed": { "type": "boolean", "description": "Whether item comments are allowed" }, "takeawayEnabled": { "type": "boolean", "description": "Whether takeaway is enabled" }, "isMigratedToPurchase": { "type": "boolean", "description": "Whether migrated to purchase payments" }, "isDiscountsEnabled": { "type": "boolean", "description": "Whether discounts are enabled" }, "isScanToTabEnabled": { "type": "boolean", "description": "Whether scan-to-tab is enabled" }, "isSplitItemEnabled": { "type": "boolean", "description": "Whether split item is enabled" }, "isUserSessionsEnabled": { "type": "boolean", "description": "Whether user sessions are enabled" }, "defaultTakeawayVatValue": { "type": "number", "nullable": true, "description": "Default takeaway VAT rate for this location (basis points). When set and no item-specific takeaway VAT is defined, this rate applies to takeaway orders." }, "orderPlacements": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Order placement configuration" }, "timezone": { "type": "string", "description": "Timezone (e.g., Europe/Stockholm)" }, "context": { "type": "string", "nullable": true, "description": "Location context JSON string" }, "smsNotifications": { "type": "boolean", "description": "Whether SMS notifications are enabled" }, "swishConfig": { "type": "object", "nullable": true, "properties": { "number": { "type": "number", "description": "Swish number" } } }, "themes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "brandPrimaryColor": { "type": "string", "nullable": true }, "brandColorTextOnPrimary": { "type": "string", "nullable": true }, "brandFontPath": { "type": "string", "nullable": true }, "brandFontFamily": { "type": "string", "nullable": true } }, "required": [ "id" ] }, "description": "Location themes" }, "locationCenters": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "logo": { "type": "string", "nullable": true }, "visibleMenuGroups": { "type": "array", "items": { "type": "number" } }, "themeId": { "type": "number", "nullable": true } }, "required": [ "id", "name", "visibleMenuGroups" ] }, "description": "Location centers" }, "tip": { "type": "boolean", "description": "Whether tipping is enabled" }, "externalName": { "type": "string", "nullable": true, "description": "External display name" }, "externalTos": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string" }, "link": { "type": "string" } }, "required": [ "name", "link" ] }, "description": "External terms of service links" }, "loyaltyProgram": { "type": "object", "properties": { "programId": { "type": "number" }, "name": { "type": "string" }, "slug": { "type": "string" }, "baseColor": { "type": "string" }, "pointConversion": { "type": "object", "nullable": true, "properties": { "everyXCents": { "type": "number" }, "earnYPoints": { "type": "number" } } } }, "required": [ "programId", "name", "slug", "baseColor" ], "description": "Loyalty program information" }, "isOpenNow": { "type": "boolean", "description": "Whether the location is currently open based on opening hours schedule" }, "nextStatusChange": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO 8601 timestamp of when the open/closed status will next change" }, "scheduleId": { "type": "string", "nullable": true, "description": "Schedule ID for the location hours" }, "weeklyHours": { "type": "object", "properties": { "monday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "tuesday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "wednesday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "thursday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "friday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "saturday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] }, "sunday": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time (HH:MM)" }, "close": { "type": "string", "description": "Closing time (HH:MM)" }, "closed": { "type": "boolean", "description": "Whether closed on this day" } }, "required": [ "closed" ] } }, "description": "Weekly opening hours from the schedules system" }, "exceptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "closed": { "type": "boolean" }, "date": { "type": "string", "description": "YYYY-MM-DD for single date" }, "startDate": { "type": "string", "description": "YYYY-MM-DD for date range start" }, "endDate": { "type": "string", "description": "YYYY-MM-DD for date range end" }, "open": { "type": "string", "description": "HH:MM if not closed" }, "close": { "type": "string", "description": "HH:MM if not closed" } }, "required": [ "name", "closed" ] }, "description": "Exceptions to regular hours (holidays, special hours)" }, "features": { "type": "array", "items": { "type": "string" }, "description": "Enabled feature keys for this location (e.g. [\"reservations\", \"pos\"]). Storefronts gate optional UI on these — e.g. the booking page requires \"reservations\"." }, "pickupDaysInAdvanceAllowed": { "type": "number", "description": "Number of days in advance customers can select a pickup time slot for takeaway orders" } }, "required": [ "locationId", "name", "latitude", "longitude", "currencyCode", "averageRating", "saleStatus", "defaultPreparationTimeSeconds", "psp", "isItemCommentAllowed", "takeawayEnabled", "isMigratedToPurchase", "isDiscountsEnabled", "isScanToTabEnabled", "isSplitItemEnabled", "orderPlacements", "timezone" ] } }, "required": [ "location" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/{programId}/import": { "post": { "summary": "Import members from CSV data", "tags": [ "Loyalty Programs" ], "description": "Import multiple members into a loyalty program from parsed CSV data. Supports name, email, phone, initial points, and enrolled date. Creates users if they do not exist.\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "minItems": 1, "maxItems": 5000, "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "points": { "type": "number", "minimum": 0, "description": "Initial points balance" }, "enrolledAt": { "type": "string", "description": "Enrollment date (ISO 8601 or date string)" }, "tier": { "type": "string", "description": "Tier name to assign (case-insensitive, must match a program tier)" } } }, "description": "Array of member objects to import" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "totalProcessed": { "type": "number", "description": "Total rows processed" }, "enrolled": { "type": "number", "description": "Number of new members enrolled" }, "alreadyEnrolled": { "type": "number", "description": "Number already enrolled (points still adjusted if provided)" }, "failed": { "type": "number", "description": "Number of failed imports" }, "results": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "number", "description": "Row number (1-based)" }, "success": { "type": "boolean" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "userId": { "type": "number", "nullable": true }, "pointsSet": { "type": "number", "nullable": true }, "isNew": { "type": "boolean", "description": "Whether this was a newly created enrollment" } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/{programId}/members": { "get": { "summary": "List loyalty members", "tags": [ "Loyalty Programs" ], "description": "Get all members of a loyalty program with pagination and search\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 1000, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" }, { "schema": { "type": "string" }, "in": "query", "name": "sort", "required": false, "description": "Sort field (created_at, current_balance, lifetime_earned, lifetime_redeemed, user_name, user_email, tier_name)" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Sort order" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Search by name, email, or phone" }, { "schema": { "type": "string" }, "in": "query", "name": "tierId", "required": false, "description": "Filter by tier ID, or \"none\" for members without a tier" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Filter members enrolled on or after this date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "Filter members enrolled on or before this date (ISO 8601)" }, { "schema": { "type": "number" }, "in": "query", "name": "minBalance", "required": false, "description": "Minimum current balance" }, { "schema": { "type": "number" }, "in": "query", "name": "maxBalance", "required": false, "description": "Maximum current balance" }, { "schema": { "type": "number" }, "in": "query", "name": "minLifetimeEarned", "required": false, "description": "Minimum lifetime earned points" }, { "schema": { "type": "number" }, "in": "query", "name": "maxLifetimeEarned", "required": false, "description": "Maximum lifetime earned points" }, { "schema": { "type": "number" }, "in": "query", "name": "minLifetimeRedeemed", "required": false, "description": "Minimum lifetime redeemed points" }, { "schema": { "type": "number" }, "in": "query", "name": "maxLifetimeRedeemed", "required": false, "description": "Maximum lifetime redeemed points" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/{programId}/members/{userId}": { "get": { "summary": "Get member details", "tags": [ "Loyalty Programs" ], "description": "Get detailed member information including account, user info, tier, and program details\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "userId", "required": true, "description": "User ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/{programId}/members/{userId}/adjust-points": { "post": { "summary": "Adjust member points", "tags": [ "Loyalty Programs" ], "description": "Manually adjust a member's points balance (add or remove points)\n\n**Permissions:** 🟠 `loyalty.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "points", "reason" ], "properties": { "points": { "type": "number", "description": "Points to add (positive) or remove (negative)" }, "reason": { "type": "string", "description": "Human-readable reason for the adjustment" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "userId", "required": true, "description": "User ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Transaction UUID" }, "pointsAccountId": { "type": "number", "description": "Points account ID" }, "transactionType": { "type": "string", "enum": [ "EARNED_PURCHASE", "EARNED_ITEM", "EARNED_VISIT", "EARNED_ACTION", "REDEEMED", "EXPIRED", "ADJUSTED", "REVOKED" ], "description": "Transaction type" }, "points": { "type": "number", "description": "Points amount (positive for earned, negative for redeemed/expired)" }, "balanceAfter": { "type": "number", "description": "Balance after this transaction" }, "purchaseId": { "type": "number", "nullable": true, "description": "Related purchase ID" }, "earningRuleId": { "type": "number", "nullable": true, "description": "Earning rule that triggered this transaction" }, "rewardRedemptionId": { "type": "number", "nullable": true, "description": "Reward redemption that caused this transaction" }, "description": { "type": "string", "nullable": true, "description": "Human-readable description" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Additional context" }, "expiresAt": { "type": "string", "format": "date", "nullable": true, "description": "When these points expire" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "user": { "type": "object", "nullable": true, "properties": { "email": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "description": "Member who made this transaction" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/{programId}/members/{userId}/redemptions": { "get": { "summary": "Get member redemptions", "tags": [ "Loyalty Programs" ], "description": "Get a member's reward redemption history\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "userId", "required": true, "description": "User ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "redemptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "pointsAccountId": { "type": "number" }, "rewardId": { "type": "number" }, "pointsSpent": { "type": "number" }, "generatedDiscountId": { "type": "number", "nullable": true, "description": "Cloned discount with unique code" }, "generatedCode": { "type": "string", "nullable": true, "description": "Generated voucher code" }, "status": { "type": "string", "enum": [ "active", "used", "expired", "revoked" ] }, "usedAt": { "type": "string", "format": "date-time", "nullable": true }, "usedInPurchaseId": { "type": "number", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/{programId}/members/{userId}/tier": { "put": { "summary": "Assign tier to member", "tags": [ "Loyalty Programs" ], "description": "Manually assign a tier override to a loyalty program member. Assignment type is inferred from auth context (manual for staff JWT, campaign for API key). Optional expiration date.\n\n**Permissions:** ⚪ `loyalty.tier.assign`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "tierId" ], "properties": { "tierId": { "type": "number", "description": "Tier ID to assign" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration date (ISO 8601)" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "userId", "required": true, "description": "User ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Account ID" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "userId": { "type": "number", "description": "User ID" }, "currentBalance": { "type": "number", "description": "Current available points" }, "lifetimeEarned": { "type": "number", "description": "Total points earned (never decreases)" }, "lifetimeRedeemed": { "type": "number", "description": "Total points redeemed" }, "lifetimeExpired": { "type": "number", "description": "Total points expired" }, "currentTierId": { "type": "number", "nullable": true, "description": "Current tier ID" }, "tierAchievedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When current tier was achieved" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Remove tier override from member", "tags": [ "Loyalty Programs" ], "description": "Remove a manual/campaign tier override from a loyalty program member, reverting to automatic point-calculated tier.\n\n**Permissions:** ⚪ `loyalty.tier.assign`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "userId", "required": true, "description": "User ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Account ID" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "userId": { "type": "number", "description": "User ID" }, "currentBalance": { "type": "number", "description": "Current available points" }, "lifetimeEarned": { "type": "number", "description": "Total points earned (never decreases)" }, "lifetimeRedeemed": { "type": "number", "description": "Total points redeemed" }, "lifetimeExpired": { "type": "number", "description": "Total points expired" }, "currentTierId": { "type": "number", "nullable": true, "description": "Current tier ID" }, "tierAchievedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When current tier was achieved" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/{programId}/members/{userId}/wallet-pass": { "get": { "summary": "Generate wallet pass", "tags": [ "Loyalty Programs" ], "description": "Generate Apple or Google Wallet pass for loyalty member", "parameters": [ { "schema": { "type": "string", "enum": [ "apple", "google" ] }, "in": "query", "name": "platform", "required": false, "description": "apple (default) returns a .pkpass binary; google returns JSON { saveUrl }" }, { "schema": { "type": "string" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" }, { "schema": { "type": "string" }, "in": "path", "name": "userId", "required": true, "description": "User ID" } ], "responses": { "200": { "description": "Apple Wallet Pass file (.pkpass)", "content": { "application/vnd.apple.pkpass": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/{programId}/redeem/{rewardId}": { "post": { "summary": "Redeem a reward", "tags": [ "Loyalty Programs" ], "description": "Redeem a reward for a user, deducting points and generating a voucher code\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "number", "description": "User ID redeeming the reward" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "rewardId", "required": true, "description": "Reward catalog item ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "pointsAccountId": { "type": "number" }, "rewardId": { "type": "number" }, "pointsSpent": { "type": "number" }, "generatedDiscountId": { "type": "number", "nullable": true, "description": "Cloned discount with unique code" }, "generatedCode": { "type": "string", "nullable": true, "description": "Generated voucher code" }, "status": { "type": "string", "enum": [ "active", "used", "expired", "revoked" ] }, "usedAt": { "type": "string", "format": "date-time", "nullable": true }, "usedInPurchaseId": { "type": "number", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/earning-rules": { "post": { "summary": "Create earning rule", "tags": [ "Loyalty Programs" ], "description": "Create a new earning rule for a loyalty program\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "loyaltyProgramId", "name", "ruleType" ], "properties": { "loyaltyProgramId": { "type": "number" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "ruleType": { "type": "string", "enum": [ "SPEND_BASED", "ITEM_BASED", "VISIT_BASED", "ACTION_BASED" ] }, "isActive": { "type": "boolean", "default": true }, "minTierId": { "type": "number" }, "pointsPerCurrencyUnit": { "type": "number" }, "minPurchaseAmount": { "type": "number" }, "itemId": { "type": "number" }, "pointsMode": { "type": "string", "enum": [ "FIXED", "MULTIPLIER" ] }, "pointsPerItem": { "type": "number" }, "pointsMultiplier": { "type": "number" }, "pointsPerVisit": { "type": "number" }, "minPurchaseForVisit": { "type": "number" }, "actionType": { "type": "string" }, "pointsPerAction": { "type": "number" }, "maxActionsPerPeriod": { "type": "number" }, "actionPeriod": { "type": "string" }, "validFrom": { "type": "string", "nullable": true, "format": "date" }, "validUntil": { "type": "string", "nullable": true, "format": "date" }, "priority": { "type": "number", "default": 0 } } } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "loyaltyProgramId": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "ruleType": { "type": "string", "enum": [ "SPEND_BASED", "ITEM_BASED", "VISIT_BASED", "ACTION_BASED" ] }, "isActive": { "type": "boolean" }, "minTierId": { "type": "number", "nullable": true, "description": "Minimum tier required to earn from this rule" }, "pointsPerCurrencyUnit": { "type": "number", "nullable": true, "description": "Points per SEK/currency unit" }, "minPurchaseAmount": { "type": "number", "nullable": true, "description": "Minimum purchase to qualify" }, "itemId": { "type": "number", "nullable": true, "description": "Specific item that earns points" }, "pointsMode": { "type": "string", "enum": [ "FIXED", "MULTIPLIER" ], "nullable": true, "description": "FIXED or MULTIPLIER" }, "pointsPerItem": { "type": "number", "nullable": true, "description": "Fixed points per item" }, "pointsMultiplier": { "type": "number", "nullable": true, "description": "Multiplier (e.g., 2.0 = 2x base points)" }, "pointsPerVisit": { "type": "number", "nullable": true, "description": "Points per visit/check-in" }, "minPurchaseForVisit": { "type": "number", "nullable": true, "description": "Minimum purchase to qualify as visit" }, "actionType": { "type": "string", "nullable": true, "description": "signup, referral, social_share, review, etc." }, "pointsPerAction": { "type": "number", "nullable": true, "description": "Points per action" }, "maxActionsPerPeriod": { "type": "number", "nullable": true, "description": "Max times action can earn points" }, "actionPeriod": { "type": "string", "nullable": true, "description": "daily, weekly, monthly, lifetime" }, "validFrom": { "type": "string", "format": "date", "nullable": true }, "validUntil": { "type": "string", "format": "date", "nullable": true }, "priority": { "type": "number", "description": "Rule evaluation priority (higher = evaluated first)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/earning-rules/{id}": { "put": { "summary": "Update earning rule", "tags": [ "Loyalty Programs" ], "description": "Update an existing earning rule\n\n**Permissions:** 🟠 `loyalty.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "ruleType": { "type": "string", "enum": [ "SPEND_BASED", "ITEM_BASED", "VISIT_BASED", "ACTION_BASED" ] }, "isActive": { "type": "boolean" }, "minTierId": { "type": "number" }, "pointsPerCurrencyUnit": { "type": "number" }, "minPurchaseAmount": { "type": "number" }, "itemId": { "type": "number" }, "pointsMode": { "type": "string", "enum": [ "FIXED", "MULTIPLIER" ] }, "pointsPerItem": { "type": "number" }, "pointsMultiplier": { "type": "number" }, "pointsPerVisit": { "type": "number" }, "minPurchaseForVisit": { "type": "number" }, "actionType": { "type": "string" }, "pointsPerAction": { "type": "number" }, "maxActionsPerPeriod": { "type": "number" }, "actionPeriod": { "type": "string" }, "validFrom": { "type": "string", "nullable": true, "format": "date" }, "validUntil": { "type": "string", "nullable": true, "format": "date" }, "priority": { "type": "number" } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Earning rule ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "loyaltyProgramId": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "ruleType": { "type": "string", "enum": [ "SPEND_BASED", "ITEM_BASED", "VISIT_BASED", "ACTION_BASED" ] }, "isActive": { "type": "boolean" }, "minTierId": { "type": "number", "nullable": true, "description": "Minimum tier required to earn from this rule" }, "pointsPerCurrencyUnit": { "type": "number", "nullable": true, "description": "Points per SEK/currency unit" }, "minPurchaseAmount": { "type": "number", "nullable": true, "description": "Minimum purchase to qualify" }, "itemId": { "type": "number", "nullable": true, "description": "Specific item that earns points" }, "pointsMode": { "type": "string", "enum": [ "FIXED", "MULTIPLIER" ], "nullable": true, "description": "FIXED or MULTIPLIER" }, "pointsPerItem": { "type": "number", "nullable": true, "description": "Fixed points per item" }, "pointsMultiplier": { "type": "number", "nullable": true, "description": "Multiplier (e.g., 2.0 = 2x base points)" }, "pointsPerVisit": { "type": "number", "nullable": true, "description": "Points per visit/check-in" }, "minPurchaseForVisit": { "type": "number", "nullable": true, "description": "Minimum purchase to qualify as visit" }, "actionType": { "type": "string", "nullable": true, "description": "signup, referral, social_share, review, etc." }, "pointsPerAction": { "type": "number", "nullable": true, "description": "Points per action" }, "maxActionsPerPeriod": { "type": "number", "nullable": true, "description": "Max times action can earn points" }, "actionPeriod": { "type": "string", "nullable": true, "description": "daily, weekly, monthly, lifetime" }, "validFrom": { "type": "string", "format": "date", "nullable": true }, "validUntil": { "type": "string", "format": "date", "nullable": true }, "priority": { "type": "number", "description": "Rule evaluation priority (higher = evaluated first)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete earning rule", "tags": [ "Loyalty Programs" ], "description": "Delete an earning rule\n\n**Permissions:** 🔴 `loyalty.delete`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Earning rule ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "id": { "type": "number" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/enroll": { "post": { "summary": "Enroll user in program", "tags": [ "Loyalty Programs" ], "description": "Enroll a single user in a loyalty program. Supports userId, email, or phone identification.\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "programId" ], "properties": { "programId": { "type": "number", "description": "Loyalty program ID" }, "userId": { "type": "number", "description": "User ID (priority 1)" }, "email": { "type": "string", "format": "email", "description": "Email address (priority 2)" }, "phone": { "type": "string", "description": "Phone number (priority 3)" }, "tierId": { "type": "number", "description": "Optional tier ID to assign at enrollment (requires loyalty.tier.assign permission)" } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Account ID" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "userId": { "type": "number", "description": "User ID" }, "currentBalance": { "type": "number", "description": "Current available points" }, "lifetimeEarned": { "type": "number", "description": "Total points earned (never decreases)" }, "lifetimeRedeemed": { "type": "number", "description": "Total points redeemed" }, "lifetimeExpired": { "type": "number", "description": "Total points expired" }, "currentTierId": { "type": "number", "nullable": true, "description": "Current tier ID" }, "tierAchievedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When current tier was achieved" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/enroll/bulk": { "post": { "summary": "Bulk enroll users", "tags": [ "Loyalty Programs" ], "description": "Enroll multiple users in a loyalty program at once. When tierId is provided, the tier is applied to ALL users (new and already-enrolled).\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "programId", "userIds" ], "properties": { "programId": { "type": "number", "description": "Loyalty program ID" }, "userIds": { "type": "array", "items": { "type": "number" }, "description": "Array of user IDs to enroll" }, "tierId": { "type": "number", "description": "Optional tier ID to assign to ALL users (requires loyalty.tier.assign permission)" } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "enrolled": { "type": "number", "description": "Number of users enrolled" }, "alreadyEnrolled": { "type": "number", "description": "Number already enrolled (skipped)" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Account ID" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "userId": { "type": "number", "description": "User ID" }, "currentBalance": { "type": "number", "description": "Current available points" }, "lifetimeEarned": { "type": "number", "description": "Total points earned (never decreases)" }, "lifetimeRedeemed": { "type": "number", "description": "Total points redeemed" }, "lifetimeExpired": { "type": "number", "description": "Total points expired" }, "currentTierId": { "type": "number", "nullable": true, "description": "Current tier ID" }, "tierAchievedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When current tier was achieved" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/points/award": { "post": { "summary": "Award points", "tags": [ "Loyalty Programs" ], "description": "Award points to a user manually. Used for promotional points, customer service adjustments, or manual corrections.\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "number", "description": "User ID to award points to" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "points": { "type": "number", "minimum": 1, "description": "Number of points to award (must be positive)" }, "description": { "type": "string", "description": "Reason for awarding points" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata for tracking" } }, "required": [ "userId", "loyaltyProgramId", "points", "description" ] } } }, "required": true }, "responses": { "201": { "description": "Points awarded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "transactionId": { "type": "string", "description": "Transaction ID (UUID)" }, "points": { "type": "number", "description": "Points involved in the transaction" }, "description": { "type": "string", "description": "Transaction description" }, "createdAt": { "type": "string", "format": "date-time", "description": "Transaction creation timestamp" } }, "required": [ "transactionId", "points", "description", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/points/claim-purchase": { "post": { "summary": "Claim loyalty points for a past purchase", "tags": [ "Loyalty Programs" ], "description": "Retroactively claim loyalty points for a purchase made within the last 30 days.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "number", "description": "User ID of the loyalty program member" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "purchaseIntentId": { "type": "string", "description": "Purchase intent ID from the completed purchase" } }, "required": [ "userId", "loyaltyProgramId", "purchaseIntentId" ] } } }, "required": true }, "responses": { "200": { "description": "Points claimed or no points to award", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "string", "nullable": true }, "pointsAwarded": { "type": "number" }, "message": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/points/deduct": { "post": { "summary": "Deduct points", "tags": [ "Loyalty Programs" ], "description": "Deduct points from a user. Used for manual adjustments or corrections. For redemptions, use the redemption endpoints.\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "number", "description": "User ID to deduct points from" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "points": { "type": "number", "minimum": 1, "description": "Number of points to deduct (must be positive)" }, "description": { "type": "string", "description": "Reason for deducting points" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata for tracking" } }, "required": [ "userId", "loyaltyProgramId", "points", "description" ] } } }, "required": true }, "responses": { "200": { "description": "Points deducted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "transactionId": { "type": "string", "description": "Transaction ID (UUID)" }, "points": { "type": "number", "description": "Points involved in the transaction" }, "description": { "type": "string", "description": "Transaction description" }, "createdAt": { "type": "string", "format": "date-time", "description": "Transaction creation timestamp" } }, "required": [ "transactionId", "points", "description", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/points/estimate": { "post": { "summary": "Estimate points for purchase", "tags": [ "Loyalty Programs" ], "description": "Estimate points that would be earned from a purchase. Used to display earning preview at checkout before the purchase is committed. No authentication required - called from storefront.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "purchaseAmountCents": { "type": "number", "minimum": 0, "description": "Estimated purchase amount in cents" }, "itemIds": { "type": "array", "items": { "type": "number" }, "description": "Array of item IDs in the cart (for item-based earning rules)" }, "userTierId": { "type": "number", "nullable": true, "description": "User tier ID for tier-specific multipliers (optional)" } }, "required": [ "loyaltyProgramId", "purchaseAmountCents" ] } } }, "required": true }, "responses": { "200": { "description": "Points estimate calculated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "estimatedPoints": { "type": "number", "description": "Total estimated points (with multipliers)" }, "basePoints": { "type": "number", "description": "Base points before multipliers" }, "appliedRules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Rule ID" }, "name": { "type": "string", "description": "Rule name" }, "ruleType": { "type": "string", "enum": [ "SPEND_BASED", "ITEM_BASED" ], "description": "Type of earning rule" }, "pointsAwarded": { "type": "number", "description": "Points from this rule" } } }, "description": "List of earning rules applied" }, "activeMultiplier": { "type": "number", "nullable": true, "description": "Active multiplier (if any double points promotion is active)" } }, "required": [ "estimatedPoints", "basePoints", "appliedRules" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/points/process-purchase": { "post": { "summary": "Process purchase points", "tags": [ "Loyalty Programs" ], "description": "Process points from a purchase. Called after a purchase is completed to calculate and award earned points based on earning rules.\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "number", "description": "User ID who made the purchase" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "purchaseId": { "type": "number", "description": "Purchase ID to process" }, "purchaseAmountCents": { "type": "number", "description": "Total purchase amount in cents" }, "itemIds": { "type": "array", "items": { "type": "number" }, "description": "Array of item IDs in the purchase (for item-based earning rules)" } }, "required": [ "userId", "loyaltyProgramId", "purchaseId", "purchaseAmountCents" ] } } }, "required": true }, "responses": { "200": { "description": "Purchase processed (no points earned)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "pointsAwarded": { "type": "number", "description": "Points awarded (0 if none earned)" }, "message": { "type": "string", "description": "Explanation message" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "201": { "description": "Points awarded for purchase", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "transactionId": { "type": "string", "description": "Transaction ID (UUID)" }, "pointsAwarded": { "type": "number", "description": "Points awarded" }, "createdAt": { "type": "string", "format": "date-time", "description": "Transaction timestamp" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/programs": { "get": { "summary": "List loyalty programs", "tags": [ "Loyalty Programs" ], "description": "List loyalty programs with optional filtering\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isActive", "required": false, "description": "Filter by active status" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 1000, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "programs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Loyalty program ID" }, "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Program name" }, "description": { "type": "string", "nullable": true, "description": "Program description" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, USD)" }, "isActive": { "type": "boolean", "description": "Whether program is active" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Program start date" }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "Program end date" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "programs", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create loyalty program", "tags": [ "Loyalty Programs" ], "description": "Create a new loyalty program\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Program name" }, "description": { "type": "string", "nullable": true, "description": "Program description" }, "currency": { "type": "string", "default": "SEK", "description": "Currency code" }, "isActive": { "type": "boolean", "default": true, "description": "Whether program is active" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Program start date" }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "Program end date" }, "loyaltyCardImage": { "type": "string", "nullable": true, "description": "Loyalty card image URL" }, "loyaltyColor": { "type": "string", "nullable": true, "description": "Loyalty card color (hex)" } }, "required": [ "name" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Loyalty program ID" }, "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Program name" }, "description": { "type": "string", "nullable": true, "description": "Program description" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, USD)" }, "isActive": { "type": "boolean", "description": "Whether program is active" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Program start date" }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "Program end date" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/programs/{id}": { "get": { "summary": "Get loyalty program", "tags": [ "Loyalty Programs" ], "description": "Get a single loyalty program by ID\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Loyalty program ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Loyalty program ID" }, "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Program name" }, "description": { "type": "string", "nullable": true, "description": "Program description" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, USD)" }, "isActive": { "type": "boolean", "description": "Whether program is active" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Program start date" }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "Program end date" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update loyalty program", "tags": [ "Loyalty Programs" ], "description": "Update an existing loyalty program\n\n**Permissions:** 🟠 `loyalty.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Program name" }, "description": { "type": "string", "nullable": true, "description": "Program description" }, "currency": { "type": "string", "description": "Currency code" }, "isActive": { "type": "boolean", "description": "Whether program is active" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Program start date" }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "Program end date" }, "loyaltyCardImage": { "type": "string", "nullable": true, "description": "Loyalty card image URL" }, "loyaltyColor": { "type": "string", "nullable": true, "description": "Loyalty card color (hex)" } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Loyalty program ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Loyalty program ID" }, "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Program name" }, "description": { "type": "string", "nullable": true, "description": "Program description" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, USD)" }, "isActive": { "type": "boolean", "description": "Whether program is active" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Program start date" }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "Program end date" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete loyalty program", "tags": [ "Loyalty Programs" ], "description": "Soft-delete a loyalty program (sets deleted_at, preserves data). Requires loyalty.admin permission.\n\n**Permissions:** ⚪ `loyalty.admin`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Loyalty program ID" } ], "responses": { "204": { "description": "Program soft-deleted successfully" }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/programs/{programId}/accounts": { "get": { "summary": "List points accounts", "tags": [ "Loyalty Programs" ], "description": "Get all points accounts for a loyalty program with pagination\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 1000, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Account ID" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "userId": { "type": "number", "description": "User ID" }, "currentBalance": { "type": "number", "description": "Current available points" }, "lifetimeEarned": { "type": "number", "description": "Total points earned (never decreases)" }, "lifetimeRedeemed": { "type": "number", "description": "Total points redeemed" }, "lifetimeExpired": { "type": "number", "description": "Total points expired" }, "currentTierId": { "type": "number", "nullable": true, "description": "Current tier ID" }, "tierAchievedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When current tier was achieved" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "accounts" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/programs/{programId}/earning-rules": { "get": { "summary": "List earning rules", "tags": [ "Loyalty Programs" ], "description": "Get all earning rules for a loyalty program\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "earningRules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "loyaltyProgramId": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "ruleType": { "type": "string", "enum": [ "SPEND_BASED", "ITEM_BASED", "VISIT_BASED", "ACTION_BASED" ] }, "isActive": { "type": "boolean" }, "minTierId": { "type": "number", "nullable": true, "description": "Minimum tier required to earn from this rule" }, "pointsPerCurrencyUnit": { "type": "number", "nullable": true, "description": "Points per SEK/currency unit" }, "minPurchaseAmount": { "type": "number", "nullable": true, "description": "Minimum purchase to qualify" }, "itemId": { "type": "number", "nullable": true, "description": "Specific item that earns points" }, "pointsMode": { "type": "string", "enum": [ "FIXED", "MULTIPLIER" ], "nullable": true, "description": "FIXED or MULTIPLIER" }, "pointsPerItem": { "type": "number", "nullable": true, "description": "Fixed points per item" }, "pointsMultiplier": { "type": "number", "nullable": true, "description": "Multiplier (e.g., 2.0 = 2x base points)" }, "pointsPerVisit": { "type": "number", "nullable": true, "description": "Points per visit/check-in" }, "minPurchaseForVisit": { "type": "number", "nullable": true, "description": "Minimum purchase to qualify as visit" }, "actionType": { "type": "string", "nullable": true, "description": "signup, referral, social_share, review, etc." }, "pointsPerAction": { "type": "number", "nullable": true, "description": "Points per action" }, "maxActionsPerPeriod": { "type": "number", "nullable": true, "description": "Max times action can earn points" }, "actionPeriod": { "type": "string", "nullable": true, "description": "daily, weekly, monthly, lifetime" }, "validFrom": { "type": "string", "format": "date", "nullable": true }, "validUntil": { "type": "string", "format": "date", "nullable": true }, "priority": { "type": "number", "description": "Rule evaluation priority (higher = evaluated first)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/programs/{programId}/rewards": { "get": { "summary": "List rewards catalog", "tags": [ "Loyalty Programs" ], "description": "Get the rewards catalog for a loyalty program\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "query", "name": "userId", "required": false, "description": "Optional user ID. When provided, rewards the user has already hit their max_redemptions_per_user for are filtered out." }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "rewards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "loyaltyProgramId": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "pointsCost": { "type": "number", "description": "Points required to redeem" }, "minTierId": { "type": "number", "nullable": true, "description": "Minimum tier required to redeem" }, "discountId": { "type": "number", "description": "Reference to voucher in discounts table" }, "isActive": { "type": "boolean" }, "stockQuantity": { "type": "number", "nullable": true, "description": "Available quantity (NULL = unlimited)" }, "maxRedemptionsPerUser": { "type": "number", "nullable": true, "description": "Max redemptions per user" }, "availableFrom": { "type": "string", "format": "date", "nullable": true }, "availableUntil": { "type": "string", "format": "date", "nullable": true }, "displayOrder": { "type": "number" }, "expirationDays": { "type": "number", "nullable": true, "description": "Days until redemption expires" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "displayTitle": { "type": "string", "nullable": true, "description": "Customer-facing title from linked voucher" }, "displayDescription": { "type": "string", "nullable": true, "description": "Customer-facing description from linked voucher" } }, "additionalProperties": false } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/programs/{programId}/tiers": { "get": { "summary": "List loyalty tiers", "tags": [ "Loyalty Programs" ], "description": "Get all tiers for a loyalty program\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Tier ID" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "name": { "type": "string", "description": "Tier name (e.g., Bronze, Silver, Gold)" }, "description": { "type": "string", "nullable": true, "description": "Tier description" }, "pointsThreshold": { "type": "number", "description": "Points required for this tier" }, "thresholdType": { "type": "string", "enum": [ "LIFETIME_POINTS", "ROLLING_PERIOD", "MANUAL" ], "description": "LIFETIME_POINTS = based on lifetime_earned, ROLLING_PERIOD = based on points in last X months, MANUAL = manually assigned" }, "rollingPeriodMonths": { "type": "number", "nullable": true, "description": "Required when thresholdType = ROLLING_PERIOD. Points earned in last X months." }, "order": { "type": "number", "description": "Display order (lower = higher tier)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "required": [ "tiers" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/programs/{programId}/users/{userId}/account": { "get": { "summary": "Get user points account", "tags": [ "Loyalty Programs" ], "description": "Get or create a points account for a specific user in a loyalty program\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "userId", "required": true, "description": "User ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Account ID" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "userId": { "type": "number", "description": "User ID" }, "currentBalance": { "type": "number", "description": "Current available points" }, "lifetimeEarned": { "type": "number", "description": "Total points earned (never decreases)" }, "lifetimeRedeemed": { "type": "number", "description": "Total points redeemed" }, "lifetimeExpired": { "type": "number", "description": "Total points expired" }, "currentTierId": { "type": "number", "nullable": true, "description": "Current tier ID" }, "tierAchievedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When current tier was achieved" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/programs/{programId}/users/{userId}/redemptions": { "get": { "summary": "Get user redemptions", "tags": [ "Loyalty Programs" ], "description": "Get reward redemption history for a user in a loyalty program\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" }, { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "userId", "required": true, "description": "User ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "redemptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "pointsAccountId": { "type": "number" }, "rewardId": { "type": "number" }, "pointsSpent": { "type": "number" }, "generatedDiscountId": { "type": "number", "nullable": true, "description": "Cloned discount with unique code" }, "generatedCode": { "type": "string", "nullable": true, "description": "Generated voucher code" }, "status": { "type": "string", "enum": [ "active", "used", "expired", "revoked" ] }, "usedAt": { "type": "string", "format": "date-time", "nullable": true }, "usedInPurchaseId": { "type": "number", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/rewards": { "post": { "summary": "Create reward", "tags": [ "Loyalty Programs" ], "description": "Create a new reward in the catalog\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "loyaltyProgramId", "name", "pointsCost", "discountId" ], "properties": { "loyaltyProgramId": { "type": "number" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "pointsCost": { "type": "number", "minimum": 1 }, "minTierId": { "type": "number" }, "discountId": { "type": "number" }, "isActive": { "type": "boolean", "default": true }, "stockQuantity": { "type": "number" }, "maxRedemptionsPerUser": { "type": "number" }, "availableFrom": { "type": "string", "format": "date", "nullable": true }, "availableUntil": { "type": "string", "format": "date", "nullable": true }, "displayOrder": { "type": "number", "default": 0 }, "expirationDays": { "type": "number" } } } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "loyaltyProgramId": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "pointsCost": { "type": "number", "description": "Points required to redeem" }, "minTierId": { "type": "number", "nullable": true, "description": "Minimum tier required to redeem" }, "discountId": { "type": "number", "description": "Reference to voucher in discounts table" }, "isActive": { "type": "boolean" }, "stockQuantity": { "type": "number", "nullable": true, "description": "Available quantity (NULL = unlimited)" }, "maxRedemptionsPerUser": { "type": "number", "nullable": true, "description": "Max redemptions per user" }, "availableFrom": { "type": "string", "format": "date", "nullable": true }, "availableUntil": { "type": "string", "format": "date", "nullable": true }, "displayOrder": { "type": "number" }, "expirationDays": { "type": "number", "nullable": true, "description": "Days until redemption expires" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "displayTitle": { "type": "string", "nullable": true, "description": "Customer-facing title from linked voucher" }, "displayDescription": { "type": "string", "nullable": true, "description": "Customer-facing description from linked voucher" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/rewards/{id}": { "put": { "summary": "Update reward", "tags": [ "Loyalty Programs" ], "description": "Update an existing reward in the catalog\n\n**Permissions:** 🟠 `loyalty.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "pointsCost": { "type": "number", "minimum": 1 }, "minTierId": { "type": "number" }, "discountId": { "type": "number" }, "isActive": { "type": "boolean" }, "stockQuantity": { "type": "number" }, "maxRedemptionsPerUser": { "type": "number" }, "availableFrom": { "type": "string", "format": "date", "nullable": true }, "availableUntil": { "type": "string", "format": "date", "nullable": true }, "displayOrder": { "type": "number" }, "expirationDays": { "type": "number" } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Reward ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "loyaltyProgramId": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "pointsCost": { "type": "number", "description": "Points required to redeem" }, "minTierId": { "type": "number", "nullable": true, "description": "Minimum tier required to redeem" }, "discountId": { "type": "number", "description": "Reference to voucher in discounts table" }, "isActive": { "type": "boolean" }, "stockQuantity": { "type": "number", "nullable": true, "description": "Available quantity (NULL = unlimited)" }, "maxRedemptionsPerUser": { "type": "number", "nullable": true, "description": "Max redemptions per user" }, "availableFrom": { "type": "string", "format": "date", "nullable": true }, "availableUntil": { "type": "string", "format": "date", "nullable": true }, "displayOrder": { "type": "number" }, "expirationDays": { "type": "number", "nullable": true, "description": "Days until redemption expires" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "displayTitle": { "type": "string", "nullable": true, "description": "Customer-facing title from linked voucher" }, "displayDescription": { "type": "string", "nullable": true, "description": "Customer-facing description from linked voucher" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete reward", "tags": [ "Loyalty Programs" ], "description": "Delete a reward from the catalog\n\n**Permissions:** 🔴 `loyalty.delete`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Reward ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "id": { "type": "number" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/tiers": { "post": { "summary": "Create loyalty tier", "tags": [ "Loyalty Programs" ], "description": "Create a new tier for a loyalty program\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "loyaltyProgramId": { "type": "number" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "nullable": true }, "pointsThreshold": { "type": "number", "minimum": 0 }, "thresholdType": { "type": "string", "enum": [ "LIFETIME_POINTS", "ROLLING_PERIOD", "MANUAL" ], "default": "LIFETIME_POINTS" }, "rollingPeriodMonths": { "type": "number", "nullable": true, "minimum": 1, "description": "Required when thresholdType = ROLLING_PERIOD" }, "tierCardImageUrl": { "type": "string", "nullable": true, "description": "Tier card image URL" }, "tierColor": { "type": "string", "nullable": true, "description": "Tier card color (hex)" }, "order": { "type": "number", "default": 0 } }, "required": [ "loyaltyProgramId", "name" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Tier ID" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "name": { "type": "string", "description": "Tier name (e.g., Bronze, Silver, Gold)" }, "description": { "type": "string", "nullable": true, "description": "Tier description" }, "pointsThreshold": { "type": "number", "description": "Points required for this tier" }, "thresholdType": { "type": "string", "enum": [ "LIFETIME_POINTS", "ROLLING_PERIOD", "MANUAL" ], "description": "LIFETIME_POINTS = based on lifetime_earned, ROLLING_PERIOD = based on points in last X months, MANUAL = manually assigned" }, "rollingPeriodMonths": { "type": "number", "nullable": true, "description": "Required when thresholdType = ROLLING_PERIOD. Points earned in last X months." }, "order": { "type": "number", "description": "Display order (lower = higher tier)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/tiers/{id}": { "put": { "summary": "Update loyalty tier", "tags": [ "Loyalty Programs" ], "description": "Update an existing loyalty tier\n\n**Permissions:** 🟠 `loyalty.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Tier name" }, "description": { "type": "string", "nullable": true, "description": "Tier description" }, "pointsThreshold": { "type": "number", "minimum": 0, "description": "Points required for this tier" }, "thresholdType": { "type": "string", "enum": [ "LIFETIME_POINTS", "ROLLING_PERIOD", "MANUAL" ] }, "rollingPeriodMonths": { "type": "number", "nullable": true, "minimum": 1 }, "tierCardImageUrl": { "type": "string", "nullable": true, "description": "Tier card image URL" }, "tierColor": { "type": "string", "nullable": true, "description": "Tier card color (hex)" }, "order": { "type": "number" } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Tier ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Tier ID" }, "loyaltyProgramId": { "type": "number", "description": "Loyalty program ID" }, "name": { "type": "string", "description": "Tier name (e.g., Bronze, Silver, Gold)" }, "description": { "type": "string", "nullable": true, "description": "Tier description" }, "pointsThreshold": { "type": "number", "description": "Points required for this tier" }, "thresholdType": { "type": "string", "enum": [ "LIFETIME_POINTS", "ROLLING_PERIOD", "MANUAL" ], "description": "LIFETIME_POINTS = based on lifetime_earned, ROLLING_PERIOD = based on points in last X months, MANUAL = manually assigned" }, "rollingPeriodMonths": { "type": "number", "nullable": true, "description": "Required when thresholdType = ROLLING_PERIOD. Points earned in last X months." }, "order": { "type": "number", "description": "Display order (lower = higher tier)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete loyalty tier", "tags": [ "Loyalty Programs" ], "description": "Delete a loyalty tier\n\n**Permissions:** 🔴 `loyalty.delete`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Tier ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "id": { "type": "number" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/transactions": { "get": { "summary": "List points transactions", "tags": [ "Loyalty Programs" ], "description": "Get points transactions with optional filters (account, user, type, date range)\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "pointsAccountId", "required": false, "description": "Filter by points account ID" }, { "schema": { "type": "number" }, "in": "query", "name": "programId", "required": false, "description": "Filter by loyalty program ID" }, { "schema": { "type": "number" }, "in": "query", "name": "userId", "required": false, "description": "Filter by user ID" }, { "schema": { "type": "string" }, "in": "query", "name": "transactionType", "required": false, "description": "Filter by transaction type" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": false, "description": "Filter by start date" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": false, "description": "Filter by end date" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "number", "minimum": 1, "maximum": 1000, "default": 50 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Transaction UUID" }, "pointsAccountId": { "type": "number", "description": "Points account ID" }, "transactionType": { "type": "string", "enum": [ "EARNED_PURCHASE", "EARNED_ITEM", "EARNED_VISIT", "EARNED_ACTION", "REDEEMED", "EXPIRED", "ADJUSTED", "REVOKED" ], "description": "Transaction type" }, "points": { "type": "number", "description": "Points amount (positive for earned, negative for redeemed/expired)" }, "balanceAfter": { "type": "number", "description": "Balance after this transaction" }, "purchaseId": { "type": "number", "nullable": true, "description": "Related purchase ID" }, "earningRuleId": { "type": "number", "nullable": true, "description": "Earning rule that triggered this transaction" }, "rewardRedemptionId": { "type": "number", "nullable": true, "description": "Reward redemption that caused this transaction" }, "description": { "type": "string", "nullable": true, "description": "Human-readable description" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Additional context" }, "expiresAt": { "type": "string", "format": "date", "nullable": true, "description": "When these points expire" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "user": { "type": "object", "nullable": true, "properties": { "email": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "description": "Member who made this transaction" } }, "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/users/{userId}/programs": { "get": { "summary": "Get user enrolled programs", "tags": [ "Loyalty Programs" ], "description": "Get all loyalty programs a user is enrolled in with account details and current tier. Users can only view their own enrollments. API keys with 'loyalty.read' permission can view any user's enrollments.\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "userId", "required": true, "description": "User ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "programs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Loyalty program ID" }, "locationId": { "type": "number", "description": "Location ID" }, "locationSlug": { "type": "string", "nullable": true, "description": "Active location slug for storefront URL" }, "name": { "type": "string", "description": "Program name" }, "description": { "type": "string", "nullable": true, "description": "Program description" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, USD)" }, "isActive": { "type": "boolean", "description": "Whether program is active" }, "startDate": { "type": "string", "format": "date", "nullable": true, "description": "Program start date" }, "endDate": { "type": "string", "format": "date", "nullable": true, "description": "Program end date" }, "loyaltyCardImage": { "type": "string", "nullable": true, "description": "Loyalty card image URL" }, "loyaltyColor": { "type": "string", "nullable": true, "description": "Loyalty card color (hex)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Program creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Program last update timestamp" }, "enrollment": { "type": "object", "properties": { "accountId": { "type": "number", "description": "Points account ID" }, "cardId": { "type": "string", "description": "Loyalty card identifier" }, "currentBalance": { "type": "number", "description": "Current points balance" }, "lifetimeEarned": { "type": "number", "description": "Total points earned all-time" }, "lifetimeRedeemed": { "type": "number", "description": "Total points redeemed all-time" }, "lifetimeExpired": { "type": "number", "description": "Total points expired all-time" }, "enrolledAt": { "type": "string", "format": "date-time", "description": "Enrollment timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Account last update timestamp" } }, "required": [ "accountId", "cardId", "currentBalance", "lifetimeEarned", "lifetimeRedeemed", "lifetimeExpired", "enrolledAt", "updatedAt" ] }, "currentTier": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "number", "description": "Tier ID" }, "name": { "type": "string", "description": "Tier name" }, "description": { "type": "string", "nullable": true, "description": "Tier description" }, "pointsThreshold": { "type": "number", "description": "Points required for this tier" }, "thresholdType": { "type": "string", "description": "LIFETIME_POINTS or ROLLING_PERIOD" }, "benefits": { "description": "Tier benefits (JSON)" }, "tierCardImageUrl": { "type": "string", "nullable": true, "description": "Tier card image URL" }, "tierColor": { "type": "string", "nullable": true, "description": "Tier color" } }, "required": [ "id", "name", "pointsThreshold", "thresholdType" ], "additionalProperties": false }, { "type": "null" } ], "description": "Current tier information, or null if no tier" } }, "required": [ "id", "locationId", "name", "currency", "isActive", "createdAt", "updatedAt", "enrollment", "currentTier" ], "additionalProperties": false }, "description": "List of loyalty programs the user is enrolled in" } }, "required": [ "programs" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/validate": { "post": { "summary": "Validate loyalty members", "tags": [ "Loyalty Programs" ], "description": "Validate loyalty membership for multiple users by userId, email, phone, or cardId", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "description": "Array of user identifiers to validate", "items": { "type": "object", "properties": { "userId": { "type": "number", "description": "User ID (optional if email, phone, or cardId provided)" }, "email": { "type": "string", "description": "User email (optional if userId, phone, or cardId provided)" }, "phone": { "type": "string", "description": "User phone (optional if userId, email, or cardId provided)" }, "cardId": { "type": "string", "description": "Loyalty card ID (optional if userId, email, or phone provided)" } }, "minProperties": 1 } } }, "required": [ "users" ] } } }, "required": true }, "responses": { "200": { "description": "Loyalty validation results", "content": { "application/json": { "schema": { "description": "Loyalty validation results", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "hasLoyaltyProgram": { "type": "boolean", "description": "Whether this location has an active loyalty program" }, "programId": { "type": "number", "nullable": true, "description": "Loyalty program ID (null if no program)" }, "programName": { "type": "string", "nullable": true, "description": "Loyalty program name (null if no program)" }, "users": { "type": "array", "description": "Enrollment status for each requested user", "items": { "type": "object", "properties": { "userId": { "type": "number", "nullable": true, "description": "User ID if found" }, "email": { "type": "string", "nullable": true, "description": "User email if found" }, "phone": { "type": "string", "nullable": true, "description": "User phone if found" }, "cardId": { "type": "string", "nullable": true, "description": "Loyalty card ID if found" }, "isEnrolled": { "type": "boolean", "description": "Whether user is enrolled in loyalty program" }, "currentBalance": { "type": "number", "nullable": true, "description": "Current loyalty points balance (null if not enrolled)" }, "lifetimeEarned": { "type": "number", "nullable": true, "description": "Total points earned all time (null if not enrolled)" }, "lifetimeRedeemed": { "type": "number", "nullable": true, "description": "Total points redeemed all time (null if not enrolled)" }, "currentTier": { "type": "string", "nullable": true, "description": "Current tier name (null if not enrolled or no tiers)" }, "accountId": { "type": "number", "nullable": true, "description": "Loyalty account ID (null if not enrolled)" } }, "required": [ "userId", "email", "phone", "cardId", "isEnrolled", "currentBalance", "lifetimeEarned", "lifetimeRedeemed", "currentTier", "accountId" ] } } }, "required": [ "hasLoyaltyProgram", "programId", "programName", "users" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/enrollment-token-preview": { "get": { "summary": "Preview enrollment token", "tags": [ "Loyalty Self-Service" ], "description": "Verify an enrollment JWT token and return card details without consuming (marking as used) the token.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "token", "required": true, "description": "JWT enrollment token from QR code" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success", "error" ] }, "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "purchaseIntentId": { "type": "string", "nullable": true }, "locationId": { "type": "number", "nullable": true }, "last4": { "type": "string", "nullable": true }, "brand": { "type": "string", "nullable": true }, "pointsAlreadyAwarded": { "type": "boolean", "nullable": true } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/self-service-enroll": { "post": { "summary": "Self-service card enrollment", "tags": [ "Loyalty Self-Service" ], "description": "Link a payment card to a user account via self-service. Supports two modes: (1) QR flow with enrollment token, (2) confirmation page flow with purchaseIntentId + userId.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "userId" ], "properties": { "token": { "type": "string", "description": "JWT enrollment token (QR flow). Mutually exclusive with purchaseIntentId." }, "purchaseIntentId": { "type": "string", "description": "Purchase intent ID (confirmation page flow). Mutually exclusive with token." }, "userId": { "type": "number", "description": "Guest user ID (passed in body — API key auth has no guest identity)" } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "cardLinked": { "type": "boolean" }, "enrolled": { "type": "boolean" }, "pointsAwarded": { "type": "number" }, "pointsAlreadyAwarded": { "type": "boolean", "nullable": true }, "newBalance": { "type": "number", "nullable": true } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/{programId}/wallet-pass/broadcast-marketing": { "post": { "tags": [ "Loyalty Wallet Passes" ], "description": "Send a marketing push (headline + body) to every saved Apple/Google Wallet card for this loyalty program", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "headline", "body" ], "properties": { "headline": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "minLength": 1, "maxLength": 280 }, "url": { "type": "string", "format": "uri" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/loyalty/{programId}/wallet-pass/broadcast-push": { "post": { "tags": [ "Loyalty Wallet Passes" ], "description": "Broadcast wallet pass push notification to all registered devices for a loyalty program", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "programId", "required": true, "description": "Loyalty program ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "notified": { "type": "number" }, "serialNumbers": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "/api/v1/menu-layouts": { "get": { "summary": "List menu layouts", "tags": [ "Menu Layouts" ], "description": "List menu layouts with optional filtering by location, schedule, and channels\n\n**Permissions:** 🔵 `menu_layouts.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" }, { "schema": { "type": "string" }, "in": "query", "name": "availableOnly", "required": false, "description": "Filter by schedule availability (ISO timestamp or \"true\")" }, { "schema": { "type": "string" }, "in": "query", "name": "channels", "required": false, "description": "Filter by channels (comma-separated channel types)" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "templatesOnly", "required": false, "description": "Filter to only return templates" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "excludeTemplates", "required": false, "description": "Exclude templates from results" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "resolveReferences", "required": false, "description": "Resolve linked template references in the context" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "excludeUnmapped", "required": false, "description": "Drop product nodes whose item lacks a POS integration_resource_mappings row. Used by storefront to hide items that would silently fail at the POS. No-op when the location has no active POS integration." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "layouts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique menu layout ID" }, "locationId": { "type": "number", "description": "Location ID this layout belongs to" }, "context": { "type": "object", "description": "JSON object storing the POS screen configuration and layout structure", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last update timestamp" }, "sortOrder": { "type": "number", "nullable": true, "description": "Display order for menu layouts (lower values first)" }, "isTemplate": { "type": "boolean", "nullable": true, "description": "Whether this layout is a reusable template" }, "templateName": { "type": "string", "nullable": true, "description": "Display name for the template" }, "usageCount": { "type": "number", "description": "Number of menus using this template (only for templates)" }, "scheduleRules": { "type": "array", "description": "Schedule rules for time-based availability", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Rule ID" }, "dayOfWeek": { "type": "number", "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "Start time (HH:MM)" }, "endTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "End time (HH:MM)" }, "active": { "type": "boolean", "description": "Whether item is available during this time" } } } }, "channelAvailability": { "type": "object", "description": "Channel availability flags", "properties": { "online": { "type": "boolean", "description": "Available on online channel" }, "qr": { "type": "boolean", "description": "Available on QR channel" }, "kiosk": { "type": "boolean", "description": "Available on kiosk channel" }, "pos": { "type": "boolean", "description": "Available on POS channel" } } } }, "required": [ "id", "locationId", "context", "createdAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "layouts", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create menu layout", "tags": [ "Menu Layouts" ], "description": "Create a new menu layout\n\n**Permissions:** 🟢 `menu_layouts.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID" }, "context": { "type": "object", "description": "JSON object with POS screen layout configuration", "additionalProperties": true }, "isTemplate": { "type": "boolean", "description": "Whether this layout should be a reusable template" }, "templateName": { "type": "string", "description": "Display name for the template (required if isTemplate is true)" } }, "required": [ "locationId", "context" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique menu layout ID" }, "locationId": { "type": "number", "description": "Location ID this layout belongs to" }, "context": { "type": "object", "description": "JSON object storing the POS screen configuration and layout structure", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last update timestamp" }, "sortOrder": { "type": "number", "nullable": true, "description": "Display order for menu layouts (lower values first)" }, "isTemplate": { "type": "boolean", "nullable": true, "description": "Whether this layout is a reusable template" }, "templateName": { "type": "string", "nullable": true, "description": "Display name for the template" }, "usageCount": { "type": "number", "description": "Number of menus using this template (only for templates)" }, "scheduleRules": { "type": "array", "description": "Schedule rules for time-based availability", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Rule ID" }, "dayOfWeek": { "type": "number", "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "Start time (HH:MM)" }, "endTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "End time (HH:MM)" }, "active": { "type": "boolean", "description": "Whether item is available during this time" } } } }, "channelAvailability": { "type": "object", "description": "Channel availability flags", "properties": { "online": { "type": "boolean", "description": "Available on online channel" }, "qr": { "type": "boolean", "description": "Available on QR channel" }, "kiosk": { "type": "boolean", "description": "Available on kiosk channel" }, "pos": { "type": "boolean", "description": "Available on POS channel" } } } }, "required": [ "id", "locationId", "context", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/menu-layouts/{id}": { "get": { "summary": "Get menu layout", "tags": [ "Menu Layouts" ], "description": "Get a single menu layout by ID. Use resolveReferences=true to expand linked template references.\n\n**Permissions:** 🔵 `menu_layouts.read`", "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "resolveReferences", "required": false, "description": "Resolve linked template references in the context" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "excludeUnmapped", "required": false, "description": "Drop product nodes whose item lacks a POS integration_resource_mappings row. No-op when the location has no active POS integration." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Menu layout ID (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique menu layout ID" }, "locationId": { "type": "number", "description": "Location ID this layout belongs to" }, "context": { "type": "object", "description": "JSON object storing the POS screen configuration and layout structure", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last update timestamp" }, "sortOrder": { "type": "number", "nullable": true, "description": "Display order for menu layouts (lower values first)" }, "isTemplate": { "type": "boolean", "nullable": true, "description": "Whether this layout is a reusable template" }, "templateName": { "type": "string", "nullable": true, "description": "Display name for the template" }, "usageCount": { "type": "number", "description": "Number of menus using this template (only for templates)" }, "scheduleRules": { "type": "array", "description": "Schedule rules for time-based availability", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Rule ID" }, "dayOfWeek": { "type": "number", "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "Start time (HH:MM)" }, "endTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "End time (HH:MM)" }, "active": { "type": "boolean", "description": "Whether item is available during this time" } } } }, "channelAvailability": { "type": "object", "description": "Channel availability flags", "properties": { "online": { "type": "boolean", "description": "Available on online channel" }, "qr": { "type": "boolean", "description": "Available on QR channel" }, "kiosk": { "type": "boolean", "description": "Available on kiosk channel" }, "pos": { "type": "boolean", "description": "Available on POS channel" } } } }, "required": [ "id", "locationId", "context", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update menu layout", "tags": [ "Menu Layouts" ], "description": "Update an existing menu layout\n\n**Permissions:** 🟠 `menu_layouts.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "object", "description": "Updated JSON object with POS screen layout configuration", "additionalProperties": true }, "isTemplate": { "type": "boolean", "description": "Whether this layout should be a reusable template" }, "templateName": { "type": "string", "description": "Display name for the template" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Menu layout ID (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique menu layout ID" }, "locationId": { "type": "number", "description": "Location ID this layout belongs to" }, "context": { "type": "object", "description": "JSON object storing the POS screen configuration and layout structure", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last update timestamp" }, "sortOrder": { "type": "number", "nullable": true, "description": "Display order for menu layouts (lower values first)" }, "isTemplate": { "type": "boolean", "nullable": true, "description": "Whether this layout is a reusable template" }, "templateName": { "type": "string", "nullable": true, "description": "Display name for the template" }, "usageCount": { "type": "number", "description": "Number of menus using this template (only for templates)" }, "scheduleRules": { "type": "array", "description": "Schedule rules for time-based availability", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Rule ID" }, "dayOfWeek": { "type": "number", "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "Start time (HH:MM)" }, "endTime": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "End time (HH:MM)" }, "active": { "type": "boolean", "description": "Whether item is available during this time" } } } }, "channelAvailability": { "type": "object", "description": "Channel availability flags", "properties": { "online": { "type": "boolean", "description": "Available on online channel" }, "qr": { "type": "boolean", "description": "Available on QR channel" }, "kiosk": { "type": "boolean", "description": "Available on kiosk channel" }, "pos": { "type": "boolean", "description": "Available on POS channel" } } } }, "required": [ "id", "locationId", "context", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete menu layout", "tags": [ "Menu Layouts" ], "description": "Delete a menu layout. If the layout is a template that is being used, set force=true to delete anyway.\n\n**Permissions:** 🔴 `menu_layouts.delete`", "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "force", "required": false, "description": "Force delete a template even if it is being used in menus" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Menu layout ID (UUID)" } ], "responses": { "200": { "description": "Menu layout successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/menu-layouts/{id}/usage": { "get": { "summary": "Get template usage", "tags": [ "Menu Layouts" ], "description": "Get information about which menus are using a template\n\n**Permissions:** 🔵 `menu_layouts.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Menu layout ID (UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "templateId": { "type": "string", "description": "The template ID" }, "usageCount": { "type": "number", "description": "Number of menus using this template" }, "usedIn": { "type": "array", "items": { "type": "object", "properties": { "menuId": { "type": "string", "description": "Menu ID" }, "menuTitle": { "type": "string", "description": "Menu title" }, "linked": { "type": "boolean", "description": "Whether the reference is linked (auto-updates) or copied" } } }, "description": "List of menus using this template" } }, "required": [ "templateId", "usageCount", "usedIn" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/menu-layouts/reorder": { "post": { "summary": "Reorder menu layouts", "tags": [ "Menu Layouts" ], "description": "Reorder menu layouts by updating their sort order\n\n**Permissions:** 🟠 `menu_layouts.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "layoutIds": { "type": "array", "items": { "type": "string" }, "description": "Array of menu layout IDs in the desired display order" } }, "required": [ "layoutIds" ] } } }, "required": true }, "responses": { "200": { "description": "Menu layouts successfully reordered", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "layoutIds": { "type": "array", "items": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/notes": { "get": { "summary": "List notes for an entity", "tags": [ "Notes" ], "description": "List all notes attached to a specific entity (tab or user). Notes are returned in sort order (lowest sortOrder first).\n\n**Permissions:** 🔵 `notes.read`", "parameters": [ { "schema": { "type": "string", "enum": [ "tab", "user", "booking" ] }, "in": "query", "name": "entityType", "required": true, "description": "Type of entity to fetch notes for" }, { "schema": { "type": "string" }, "in": "query", "name": "entityId", "required": true, "description": "ID of the entity (tab UUID or user ID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "enum": [ "tab", "user", "booking" ], "description": "Type of entity this note is attached to" }, "entityId": { "type": "string", "description": "ID of the entity (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order for displaying notes (lower = first)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of the user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of the user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] } } }, "required": [ "notes" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create a note", "tags": [ "Notes" ], "description": "Create a new note attached to an entity (tab or user). The note will be associated with the current location and the authenticated user (if using JWT auth).\n\n**Permissions:** 🟢 `notes.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "tab", "user", "booking" ], "description": "Type of entity to attach the note to" }, "entityId": { "type": "string", "description": "ID of the entity (tab UUID or user ID)" }, "note": { "type": "string", "minLength": 1, "description": "Note content" } }, "required": [ "entityType", "entityId", "note" ], "additionalProperties": false } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "enum": [ "tab", "user", "booking" ], "description": "Type of entity this note is attached to" }, "entityId": { "type": "string", "description": "ID of the entity (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order for displaying notes (lower = first)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of the user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of the user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/notes/{uuid}": { "get": { "summary": "Get a note", "tags": [ "Notes" ], "description": "Get a single note by UUID\n\n**Permissions:** 🔵 `notes.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "uuid", "required": true, "description": "Note UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "enum": [ "tab", "user", "booking" ], "description": "Type of entity this note is attached to" }, "entityId": { "type": "string", "description": "ID of the entity (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order for displaying notes (lower = first)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of the user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of the user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "patch": { "summary": "Update a note", "tags": [ "Notes" ], "description": "Update an existing note. The updated_by fields will be set to the authenticated user.\n\n**Permissions:** 🟠 `notes.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1, "description": "Updated note content" } }, "required": [ "note" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "uuid", "required": true, "description": "Note UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "enum": [ "tab", "user", "booking" ], "description": "Type of entity this note is attached to" }, "entityId": { "type": "string", "description": "ID of the entity (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order for displaying notes (lower = first)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of the user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of the user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete a note", "tags": [ "Notes" ], "description": "Delete a note by UUID\n\n**Permissions:** 🔴 `notes.delete`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "uuid", "required": true, "description": "Note UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/notes/reorder": { "post": { "summary": "Reorder notes", "tags": [ "Notes" ], "description": "Reorder notes for an entity. Pass an array of note UUIDs in the desired order. Each note will have its sortOrder updated to match its position in the array.\n\n**Permissions:** 🟠 `notes.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "noteUuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Array of note UUIDs in the desired order" } }, "required": [ "noteUuids" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "enum": [ "tab", "user", "booking" ] }, "in": "query", "name": "entityType", "required": true, "description": "Type of entity to fetch notes for" }, { "schema": { "type": "string" }, "in": "query", "name": "entityId", "required": true, "description": "ID of the entity (tab UUID or user ID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "enum": [ "tab", "user", "booking" ], "description": "Type of entity this note is attached to" }, "entityId": { "type": "string", "description": "ID of the entity (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order for displaying notes (lower = first)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of the user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of the user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] } } }, "required": [ "notes" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/kitchen-dispatch-items/{id}": { "delete": { "summary": "Delete kitchen dispatch item", "tags": [ "Orders" ], "description": "Remove a single item from an order. Disallowed when the item is already paid or has a settlement in progress.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Kitchen dispatch item UUID" } ], "responses": { "200": { "description": "Successfully deleted item", "content": { "application/json": { "schema": { "description": "Successfully deleted item", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kitchenDispatchId": { "type": "string", "format": "uuid" }, "tabId": { "type": "string", "format": "uuid" }, "kitchenDispatchEmptied": { "type": "boolean" }, "deleted": { "type": "boolean" } }, "required": [ "id", "kitchenDispatchId", "tabId", "kitchenDispatchEmptied", "deleted" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/kitchen-dispatch-items/{id}/split": { "get": { "summary": "Get split order items", "tags": [ "Orders" ], "description": "Get all items that were split from an order item for bill splitting", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Kitchen dispatch item UUID (the split_of_kitchen_dispatch_item reference)" } ], "responses": { "200": { "description": "Successfully retrieved split items", "content": { "application/json": { "schema": { "description": "Successfully retrieved split items", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Split item UUID" }, "basePrice": { "type": "number", "description": "Base price in cents" }, "modificationPrice": { "type": "number", "description": "Total modification price in cents" }, "price": { "type": "number", "description": "Final price in cents" }, "title": { "type": "string", "description": "Item title" }, "currencyCode": { "type": "string", "description": "Currency code (e.g., SEK)" }, "modifications": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "variantId": { "type": "number" }, "variantGroupId": { "type": "number" }, "type": { "type": "string", "enum": [ "variant", "extra" ] }, "amount": { "type": "number", "description": "Price in cents" } } } } }, "required": [ "uuid", "basePrice", "modificationPrice", "price", "title", "currencyCode", "modifications" ] } }, "originalItemId": { "type": "string", "format": "uuid", "description": "The original item UUID that was split" } }, "required": [ "items", "originalItemId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Split order item", "tags": [ "Orders" ], "description": "Split an order item into multiple parts for bill splitting with equal pricing", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "numberOfParts": { "type": "number", "minimum": 2, "maximum": 10, "description": "Number of parts to split the item into (2-10)" }, "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID that the item belongs to" } }, "required": [ "numberOfParts", "tabId" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Kitchen dispatch item UUID" } ], "responses": { "200": { "description": "Successfully split the item", "content": { "application/json": { "schema": { "description": "Successfully split the item", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "splitItemIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "UUIDs of the newly created split items" }, "originalItemId": { "type": "string", "format": "uuid", "description": "UUID of the original item (now deleted)" } }, "required": [ "splitItemIds", "originalItemId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/kitchen-dispatch-items/{id}/takeaway": { "patch": { "summary": "Toggle takeaway status", "tags": [ "Orders" ], "description": "Toggle takeaway status on a kitchen dispatch item", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "is_takeaway": { "type": "boolean", "description": "Whether the item is takeaway" } }, "required": [ "is_takeaway" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Kitchen dispatch item UUID" } ], "responses": { "200": { "description": "Successfully toggled takeaway status", "content": { "application/json": { "schema": { "description": "Successfully toggled takeaway status", "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "uuid": { "type": "string" }, "isTakeaway": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/kitchen-dispatch-items/{id}/void": { "post": { "summary": "Void a kitchen dispatch item", "tags": [ "Orders" ], "description": "Set item_state to \"aborted\" on a kitchen dispatch item. Requires orders.void permission. Rejects when the parent tab has any purchases. When reasonCode is \"other\", reasonNote is required.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reasonCode": { "type": "string", "enum": [ "staff_mistake", "customer_change", "wrong_make", "quality_issue", "out_of_stock", "allergy", "other" ], "description": "Reason code from the locked enum" }, "reasonNote": { "type": [ "string", "null" ], "maxLength": 500, "description": "Optional free-text note; REQUIRED when reasonCode is \"other\"" }, "quantityCents": { "type": [ "integer", "null" ], "minimum": 1, "description": "Optional partial-void quantity in basis-points (null = full quantity). Stored only in audit." }, "suppressKorrbong": { "type": "boolean", "description": "When true, suppress the order.reversed webhook so printer-service does not print a KORRBONG correction ticket. Used by cafe-mode void-and-replace flows." } }, "required": [ "reasonCode" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Kitchen dispatch item UUID" } ], "responses": { "200": { "description": "Successfully voided the item", "content": { "application/json": { "schema": { "description": "Successfully voided the item", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "kitchenDispatchItemId": { "type": "string", "format": "uuid" }, "previousItemState": { "type": [ "null", "string" ] }, "newItemState": { "type": "string", "enum": [ "aborted" ] }, "reasonCode": { "type": "string", "enum": [ "staff_mistake", "customer_change", "wrong_make", "quality_issue", "out_of_stock", "allergy", "other" ] }, "reasonNote": { "type": [ "null", "string" ] }, "dispatchAborted": { "type": "boolean" } }, "required": [ "kitchenDispatchItemId", "previousItemState", "newItemState", "reasonCode", "reasonNote", "dispatchAborted" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/kitchen-dispatch-items/void-batch": { "post": { "summary": "Void one or more kitchen dispatch items", "tags": [ "Orders" ], "description": "Set item_state to \"aborted\" on multiple kitchen dispatch items in one request. Items may span multiple parent dispatches; one `order.reversed` event is emitted per affected KD. Requires orders.void permission. Rejects when ANY affected tab has purchases. When reasonCode is \"other\", reasonNote is required.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reasonCode": { "type": "string", "enum": [ "staff_mistake", "customer_change", "wrong_make", "quality_issue", "out_of_stock", "allergy", "other" ], "description": "Reason code from the locked enum, applied to every item in the batch" }, "reasonNote": { "type": [ "string", "null" ], "maxLength": 500, "description": "Optional free-text note; REQUIRED when reasonCode is \"other\"" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Kitchen dispatch items to void", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "quantityCents": { "type": [ "integer", "null" ], "minimum": 1, "description": "Optional partial-void quantity (null = full)." } }, "required": [ "id" ], "additionalProperties": false } }, "suppressKorrbong": { "type": "boolean", "description": "When true, suppress the order.reversed webhook so printer-service does not print a KORRBONG per affected dispatch. Used by cafe-mode void-and-replace flows." } }, "required": [ "reasonCode", "items" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Successfully voided all items in the batch", "content": { "application/json": { "schema": { "description": "Successfully voided all items in the batch", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "reasonCode": { "type": "string", "enum": [ "staff_mistake", "customer_change", "wrong_make", "quality_issue", "out_of_stock", "allergy", "other" ] }, "reasonNote": { "type": [ "null", "string" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "kitchenDispatchItemId": { "type": "string", "format": "uuid" }, "kitchenDispatchId": { "type": "string", "format": "uuid" }, "previousItemState": { "type": [ "null", "string" ] }, "newItemState": { "type": "string", "enum": [ "aborted" ] }, "dispatchAborted": { "type": "boolean" } }, "required": [ "kitchenDispatchItemId", "kitchenDispatchId", "previousItemState", "newItemState", "dispatchAborted" ] } }, "affectedDispatchIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "reasonCode", "reasonNote", "results", "affectedDispatchIds" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders": { "get": { "summary": "List orders", "tags": [ "Orders" ], "description": "Retrieve a paginated list of orders with filtering capabilities.\n\n**Hybrid Dual-Fetch Architecture:**\n- PostgreSQL for recent orders (<30 minutes old) - ensures freshness\n- BigQuery for historical orders (>30 minutes old) - scalability\n- Automatic merge when date range spans both sources\n\n**KDS/Real-Time Mode:**\n- Use `forcePostgres=true` to always query PostgreSQL only\n- This ensures fresh state data for Kitchen Display Systems\n- Recommended for any real-time display needing immediate state updates\n\n**Default Behavior:**\n- Returns last 24 hours if no date filters specified\n- Sorted by created_at descending (newest first)\n- Items not included by default (use includeItems=true)\n\n**Performance Notes:**\n- BigQuery queries typically take 1-3 seconds\n- For real-time displays, use forcePostgres=true or /api/v1/orders/stream endpoint\n\n**Permissions:** 🔵 `orders.read`", "parameters": [ { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 1000, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page (max 1000)" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeItems", "required": false, "description": "Include order items in response. Items are returned FLAT with parentKitchenDispatchItemId for hierarchy building." }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeNotes", "required": false, "description": "Include tab notes attached to each order (notes are polymorphic, keyed by tab uuid). Used by the KDS." }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "forcePostgres", "required": false, "description": "Force PostgreSQL only (skip BigQuery). Use for KDS/real-time displays where state must be fresh." }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "excludeAbortedTabs", "required": false, "description": "Hide KDs whose parent tab was force-closed (aborted). Use for the active KDS so staff don't see orphan tickets they cannot advance. Leave off for order history and audit views." }, { "schema": { "type": "number" }, "in": "query", "name": "dailyOrderNumber", "required": false, "description": "Filter by daily order number" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "state", "required": false, "description": "Filter by state(s)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "tabType", "required": false, "description": "Filter by tab type(s)" }, { "schema": { "type": "string" }, "in": "query", "name": "tableId", "required": false, "description": "Filter by table/QR code ID" }, { "schema": { "type": "string" }, "in": "query", "name": "tabMemberEmail", "required": false, "description": "Filter by tab member email (partial match)" }, { "schema": { "type": "number" }, "in": "query", "name": "minPrice", "required": false, "description": "Minimum total price in cents" }, { "schema": { "type": "number" }, "in": "query", "name": "maxPrice", "required": false, "description": "Maximum total price in cents" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "source", "required": false, "description": "Filter by order source/channel (POS, ONLINE, QR, KIOSK)" }, { "schema": { "type": "number" }, "in": "query", "name": "itemId", "required": false, "description": "Filter orders containing a specific inventory item ID" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "printerGroupIds", "required": false, "description": "Filter by prep group (printer group) IDs" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Filter orders created after this date (default: 24 hours ago)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "Filter orders created before this date (default: now)" }, { "schema": { "type": "string", "enum": [ "created_at", "daily_ordinal_number", "updated_at" ], "default": "created_at" }, "in": "query", "name": "sort", "required": false, "description": "Field to sort by" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "order", "required": false, "description": "Sort order" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Unique order ID (kitchen_dispatch.uuid)" }, "locationId": { "type": "number", "description": "Location ID" }, "tabId": { "type": "string", "format": "uuid", "nullable": true, "description": "Associated tab ID" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number for the location" }, "state": { "type": "string", "enum": [ "not_sent", "pending", "accepted", "in_preparation", "ready_to_deliver", "delivered", "rejected", "rejected_and_acknowledged", "staged_awaiting_payment", "scheduled", "aborted" ], "description": "Current order state" }, "orderType": { "type": "string", "enum": [ "TAKEAWAY", "OTC", "QR", "TABLE" ], "nullable": true, "description": "Order type" }, "orderChannel": { "type": "string", "enum": [ "ONLINE", "QR", "KIOSK", "POS" ], "nullable": true, "description": "Order channel" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "tabType": { "type": "string", "nullable": true, "description": "Tab type (table, takeaway, etc.)" }, "storefrontQrCodeId": { "type": "string", "nullable": true, "description": "Table UUID (storefront QR code ID) - frontend maps to name" }, "tabMemberEmail": { "type": "string", "format": "email", "nullable": true, "description": "Tab member email" }, "tabMemberName": { "type": "string", "nullable": true, "description": "Tab member name" }, "memberCount": { "type": "number", "nullable": true, "description": "Guest count on the tab (party size)" }, "totalPrice": { "type": "number", "nullable": true, "description": "Total price in cents" }, "itemCount": { "type": "number", "nullable": true, "description": "Number of items in order" }, "message": { "type": "string", "nullable": true, "description": "Order message/notes" }, "source": { "type": "string", "nullable": true, "description": "Order source" }, "items": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true, "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Unique order item ID" }, "itemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "title": { "type": "string", "nullable": true, "description": "Item title" }, "titlePrep": { "type": "string", "nullable": true, "description": "Kitchen prep title for KDS display - use instead of title if set" }, "quantity": { "type": "number", "description": "Quantity (integer)" }, "quantityCents": { "type": "number", "description": "Quantity in cents (e.g., 200 = 2x)" }, "price": { "type": "number", "description": "Total price in cents" }, "basePrice": { "type": "number", "description": "Base price in cents before discounts" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "status": { "type": "string", "nullable": true, "description": "Item status" }, "comments": {}, "variants": { "type": "array", "nullable": true, "description": "Variant/modification data for this item", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Variant ID" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "nullable": true, "description": "Variant price in cents" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents" }, "priceCents": { "type": "number", "nullable": true, "description": "Price in cents" }, "modification_id": { "type": "number", "description": "Modification ID for completion tracking" }, "status": { "type": "string", "nullable": true, "description": "Modification status" } } } }, "tabMemberId": { "type": "string", "format": "uuid", "nullable": true, "description": "Tab member who owns this item" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "servingCenterId": { "type": "number", "nullable": true, "description": "Serving center ID for this item" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "Prep group (printer group) ID for this item" }, "tabMemberEmail": { "type": "string", "format": "email", "nullable": true, "description": "Tab member email" }, "tabMemberName": { "type": "string", "nullable": true, "description": "Tab member name" }, "parentKitchenDispatchItemId": { "type": "string", "format": "uuid", "nullable": true, "description": "Parent item UUID - if set, this is a child/modifier item. Use this to build hierarchy in frontend." }, "itemState": { "type": "string", "nullable": true, "description": "Item-level state (not_sent, pending, accepted, in_preparation, ready_to_deliver, delivered, rejected)" }, "salesItemType": { "type": "string", "nullable": true, "description": "How the line was sold: \"regular\" or \"surplus\". Drives the KDS surplus badge." }, "surplusEntryId": { "type": "number", "nullable": true, "description": "item_ministock.id this surplus line was sold against (null for regular lines)." }, "isTakeaway": { "type": "boolean", "description": "Whether this specific line item is takeaway (independent of the tab-level tabType). Drives the KDS bag indicator." } }, "required": [ "uuid", "quantity", "quantityCents", "price", "basePrice", "createdAt" ] }, "description": "Order items (only when includeItems=true)" }, "notes": { "type": "array", "nullable": true, "description": "Tab notes attached to this order (only when includeNotes=true)", "items": { "type": "object", "additionalProperties": true, "properties": { "uuid": { "type": "string" }, "entityType": { "type": "string" }, "entityId": { "type": "string" }, "note": { "type": "string" }, "locationId": { "type": "number" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "createdByName": { "type": "string", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "updatedByName": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "description": "Order state change history", "items": { "type": "object", "properties": { "event": { "type": "string", "description": "Event/state name" }, "created_at": { "type": "string", "format": "date-time", "description": "Event timestamp" } }, "required": [ "event", "created_at" ] } }, "desiredPickupTime": { "type": "string", "format": "date-time", "nullable": true, "description": "Desired pickup time for scheduled orders" }, "storeCommitmentTimeout": { "type": "string", "format": "date-time", "nullable": true, "description": "Store commitment timeout for acceptance" } }, "required": [ "uuid", "locationId", "state", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "items", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/{kitchenDispatchId}/cancel": { "post": { "summary": "Cancel order", "tags": [ "Orders" ], "description": "Cancel a kitchen dispatch (order) by setting its state to aborted. Only early-stage orders can be cancelled.\n\n**Permissions:** 🟠 `inventory.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional cancellation reason (for audit trail)" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "kitchenDispatchId", "required": true, "description": "Kitchen dispatch UUID to cancel" } ], "responses": { "200": { "description": "Order cancelled successfully", "content": { "application/json": { "schema": { "description": "Order cancelled successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "previousState": { "type": "string", "description": "State before cancellation" }, "newState": { "type": "string", "enum": [ "aborted" ], "description": "New state after cancellation" }, "cancelledAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of cancellation" }, "cancelledBy": { "type": "number", "description": "User ID who cancelled the order" }, "reason": { "type": "string", "nullable": true, "description": "Cancellation reason (if provided)" }, "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID that the order belongs to" } }, "required": [ "kitchenDispatchId", "previousState", "newState", "cancelledAt", "cancelledBy", "reason", "tabId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Invalid state - Order cannot be cancelled in current state", "content": { "application/json": { "schema": { "description": "Invalid state - Order cannot be cancelled in current state", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_STATE" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "currentState": { "type": "string" }, "cancellableStates": { "type": "array", "items": { "type": "string" } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_AUTH_CONTEXT", "INVALID_API_KEY" ] }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "403": { "description": "Forbidden - Insufficient permissions or scope violation", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions or scope violation", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_PERMISSIONS", "SCOPE_VIOLATION" ] }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "404": { "description": "Kitchen dispatch not found", "content": { "application/json": { "schema": { "description": "Kitchen dispatch not found", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RESOURCE_NOT_FOUND" ] }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR" ] }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } } } } }, "/api/v1/orders/{kitchenDispatchId}/sync": { "post": { "summary": "Sync (atomic void + insert) lines on a kitchen dispatch", "tags": [ "Orders" ], "description": "Atomically void a set of existing kitchen_dispatch_items AND insert a set of new ones in ONE transaction, ONE webhook fan-out.\n\nCafe-mode \"edit committed items\" primitive. The earlier two-call shape (POST /void-batch + POST /append-to-dispatch in parallel) is replaced — clients describe the diff, the server applies it atomically.\n\n**Maps cleanly to actions:**\n- `+` on a committed line → `{ voids: [], inserts: [oneItem] }`\n- `−` on a committed line → `{ voids: [kdiId], inserts: [] }`\n- Variant edit → `{ voids: [originalKdiId], inserts: [newSpec] }`\n\n**Guards:**\n- Dispatch must exist, belong to the supplied tab + location, and be in an appendable state (`pending`/`accepted`/`in_preparation`/`ready_to_deliver`).\n- Tab must not be closed/abandoned.\n- Voids: any tab purchase rejects with 422 `TAB_HAS_PAYMENTS`. Already-aborted items pass through (idempotent, `wasAlreadyAborted: true` in the response).\n- Voided items not on this dispatch reject with 404 `KITCHEN_DISPATCH_ITEM_NOT_FOUND`.\n- Inserts: items + variants validated identically to `/orders/create`.\n\n**Side effects (one fan-out):**\n- `order.reversed` webhook (printer KORRBONG) — skipped when `suppressKorrbong: true` (cafe mode).\n- `order.updated` webhook with `changes.syncedLines` (KDS / cross-device refetch).\n- `tab.updated` webhook with `changes.kitchenDispatchSynced` (cashier tab refetch).\n- `inventory.updated` per ministock change.\n- Per-item `kitchen_dispatch_item.voided` platform_event for the audit trail.\n\n**Permissions:** 🟢 `inventory.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "tabId", "locationId", "order_channel", "voids", "inserts" ], "properties": { "tabId": { "type": "string", "format": "uuid", "description": "UUID of the tab the dispatch belongs to (validated server-side)" }, "locationId": { "type": "number" }, "order_channel": { "type": "string", "enum": [ "ONLINE", "QR", "KIOSK", "POS" ] }, "voids": { "type": "array", "description": "KDI UUIDs to set to item_state=aborted. Already-aborted ids pass through.", "items": { "type": "string", "format": "uuid" } }, "inserts": { "type": "array", "description": "New items to insert into the dispatch (same shape as /orders/create items[]).", "items": { "type": "object", "required": [ "id", "quantity_cents", "variants", "comments" ], "properties": { "id": { "type": "number" }, "quantity_cents": { "type": "number", "minimum": 1 }, "price_cents": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "number" }, "quantity_cents": { "type": "number" }, "price_cents": { "type": "number", "nullable": true }, "comments": { "type": "array", "items": { "type": "string" } } } } }, "comments": { "type": "array", "items": { "type": "string" } }, "tab_member_id": { "type": "string", "format": "uuid", "nullable": true }, "coursing_order": { "type": "number", "nullable": true }, "upsell_source": { "type": "string", "enum": [ "ai", "manual" ], "nullable": true }, "upsell_session_id": { "type": "string", "format": "uuid", "nullable": true }, "upsell_recommendation_id": { "type": "string", "format": "uuid", "nullable": true } } } }, "suppressKorrbong": { "type": "boolean", "description": "When true, skip the order.reversed webhook so printer-functions does not print a KORRBONG. Cafe-mode locations pass this; merchant locations omit it." }, "voidReasonCode": { "type": "string", "enum": [ "staff_mistake", "customer_change", "wrong_make", "quality_issue", "out_of_stock", "allergy", "other" ], "description": "Reason for the voids. Defaults to \"customer_change\"." }, "voidReasonNote": { "type": [ "string", "null" ], "maxLength": 500, "description": "Required when voidReasonCode === \"other\"." } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "kitchenDispatchId", "required": true, "description": "UUID of the kitchen dispatch to sync" } ], "responses": { "200": { "description": "Lines synced successfully", "content": { "application/json": { "schema": { "description": "Lines synced successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "kitchenDispatchId": { "type": "string", "format": "uuid" }, "tabId": { "type": "string", "format": "uuid" }, "inheritedItemState": { "type": "string" }, "dispatchAborted": { "type": "boolean" }, "voided": { "type": "array", "items": { "type": "object", "properties": { "kitchenDispatchItemId": { "type": "string", "format": "uuid" }, "previousItemState": { "type": [ "null", "string" ] }, "newItemState": { "type": "string", "enum": [ "aborted" ] }, "wasAlreadyAborted": { "type": "boolean" } } } }, "inserted": { "type": "array", "items": { "type": "object", "properties": { "kitchen_dispatch_item_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "number" }, "quantity": { "type": "number" }, "quantity_cents": { "type": "number" }, "price_cents": { "type": "number" }, "status": { "type": "string", "nullable": true } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/{orderId}": { "get": { "summary": "Get order by ID", "tags": [ "Orders" ], "description": "Retrieve detailed information about a specific order including all items.\n\nItems are always included in the response for single order queries.\n\n**Permissions:** 🔵 `orders.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "orderId", "required": true, "description": "Order ID (kitchen_dispatch.uuid)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Unique order ID (kitchen_dispatch.uuid)" }, "locationId": { "type": "number", "description": "Location ID" }, "tabId": { "type": "string", "format": "uuid", "nullable": true, "description": "Associated tab ID" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number for the location" }, "state": { "type": "string", "enum": [ "not_sent", "pending", "accepted", "in_preparation", "ready_to_deliver", "delivered", "rejected", "rejected_and_acknowledged", "staged_awaiting_payment", "scheduled", "aborted" ], "description": "Current order state" }, "orderType": { "type": "string", "enum": [ "TAKEAWAY", "OTC", "QR", "TABLE" ], "nullable": true, "description": "Order type" }, "orderChannel": { "type": "string", "enum": [ "ONLINE", "QR", "KIOSK", "POS" ], "nullable": true, "description": "Order channel" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Completion timestamp" }, "tabType": { "type": "string", "nullable": true, "description": "Tab type (table, takeaway, etc.)" }, "storefrontQrCodeId": { "type": "string", "nullable": true, "description": "Table UUID (storefront QR code ID) - frontend maps to name" }, "tabMemberEmail": { "type": "string", "format": "email", "nullable": true, "description": "Tab member email" }, "tabMemberName": { "type": "string", "nullable": true, "description": "Tab member name" }, "memberCount": { "type": "number", "nullable": true, "description": "Guest count on the tab (party size)" }, "totalPrice": { "type": "number", "nullable": true, "description": "Total price in cents" }, "itemCount": { "type": "number", "nullable": true, "description": "Number of items in order" }, "message": { "type": "string", "nullable": true, "description": "Order message/notes" }, "source": { "type": "string", "nullable": true, "description": "Order source" }, "items": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true, "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Unique order item ID" }, "itemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "title": { "type": "string", "nullable": true, "description": "Item title" }, "titlePrep": { "type": "string", "nullable": true, "description": "Kitchen prep title for KDS display - use instead of title if set" }, "quantity": { "type": "number", "description": "Quantity (integer)" }, "quantityCents": { "type": "number", "description": "Quantity in cents (e.g., 200 = 2x)" }, "price": { "type": "number", "description": "Total price in cents" }, "basePrice": { "type": "number", "description": "Base price in cents before discounts" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "status": { "type": "string", "nullable": true, "description": "Item status" }, "comments": {}, "variants": { "type": "array", "nullable": true, "description": "Variant/modification data for this item", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Variant ID" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "nullable": true, "description": "Variant price in cents" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents" }, "priceCents": { "type": "number", "nullable": true, "description": "Price in cents" }, "modification_id": { "type": "number", "description": "Modification ID for completion tracking" }, "status": { "type": "string", "nullable": true, "description": "Modification status" } } } }, "tabMemberId": { "type": "string", "format": "uuid", "nullable": true, "description": "Tab member who owns this item" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "servingCenterId": { "type": "number", "nullable": true, "description": "Serving center ID for this item" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "Prep group (printer group) ID for this item" }, "tabMemberEmail": { "type": "string", "format": "email", "nullable": true, "description": "Tab member email" }, "tabMemberName": { "type": "string", "nullable": true, "description": "Tab member name" }, "parentKitchenDispatchItemId": { "type": "string", "format": "uuid", "nullable": true, "description": "Parent item UUID - if set, this is a child/modifier item. Use this to build hierarchy in frontend." }, "itemState": { "type": "string", "nullable": true, "description": "Item-level state (not_sent, pending, accepted, in_preparation, ready_to_deliver, delivered, rejected)" }, "salesItemType": { "type": "string", "nullable": true, "description": "How the line was sold: \"regular\" or \"surplus\". Drives the KDS surplus badge." }, "surplusEntryId": { "type": "number", "nullable": true, "description": "item_ministock.id this surplus line was sold against (null for regular lines)." }, "isTakeaway": { "type": "boolean", "description": "Whether this specific line item is takeaway (independent of the tab-level tabType). Drives the KDS bag indicator." } }, "required": [ "uuid", "quantity", "quantityCents", "price", "basePrice", "createdAt" ] }, "description": "Order items (only when includeItems=true)" }, "notes": { "type": "array", "nullable": true, "description": "Tab notes attached to this order (only when includeNotes=true)", "items": { "type": "object", "additionalProperties": true, "properties": { "uuid": { "type": "string" }, "entityType": { "type": "string" }, "entityId": { "type": "string" }, "note": { "type": "string" }, "locationId": { "type": "number" }, "sortOrder": { "type": "number" }, "createdByRetailerUserId": { "type": "number", "nullable": true }, "createdByName": { "type": "string", "nullable": true }, "updatedByRetailerUserId": { "type": "number", "nullable": true }, "updatedByName": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "events": { "type": "array", "description": "Order state change history", "items": { "type": "object", "properties": { "event": { "type": "string", "description": "Event/state name" }, "created_at": { "type": "string", "format": "date-time", "description": "Event timestamp" } }, "required": [ "event", "created_at" ] } }, "desiredPickupTime": { "type": "string", "format": "date-time", "nullable": true, "description": "Desired pickup time for scheduled orders" }, "storeCommitmentTimeout": { "type": "string", "format": "date-time", "nullable": true, "description": "Store commitment timeout for acceptance" } }, "required": [ "uuid", "locationId", "state", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/{orderId}/advance-items": { "post": { "summary": "Advance order item states", "tags": [ "Orders" ], "description": "Advance item-level states for a kitchen dispatch (order).\n\n**Item-Level State Tracking:**\n- Each item independently tracks its own state\n- The overall order state is automatically derived as the earliest non-not_sent item state\n- Forward-only: items can only advance forward, never backward\n\n**Filtering Options:**\n- No filter: advance ALL items in the order\n- printerGroupId: advance only items in a specific prep group\n- coursingOrder: advance only items in a specific course\n\n**Valid Target States:**\n- pending, accepted, in_preparation, ready_to_deliver, delivered, rejected\n\n**Webhook:**\n- Emits order.updated with targetItemState and optional printerGroupId\n\n**Permissions:** 🟠 `inventory.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "pending", "accepted", "in_preparation", "ready_to_deliver", "delivered", "rejected" ], "description": "Target state to advance items to" }, "printerGroupId": { "type": "string", "format": "uuid", "description": "Optional: advance only items in this prep group (printer group)" }, "coursingOrder": { "type": "integer", "description": "Optional: advance only items in this course" } }, "required": [ "state" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "orderId", "required": true, "description": "Order ID (kitchen_dispatch.uuid)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid", "description": "Order ID (kitchen_dispatch.uuid)" }, "targetState": { "type": "string", "description": "Target state items were advanced to" }, "itemsAdvanced": { "type": "number", "description": "Number of items that were advanced" }, "derivedOrderState": { "type": "string", "description": "Derived overall order state after advancement" }, "previousOrderState": { "type": "string", "description": "Order state before advancement" }, "heldItems": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Counts of items targeted by the filter that were skipped because they are in a held state (not_sent, staged_awaiting_payment, waiting_for_merge). These items must exit their held state via the dedicated flow (coursing fire, payment confirmation, merge resolution) — bulk advance is intentionally a no-op for them." } }, "required": [ "orderId", "targetState", "itemsAdvanced", "derivedOrderState", "previousOrderState" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/{orderId}/edit-items": { "patch": { "summary": "Edit items on a staged order", "tags": [ "Orders" ], "description": "Edit item quantities on a kitchen dispatch in `staged_awaiting_payment` state.\n\nReplaces the cancel→re-commit pattern previously used for storefront-web pay_upfront tab editing.\n\n**Per item:**\n- `quantityCents > 0` — UPDATE quantity, adjust ministock delta\n- `quantityCents === 0` — DELETE the item (and its children), restore ministock\n\n**Guards:**\n- Dispatch must be in `staged_awaiting_payment` state\n- No item on the dispatch may have `paid_amount > 0`\n- Ministock checked for quantity increases\n- Location access validated\n\n**Side effects:**\n- Tab total recalculated\n- Emits `order.updated` webhook\n\n**Permissions:** 🟠 `inventory.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "description": "Items to edit. Set quantityCents to 0 to remove an item.", "items": { "type": "object", "properties": { "kitchenDispatchItemId": { "type": "string", "format": "uuid", "description": "UUID of the kitchen_dispatch_item to update" }, "quantityCents": { "type": "number", "minimum": 0, "description": "New quantity in cents (e.g. 300 = 3x). 0 removes the item." } }, "required": [ "kitchenDispatchItemId", "quantityCents" ] } } }, "required": [ "items" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "orderId", "required": true, "description": "Kitchen dispatch UUID to edit" } ], "responses": { "200": { "description": "Items edited successfully", "content": { "application/json": { "schema": { "description": "Items edited successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "updated": { "type": "number", "description": "Number of items updated" }, "removed": { "type": "number", "description": "Number of items removed" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/{orderId}/items/{itemId}/status": { "post": { "summary": "Update item status", "tags": [ "Orders" ], "description": "Update the status of a kitchen dispatch item or modification. Requires staff authentication (JWT). User ID for audit trail is extracted from the auth token.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "oneOf": [ { "type": "string", "enum": [ "COMPLETED", "UNAVAILABLE" ] }, { "type": "null" } ], "description": "Item status: COMPLETED, UNAVAILABLE, or null (reset)" }, "modificationId": { "type": "number", "description": "If provided, update this modification (variant) instead of the item" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "orderId", "required": true, "description": "Kitchen dispatch (order) UUID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "itemId", "required": true, "description": "Kitchen dispatch item UUID" } ], "responses": { "200": { "description": "Status updated successfully", "content": { "application/json": { "schema": { "description": "Status updated successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "itemId": { "type": "string", "format": "uuid" }, "status": { "oneOf": [ { "type": "string", "enum": [ "COMPLETED", "UNAVAILABLE" ] }, { "type": "null" } ], "description": "Item status: COMPLETED, UNAVAILABLE, or null (reset)" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/{orderId}/items/{itemId}/status/logs": { "get": { "summary": "Get item status logs", "tags": [ "Orders" ], "description": "Get the status change history for a kitchen dispatch item", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "orderId", "required": true, "description": "Kitchen dispatch (order) UUID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "itemId", "required": true, "description": "Kitchen dispatch item UUID" } ], "responses": { "200": { "description": "Status logs retrieved successfully", "content": { "application/json": { "schema": { "description": "Status logs retrieved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Log entry ID" }, "itemId": { "type": "string", "description": "Item or modification ID" }, "status": { "oneOf": [ { "type": "string", "enum": [ "COMPLETED", "UNAVAILABLE" ] }, { "type": "null" } ], "description": "Item status: COMPLETED, UNAVAILABLE, or null (reset)" }, "isModification": { "type": "boolean", "description": "True if this was a modification update" }, "retailerUserId": { "type": "string", "nullable": true, "description": "User who made the change" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the status was changed" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/{orderId}/items/status": { "post": { "summary": "Batch update item statuses", "tags": [ "Orders" ], "description": "Batch update the status of multiple kitchen dispatch items and/or modifications. Requires staff authentication (JWT). User ID for audit trail is extracted from the auth token.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "updates" ], "properties": { "updates": { "type": "array", "minItems": 1, "description": "Array of status updates", "items": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "description": "Item UUID or modification ID (as string)" }, "status": { "oneOf": [ { "type": "string", "enum": [ "COMPLETED", "UNAVAILABLE" ] }, { "type": "null" } ], "description": "Item status: COMPLETED, UNAVAILABLE, or null (reset)" }, "isModification": { "type": "boolean", "description": "True if this is a modification (variant), not an item" } } } } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "orderId", "required": true, "description": "Kitchen dispatch (order) UUID" } ], "responses": { "200": { "description": "Batch update completed", "content": { "application/json": { "schema": { "description": "Batch update completed", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True if all updates succeeded" }, "updatedCount": { "type": "number", "description": "Number of successfully updated items" }, "failedItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Item or modification ID" }, "isModification": { "type": "boolean", "description": "True if this is a modification (variant)" }, "error": { "type": "string", "description": "Error message" } } }, "description": "Items that failed to update" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/{orderId}/serving-center-state": { "post": { "summary": "Update serving center state", "tags": [ "Orders" ], "description": "Update the state of a specific serving center for an order.\n\n**Serving Center State Management:**\n- Each serving center independently tracks its state for each order\n- The overall order state is derived as the earliest (most backward) state across all serving centers\n- When all serving centers advance, the overall order state advances too\n\n**Valid Serving Center States (forward-only):**\n- pending → accepted → in_preparation → ready_to_deliver → delivered\n- rejected (terminal)\n\n**Constraints:**\n- Cannot set serving center state earlier than the overall order state\n- Forward-only transitions (can't go backward)\n\n**Webhook:**\n- Emits order.updated with servingCenterId and servingCenterState\n- Used by common-functions to send serving center SMS notifications\n\n**Replaces:** GraphQL mutation `updateServingCenterKitchenDispatchState` from Karma-Merchant-API\n\n**Permissions:** 🟠 `inventory.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "servingCenterId": { "type": "number", "description": "The serving center ID to update state for" }, "state": { "type": "string", "enum": [ "pending", "accepted", "in_preparation", "ready_to_deliver", "delivered", "rejected" ], "description": "The new serving center state" } }, "required": [ "servingCenterId", "state" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "orderId", "required": true, "description": "Order ID (kitchen_dispatch.uuid)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid", "description": "Order ID (kitchen_dispatch.uuid)" }, "servingCenterId": { "type": "number", "description": "Serving center ID" }, "previousServingCenterState": { "type": "string", "nullable": true, "description": "Previous serving center state" }, "newServingCenterState": { "type": "string", "description": "New serving center state" }, "orderState": { "type": "string", "description": "Overall order state (may have advanced)" }, "orderStateChanged": { "type": "boolean", "description": "Whether the overall order state changed" }, "tabId": { "type": "string", "format": "uuid", "description": "Associated tab ID" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Update timestamp" }, "updatedBy": { "type": "number", "description": "User ID who made the update" } }, "required": [ "orderId", "servingCenterId", "newServingCenterState", "orderState", "orderStateChanged" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/{orderId}/state": { "post": { "summary": "Update order state", "tags": [ "Orders" ], "description": "Update the state of an order (kitchen dispatch).\n\n**Event Sourcing:**\n- Inserts an event into kitchen_dispatch_events table\n- PostgreSQL trigger automatically updates kitchen_dispatches.latest_state\n- Emits order.updated webhook for real-time UI updates\n\n**Valid State Transitions:**\n- `not_sent` → pending, delivered, aborted\n- `pending` → accepted, rejected, aborted\n- `scheduled` → accepted, pending, aborted\n- `accepted` → in_preparation, ready_to_deliver, aborted\n- `in_preparation` → ready_to_deliver\n- `ready_to_deliver` → delivered\n- `rejected` → rejected_and_acknowledged\n- `aborted` → rejected_and_acknowledged (KDS bump on voided dispatch)\n- `staged_awaiting_payment` → pending, aborted\n\n**Terminal States (no transitions):**\n- delivered, rejected_and_acknowledged\n\n**Idempotency:**\n- Calling with current state returns 200 success (no-op)\n- Safe for retries in distributed systems\n\n**Permissions:** 🟠 `orders.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "not_sent", "pending", "accepted", "in_preparation", "ready_to_deliver", "delivered", "rejected", "rejected_and_acknowledged", "staged_awaiting_payment", "scheduled", "aborted" ], "description": "The new state to transition to" } }, "required": [ "state" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "orderId", "required": true, "description": "Order ID (kitchen_dispatch.uuid)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid", "description": "Order ID (kitchen_dispatch.uuid)" }, "previousState": { "type": "string", "description": "State before the update" }, "newState": { "type": "string", "description": "State after the update" }, "tabId": { "type": "string", "format": "uuid", "description": "Associated tab ID" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Update timestamp" }, "updatedBy": { "type": "number", "description": "User ID who made the update" } }, "required": [ "orderId", "previousState", "newState", "tabId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/append-to-dispatch": { "post": { "summary": "Append items to an existing kitchen dispatch", "tags": [ "Orders" ], "description": "Append items to an EXISTING kitchen_dispatch so they show up on the same KDS card the barista is already on.\n\nUsed by the cafe-mode \"edit committed items\" flow — instead of a void creating a fresh ticket, the cashier voids the original line and appends the replacement against the same dispatch ID.\n\n**Guards:**\n- Dispatch must exist and belong to the supplied tab.\n- Dispatch state must be one of: `pending`, `accepted`, `in_preparation`, `ready_to_deliver`. Any other state (terminal, held, merged, staged) is rejected with 409 `DISPATCH_NOT_APPENDABLE`.\n- Tab must not be closed/abandoned.\n- Items + variants validated via the same path as `/orders/create`.\n\n**Side effects:**\n- New `kitchen_dispatch_items` inserted under the existing dispatch.\n- Ministock decremented for items that track it.\n- `order.items_added` webhook emitted (resource id = dispatch id).\n- `tab.updated` webhook emitted with `kitchenDispatchUpdated: { dispatchId, itemCount }`.\n\n**Permissions:** 🟢 `inventory.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "kitchenDispatchId", "tabId", "locationId", "order_channel", "items" ], "properties": { "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "UUID of the kitchen dispatch to append to" }, "tabId": { "type": "string", "format": "uuid", "description": "UUID of the tab the dispatch belongs to (validated server-side)" }, "locationId": { "type": "number", "description": "Location ID (validated against dispatch)" }, "order_channel": { "type": "string", "enum": [ "ONLINE", "QR", "KIOSK", "POS" ], "description": "Source channel (POS-only flows pass POS so price-override gating works)" }, "items": { "type": "array", "minItems": 1, "description": "Items to append (same shape as /orders/create items)", "items": { "type": "object", "required": [ "id", "quantity_cents", "variants", "comments" ], "properties": { "id": { "type": "number", "description": "Inventory item ID" }, "quantity_cents": { "type": "number", "minimum": 1, "description": "Quantity in cents (e.g., 250 = 2.5 items)" }, "price_cents": { "type": "number", "nullable": true, "description": "Price override in cents (POS only)" }, "variants": { "type": "array", "description": "Variant modifications (recursive)", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "number" }, "quantity_cents": { "type": "number", "default": 100 }, "price_cents": { "type": "number", "nullable": true }, "comments": { "type": "array", "items": { "type": "string" } } } } }, "comments": { "type": "array", "items": { "type": "string" } }, "tab_member_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional: who this item is for (defaults to the dispatch tab_member_id)" }, "coursing_order": { "type": "number", "nullable": true, "description": "Coursing level (kept on the appended row; not used to fire courses)" }, "upsell_source": { "type": "string", "enum": [ "ai", "manual" ], "nullable": true }, "upsell_session_id": { "type": "string", "format": "uuid", "nullable": true }, "upsell_recommendation_id": { "type": "string", "format": "uuid", "nullable": true } } } } } } } }, "required": true }, "responses": { "200": { "description": "Items appended successfully", "content": { "application/json": { "schema": { "description": "Items appended successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "kitchenDispatchId": { "type": "string", "format": "uuid" }, "tabId": { "type": "string", "format": "uuid" }, "dailyOrderNumber": { "type": "number", "nullable": true }, "inheritedItemState": { "type": "string", "description": "State the new items were stamped with (mirrors the dispatch latest_state)" }, "appendedItems": { "type": "array", "items": { "type": "object", "properties": { "kitchen_dispatch_item_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "number" }, "quantity": { "type": "number" }, "quantity_cents": { "type": "number" }, "price_cents": { "type": "number" }, "status": { "type": "string", "nullable": true } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/create": { "post": { "summary": "Create order", "tags": [ "Orders" ], "description": "Unified Order Creation API - handles all order creation from POS, Storefront, Kiosk, and QR code orders\n\n**Permissions:** 🟢 `inventory.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "locationId", "order_channel", "order_type", "order_destination", "items" ], "properties": { "locationId": { "type": "number", "description": "Location ID" }, "order_channel": { "type": "string", "enum": [ "ONLINE", "QR", "KIOSK", "POS" ], "description": "Source of the order" }, "order_type": { "type": "string", "enum": [ "TAKEAWAY", "OTC", "QR", "TABLE", "SURPLUS" ], "description": "Service model - TAKEAWAY (pickup, fresh prep), OTC (over the counter), QR (customer scanned QR code or POS table order), TABLE (waiter service), SURPLUS (pre-prepared discounted item, anytime pickup)." }, "order_destination": { "type": "string", "enum": [ "QR", "TAB", "KD", "NONE" ], "description": "Where the order should be routed" }, "order_destination_id": { "type": "string", "nullable": true, "format": "uuid", "description": "UUID of the destination (QR code, tab, or kitchen dispatch)" }, "tab_member": { "type": "object", "nullable": true, "description": "User identification for the order", "properties": { "id": { "type": "number", "description": "User ID (highest priority)" }, "email": { "type": "string", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "identifier": { "type": "string", "description": "Device identifier" } } }, "items": { "type": "array", "minItems": 1, "description": "Items to include in the order", "items": { "type": "object", "required": [ "id", "quantity_cents", "variants", "comments" ], "properties": { "id": { "type": "number", "description": "Inventory item ID" }, "quantity_cents": { "type": "number", "minimum": 1, "description": "Quantity in cents (e.g., 250 = 2.5 items)" }, "price_cents": { "type": "number", "nullable": true, "description": "Price override in cents (POS only)" }, "variants": { "type": "array", "description": "Variant modifications", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "number", "description": "Variant ID" }, "quantity_cents": { "type": "number", "description": "Quantity in cents (default: 100 = 1x)", "default": 100 }, "price_cents": { "type": "number", "nullable": true, "description": "Price override in cents (POS only)" }, "comments": { "type": "array", "items": { "type": "string" }, "description": "Variant-specific comments" } } } }, "comments": { "type": "array", "items": { "type": "string" }, "description": "Special instructions" }, "upsell_source": { "type": "string", "enum": [ "ai", "manual" ], "nullable": true, "description": "Source of upsell recommendation: \"ai\" for AI-powered recommendations, \"manual\" for merchant-configured upsells" }, "upsell_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Links to upsell session for funnel analytics tracking" }, "upsell_recommendation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the specific recommendation that generated this item (from upsell_recommendations cache)" }, "gift_card_context": { "type": "object", "nullable": true, "description": "Gift card context for send-as-gift functionality", "properties": { "send_as_gift": { "type": "boolean", "description": "Whether the gift card is being sent as a gift" }, "recipient_name": { "type": "string", "description": "Gift recipient name" }, "recipient_email": { "type": "string", "format": "email", "description": "Gift recipient email address" }, "personal_message": { "type": "string", "description": "Personal message for the gift card" }, "code": { "type": "string", "description": "Pre-assigned gift card code" }, "design_id": { "type": "string", "description": "UUID of the selected gift card design from gift_card_designs table" } } } } } }, "vouchers": { "type": "array", "items": { "type": "string" }, "description": "Voucher codes to apply" }, "desiredPickupTime": { "type": "number", "nullable": true, "description": "Unix timestamp for desired pickup time" }, "hold": { "type": "boolean", "description": "If true, order will be held (not_sent) and not sent to kitchen automatically" } } } } }, "required": true }, "responses": { "200": { "description": "Order created successfully", "content": { "application/json": { "schema": { "description": "Order created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "kitchenDispatchId": { "type": "string", "format": "uuid" }, "dailyOrderNumber": { "type": "number" }, "tabId": { "type": "string", "format": "uuid" }, "tabMemberId": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "type": "object", "properties": { "kitchen_dispatch_item_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "number" }, "quantity_cents": { "type": "number", "description": "Quantity in cents (100 = 1x)" }, "price_cents": { "type": "number", "description": "Total price for this item in cents" }, "variants": { "type": "array", "description": "Variants applied to this item", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Variant ID" }, "quantity_cents": { "type": "number", "description": "Variant quantity in cents" }, "price_cents": { "type": "number", "nullable": true, "description": "Price override in cents" } } } }, "status": { "type": "string", "nullable": true, "description": "Item status (null for new items)" } } } }, "totalAmount": { "type": "number" }, "discountAmount": { "type": "number" }, "finalAmount": { "type": "number" }, "appliedVouchers": { "type": "array", "items": { "type": "object", "properties": { "voucherCode": { "type": "string" }, "discountAmountCents": { "type": "number" }, "discountType": { "type": "string" } } } }, "invalidVouchers": { "type": "array", "items": { "type": "string" } }, "estimatedReadyTime": { "type": "number", "nullable": true }, "paymentRequired": { "type": "boolean", "description": "True for INSTANT flow — guest must pay before kitchen receives items" }, "orderFlow": { "type": "string", "description": "Order flow used by backend (INSTANT, OPEN_TAB, etc.)" }, "kitchenDispatchItemIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Dispatch item UUIDs for payment processing" }, "minCommittedCoursingOrder": { "type": "number", "nullable": true, "description": "Lowest coursing_order across all just-committed KDIs (includes variant children resolved from inventory). null when nothing was coursed." } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/orders/stream": { "get": { "summary": "Stream orders (SSE)", "tags": [ "Orders" ], "description": "Stream orders using Server-Sent Events for real-time displays.\n\n**Use Case:** Kitchen Display Systems (KDS) and real-time dashboards where latency matters.\n\n**How It Works:**\n1. PostgreSQL results are sent first (~100ms) - recent orders\n2. BigQuery results follow when ready (~1-3 seconds) - historical orders\n3. Completion event sent when all data is received\n\n**SSE Events:**\n- `postgres`: Orders from PostgreSQL (recent data)\n- `bigquery`: Orders from BigQuery (historical data)\n- `error`: Error from a specific source\n- `complete`: All data has been sent\n\n**Client Example:**\n```javascript\nconst eventSource = new EventSource('/api/v1/orders/stream?limit=1000')\n\neventSource.addEventListener('postgres', (e) => {\n const { orders } = JSON.parse(e.data)\n // Show recent orders immediately!\n setOrders(prev => mergeAndSort([...prev, ...orders]))\n})\n\neventSource.addEventListener('bigquery', (e) => {\n const { orders } = JSON.parse(e.data)\n // Fill in historical orders\n setOrders(prev => mergeAndSort([...prev, ...orders]))\n})\n\neventSource.addEventListener('complete', () => {\n eventSource.close()\n})\n```\n\n**Headers Required:**\n- `Accept: text/event-stream`\n- `X-Location-Id: {locationId}`\n\n**Permissions:** 🔵 `orders.read`", "parameters": [ { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 1000, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Items per page (max 1000)" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeItems", "required": false, "description": "Include order items in response. Items are returned FLAT with parentKitchenDispatchItemId for hierarchy building." }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeNotes", "required": false, "description": "Include tab notes attached to each order (notes are polymorphic, keyed by tab uuid). Used by the KDS." }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "forcePostgres", "required": false, "description": "Force PostgreSQL only (skip BigQuery). Use for KDS/real-time displays where state must be fresh." }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "excludeAbortedTabs", "required": false, "description": "Hide KDs whose parent tab was force-closed (aborted). Use for the active KDS so staff don't see orphan tickets they cannot advance. Leave off for order history and audit views." }, { "schema": { "type": "number" }, "in": "query", "name": "dailyOrderNumber", "required": false, "description": "Filter by daily order number" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "state", "required": false, "description": "Filter by state(s)" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "tabType", "required": false, "description": "Filter by tab type(s)" }, { "schema": { "type": "string" }, "in": "query", "name": "tableId", "required": false, "description": "Filter by table/QR code ID" }, { "schema": { "type": "string" }, "in": "query", "name": "tabMemberEmail", "required": false, "description": "Filter by tab member email (partial match)" }, { "schema": { "type": "number" }, "in": "query", "name": "minPrice", "required": false, "description": "Minimum total price in cents" }, { "schema": { "type": "number" }, "in": "query", "name": "maxPrice", "required": false, "description": "Maximum total price in cents" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "source", "required": false, "description": "Filter by order source/channel (POS, ONLINE, QR, KIOSK)" }, { "schema": { "type": "number" }, "in": "query", "name": "itemId", "required": false, "description": "Filter orders containing a specific inventory item ID" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "printerGroupIds", "required": false, "description": "Filter by prep group (printer group) IDs" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Filter orders created after this date (default: 24 hours ago)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "Filter orders created before this date (default: now)" }, { "schema": { "type": "string", "enum": [ "created_at", "daily_ordinal_number", "updated_at" ], "default": "created_at" }, "in": "query", "name": "sort", "required": false, "description": "Field to sort by" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "in": "query", "name": "order", "required": false, "description": "Sort order" } ], "responses": { "200": { "description": "Server-Sent Events stream (text/event-stream)", "content": { "application/json": { "schema": { "type": "string", "description": "Server-Sent Events stream (text/event-stream)" } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/adyen-card-session": { "post": { "summary": "Create Adyen zero-value auth session for self-service card linking", "tags": [ "Payment Methods", "Loyalty" ], "description": "Creates an Adyen checkout session with amount=0 and storePaymentMethodMode=enabled.\n\nThe client initialises Adyen Drop-in with the returned `sessionId` and `sessionData`.\nAfter the user enters their card details, Adyen tokenises the card and issues a webhook.\nThe resulting token is stored in `user_payment_methods` for future card-linked loyalty recognition.\n\n**Requires authenticated user session.**\n\n**Permissions:** 🟢 `payment-methods.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "returnUrl": { "type": "string", "description": "Return URL after Adyen Drop-in completes" }, "channel": { "type": "string", "enum": [ "Web", "iOS", "Android" ], "description": "Client channel — defaults to Web" } }, "required": [ "returnUrl" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Adyen session ID for Drop-in initialisation" }, "sessionData": { "type": "string", "description": "Adyen session data for Drop-in initialisation" } }, "required": [ "sessionId", "sessionData" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/link-payment-method": { "post": { "summary": "Link payment card to user account", "tags": [ "Payment Methods", "Loyalty" ], "description": "Links a payment card (from a purchase) to a user account.\n\nThis endpoint:\n1. Extracts card data from the purchase\n2. Finds or creates a user by email/phone\n3. Links the card to the user for future recognition\n4. Optionally enrolls the user in the loyalty program\n5. Awards retroactive points for the triggering purchase\n\n**Use case**: After a guest makes a purchase and enters their email/phone,\ntheir card is linked so future purchases automatically earn loyalty points.\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseIntentId": { "type": "string", "description": "Purchase intent ID containing card data" }, "email": { "type": "string", "format": "email", "description": "User email (required if no phone)" }, "phone": { "type": "string", "description": "User phone number (required if no email)" }, "enrollInProgram": { "type": "boolean", "description": "Whether to also enroll in loyalty program" }, "locationId": { "type": "number", "description": "Location ID for enrollment (required if enrollInProgram)" } }, "required": [ "purchaseIntentId" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "number", "description": "User ID" }, "isNewUser": { "type": "boolean", "description": "Whether a new user was created" } }, "required": [ "id", "isNewUser" ] }, "paymentMethod": { "type": "object", "properties": { "linked": { "type": "boolean", "description": "Whether card was successfully linked" }, "id": { "type": "string", "format": "uuid", "nullable": true, "description": "Payment method UUID" }, "brand": { "type": "string", "nullable": true, "description": "Card brand" }, "last4": { "type": "string", "nullable": true, "description": "Last 4 digits" } }, "required": [ "linked", "id", "brand", "last4" ] }, "enrollment": { "type": "object", "nullable": true, "properties": { "enrolled": { "type": "boolean", "description": "Whether user was enrolled" }, "pointsAwarded": { "type": "number", "nullable": true, "description": "Retroactive points awarded" }, "newBalance": { "type": "number", "nullable": true, "description": "New points balance" } } } }, "required": [ "user", "paymentMethod", "enrollment" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/staff-link-payment-method": { "post": { "summary": "Staff-assisted card link with verbal consent", "tags": [ "Payment Methods", "Loyalty", "Staff" ], "description": "Links a payment card to a user account using verbal consent captured by a staff member.\n\nThis endpoint:\n1. Extracts card data from the purchase\n2. Links the card to the specified user with verbal consent\n3. Records a consent event with the staff member's retailerUserId\n4. Auto-enrolls the user in the location's loyalty program if not already enrolled\n5. Awards retroactive points for the triggering purchase\n\n**Use case**: When a guest doesn't scan the QR code, staff can look up the user\nand link their card manually after verbal confirmation.\n\n**Permissions:** 🟢 `loyalty.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseIntentId": { "type": "string", "description": "Purchase intent ID containing card data" }, "userId": { "type": "number", "description": "User ID to link the card to" }, "locationId": { "type": "number", "description": "Location ID for enrollment context" }, "consentMethod": { "type": "string", "enum": [ "verbal" ], "description": "Must be verbal for staff-assisted flow" }, "retailerUserId": { "type": "number", "description": "Staff member who captured verbal consent" } }, "required": [ "purchaseIntentId", "userId", "locationId", "consentMethod", "retailerUserId" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "cardLinked": { "type": "boolean", "description": "Whether card was successfully linked" }, "enrolled": { "type": "boolean", "description": "Whether user is enrolled in the loyalty program" }, "pointsAwarded": { "type": "number", "description": "Points awarded (welcome + retroactive)" } }, "required": [ "cardLinked", "enrolled", "pointsAwarded" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/loyalty/user-search": { "get": { "summary": "Search users by name, email, or phone (staff)", "tags": [ "Payment Methods", "Loyalty", "Staff" ], "description": "Search for users matching a query string. Used by staff during the fallback enrollment flow.\n\nQuery parameters:\n- **q**: Search term (minimum 2 characters) — matched against email, name, and phone\n- **purchaseIntentId**: Optional — if provided, the tab member for that purchase is auto-suggested\n\nResults are sorted by relevance. Maximum 10 results returned.\n\n**Permissions:** 🔵 `users.read`", "parameters": [ { "schema": { "type": "string", "minLength": 2 }, "in": "query", "name": "q", "required": true, "description": "Search term (name, email, or phone)" }, { "schema": { "type": "string" }, "in": "query", "name": "purchaseIntentId", "required": false, "description": "Optional purchase intent ID for tab member auto-suggest" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "User ID" }, "email": { "type": "string", "nullable": true, "description": "User email" }, "firstName": { "type": "string", "nullable": true, "description": "First name" }, "lastName": { "type": "string", "nullable": true, "description": "Last name" }, "phone": { "type": "string", "nullable": true, "description": "Phone number" } }, "required": [ "id" ] }, "description": "Matching users (max 10)" }, "autoSuggested": { "type": "object", "nullable": true, "description": "Tab member auto-suggested for the purchase (if purchaseIntentId provided)", "properties": { "userId": { "type": "number" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "autoSuggested": { "type": "boolean", "enum": [ true ] } } } }, "required": [ "users", "autoSuggested" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/payment-methods": { "get": { "summary": "List Adyen-configured payment methods for anonymous storefront guests", "tags": [ "Payment Methods" ], "description": "Phase 39 — Returns Adyen-configured payment methods for a location so anonymous storefront-web guests can see Klarna / Swish / scheme rows on the v3 upfront flow. Authenticates via X-API-Key. Saved-method/enrichment fields are always empty/null (no user context).", "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "locationId", "required": true }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "amountCents", "required": true }, { "schema": { "type": "string", "minLength": 3, "maxLength": 3 }, "in": "query", "name": "currencyCode", "required": true }, { "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "in": "query", "name": "countryCode", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "paymentMethods": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Always empty for anonymous callers (no user-bound saved methods)." }, "paymentMethodsResponse": { "type": "object", "additionalProperties": true, "description": "Adyen /paymentMethods response — used by storefront to render method rows (Klarna, Swish, scheme)." }, "clientKey": { "type": "string", "nullable": true }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "defaultStoredMethodId": { "type": "string", "nullable": true }, "lastUsedStoredMethodId": { "type": "string", "nullable": true }, "lastUsedKind": { "type": "string", "enum": [ "card", "swish" ], "nullable": true }, "savedSwish": { "type": "object", "nullable": true, "additionalProperties": true } }, "required": [ "paymentMethods", "paymentMethodsResponse", "environment" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases/{purchaseIntentId}/loyalty-status": { "get": { "summary": "Get loyalty status for a purchase", "tags": [ "Payment Methods", "Loyalty" ], "description": "Returns the loyalty scenario after a purchase completes.\n\nUsed by the frontend to determine what modal/action to show:\n- **POINTS_EARNED**: User is enrolled, points were awarded automatically\n- **ENROLLMENT_AVAILABLE**: Card is linked to user, but not enrolled at this location\n- **CARD_LINK_AVAILABLE**: Card is not linked to any user, prompt for email/phone\n- **NO_LOYALTY_PROGRAM**: Location has no loyalty program\n- **PROCESSING**: Still processing (retry later)\n\n**Permissions:** 🔵 `loyalty.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "purchaseIntentId", "required": true, "description": "Purchase intent ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "loyaltyScenario": { "type": "string", "enum": [ "POINTS_EARNED", "ENROLLMENT_AVAILABLE", "CARD_LINK_AVAILABLE", "NO_LOYALTY_PROGRAM", "PROCESSING" ], "description": "The loyalty scenario based on card/user recognition" }, "pointsEarned": { "type": "object", "nullable": true, "properties": { "points": { "type": "number", "description": "Points earned from this purchase" }, "newBalance": { "type": "number", "description": "New total points balance" } } }, "enrollmentOffer": { "type": "object", "nullable": true, "properties": { "programId": { "type": "number", "description": "Loyalty program ID" }, "programName": { "type": "string", "description": "Loyalty program name" }, "potentialPoints": { "type": "number", "description": "Points user would earn by enrolling" } } }, "cardLinkOffer": { "type": "object", "nullable": true, "properties": { "programId": { "type": "number", "description": "Loyalty program ID" }, "programName": { "type": "string", "description": "Loyalty program name" }, "potentialPoints": { "type": "number", "description": "Points user would earn by linking card" }, "brand": { "type": "string", "nullable": true, "description": "Card brand" }, "last4": { "type": "string", "nullable": true, "description": "Last 4 digits of card" } } }, "user": { "type": "object", "nullable": true, "properties": { "id": { "type": "number", "description": "User ID" }, "email": { "type": "string", "nullable": true, "description": "User email" } } }, "location": { "type": "object", "properties": { "id": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Location name" }, "hasLoyaltyProgram": { "type": "boolean", "description": "Whether location has an active loyalty program" } }, "required": [ "id", "name", "hasLoyaltyProgram" ] } }, "required": [ "loyaltyScenario", "pointsEarned", "enrollmentOffer", "cardLinkOffer", "user", "location" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/retailer/users/{userId}/payment-methods": { "get": { "summary": "List payment methods for a specific user (staff view)", "tags": [ "Payment Methods" ], "description": "Returns all saved payment methods for a specific user.\n\nUsed by staff to view linked payment cards on the loyalty member detail page.\nThis is a read-only view — staff cannot modify user payment methods through this endpoint.\n\n**Permissions:** 🔵 `users.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "userId", "required": true, "description": "User ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "paymentMethods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Payment method UUID" }, "nickname": { "type": "string", "nullable": true, "description": "User-defined nickname or auto-generated (e.g., \"Visa ***4242\")" }, "brand": { "type": "string", "nullable": true, "description": "Card brand (visa, mastercard, etc.)" }, "last4": { "type": "string", "nullable": true, "description": "Last 4 digits of card number" }, "expiryMonth": { "type": "number", "nullable": true, "description": "Card expiry month (1-12)" }, "expiryYear": { "type": "number", "nullable": true, "description": "Card expiry year (4 digits)" }, "isDefault": { "type": "boolean", "description": "Whether this is the default payment method" }, "isTokenized": { "type": "boolean", "description": "Whether this card is tokenized for recurring payments" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last time this payment method was used" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the payment method was saved" } }, "additionalProperties": false }, "description": "List of saved payment methods" }, "defaultStoredMethodId": { "type": "string", "nullable": true, "description": "Adyen storedPaymentMethodId of the user's default card, or null" }, "lastUsedStoredMethodId": { "type": "string", "nullable": true, "description": "Adyen storedPaymentMethodId of the most recently used method, or null" }, "lastUsedKind": { "type": "string", "enum": [ "card", "swish" ], "nullable": true, "description": "Kind of the most recently used active method, or null when no usage history" }, "savedSwish": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid", "description": "user_payment_methods.uuid for the kind=swish row" }, "payerAlias": { "type": "string", "description": "Verified phone alias in E.164" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "uuid", "payerAlias", "lastUsedAt" ] } }, "required": [ "paymentMethods" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/users/me/payment-methods": { "get": { "summary": "List saved payment methods", "tags": [ "Payment Methods" ], "description": "Returns all saved payment methods for the authenticated user.\n\nPayment methods are sorted by:\n1. Default payment method first\n2. Most recently used\n3. Creation date\n\n**Permissions:** 🔵 `payment-methods.read`", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "paymentMethods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Payment method UUID" }, "nickname": { "type": "string", "nullable": true, "description": "User-defined nickname or auto-generated (e.g., \"Visa ***4242\")" }, "brand": { "type": "string", "nullable": true, "description": "Card brand (visa, mastercard, etc.)" }, "last4": { "type": "string", "nullable": true, "description": "Last 4 digits of card number" }, "expiryMonth": { "type": "number", "nullable": true, "description": "Card expiry month (1-12)" }, "expiryYear": { "type": "number", "nullable": true, "description": "Card expiry year (4 digits)" }, "isDefault": { "type": "boolean", "description": "Whether this is the default payment method" }, "isTokenized": { "type": "boolean", "description": "Whether this card is tokenized for recurring payments" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last time this payment method was used" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the payment method was saved" } }, "additionalProperties": false }, "description": "List of saved payment methods" }, "defaultStoredMethodId": { "type": "string", "nullable": true, "description": "Adyen storedPaymentMethodId of the user's default card, or null" }, "lastUsedStoredMethodId": { "type": "string", "nullable": true, "description": "Adyen storedPaymentMethodId of the most recently used method, or null" }, "lastUsedKind": { "type": "string", "enum": [ "card", "swish" ], "nullable": true, "description": "Kind of the most recently used active method, or null when no usage history" }, "savedSwish": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid", "description": "user_payment_methods.uuid for the kind=swish row" }, "payerAlias": { "type": "string", "description": "Verified phone alias in E.164" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "uuid", "payerAlias", "lastUsedAt" ] } }, "required": [ "paymentMethods" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/users/me/payment-methods/{id}": { "delete": { "summary": "Remove saved payment method", "tags": [ "Payment Methods" ], "description": "Removes a saved payment method (soft delete). The card will no longer be recognized for loyalty purposes.\n\n**Permissions:** 🔴 `payment-methods.delete`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Payment method UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "patch": { "summary": "Update payment method", "tags": [ "Payment Methods" ], "description": "Updates a payment method's nickname.\n\n**Permissions:** 🟠 `payment-methods.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "nickname": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Custom nickname for the card" } }, "required": [ "nickname" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Payment method UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Payment method UUID" }, "nickname": { "type": "string", "nullable": true, "description": "User-defined nickname or auto-generated (e.g., \"Visa ***4242\")" }, "brand": { "type": "string", "nullable": true, "description": "Card brand (visa, mastercard, etc.)" }, "last4": { "type": "string", "nullable": true, "description": "Last 4 digits of card number" }, "expiryMonth": { "type": "number", "nullable": true, "description": "Card expiry month (1-12)" }, "expiryYear": { "type": "number", "nullable": true, "description": "Card expiry year (4 digits)" }, "isDefault": { "type": "boolean", "description": "Whether this is the default payment method" }, "isTokenized": { "type": "boolean", "description": "Whether this card is tokenized for recurring payments" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last time this payment method was used" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the payment method was saved" } }, "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/users/me/payment-methods/{id}/default": { "post": { "summary": "Set default payment method", "tags": [ "Payment Methods" ], "description": "Sets a payment method as the default for the authenticated user.\n\n**Permissions:** 🟠 `payment-methods.update`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Payment method UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/permissions": { "get": { "summary": "List permissions", "tags": [ "Permissions" ], "description": "List all permissions in the system with optional filters\n\n**Permissions:** 🔵 `permissions.read`", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "category", "required": false, "description": "Filter by category" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Search by key, name, or description" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "number", "minimum": 1, "maximum": 1000, "default": 50 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "key": { "type": "string", "example": "inventory.read" }, "name": { "type": "string", "example": "Read Inventory" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true, "example": "Inventory" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create permission", "tags": [ "Permissions" ], "description": "Create a new permission in the system\n\nINTERNAL: Only accessible to specific Karmeleon user IDs\n\n**Permissions:** 🟢 `permissions.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "name" ], "properties": { "key": { "type": "string", "pattern": "^[a-z]+\\.[a-z]+$", "description": "Dot notation permission key (e.g., resource.action)" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true } } } } }, "required": true }, "x-internal": true, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "key": { "type": "string", "example": "inventory.read" }, "name": { "type": "string", "example": "Read Inventory" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true, "example": "Inventory" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/permissions/{id}": { "get": { "summary": "Get permission", "tags": [ "Permissions" ], "description": "Get a single permission by ID\n\n**Permissions:** 🔵 `permissions.read`", "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "id", "required": true, "description": "Permission ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "key": { "type": "string", "example": "inventory.read" }, "name": { "type": "string", "example": "Read Inventory" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true, "example": "Inventory" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update permission", "tags": [ "Permissions" ], "description": "Update an existing permission\n\nINTERNAL: Only accessible to specific Karmeleon user IDs\n\nNote: Cannot update permission key\n\n**Permissions:** 🟠 `permissions.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true } } } } } }, "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "id", "required": true, "description": "Permission ID" } ], "x-internal": true, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "key": { "type": "string", "example": "inventory.read" }, "name": { "type": "string", "example": "Read Inventory" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true, "example": "Inventory" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete permission", "tags": [ "Permissions" ], "description": "Delete a permission\n\nINTERNAL: Only accessible to specific Karmeleon user IDs\n\nNote: Cannot delete permissions in use by roles or users\n\n**Permissions:** 🔴 `permissions.delete`", "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "id", "required": true, "description": "Permission ID" } ], "x-internal": true, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "number" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/permissions/matrix": { "get": { "summary": "Get permission matrix", "tags": [ "Permissions" ], "description": "Get all permissions grouped by resource for display in a matrix\n\n**Permissions:** 🔵 `permissions.read`", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "resources": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "key": { "type": "string", "example": "inventory.read" }, "name": { "type": "string", "example": "Read Inventory" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true, "example": "Inventory" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/print-settings": { "get": { "summary": "Get location print settings", "tags": [ "Print Templates" ], "description": "Get print settings for a specific location", "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "locationId": { "type": "number" }, "fontSize": { "type": "number", "nullable": true, "minimum": 1, "maximum": 4 }, "fontFamily": { "type": "string", "nullable": true, "enum": [ "a", "b" ] }, "lineSpacing": { "type": "number", "nullable": true, "minimum": 1, "maximum": 5 }, "logoUrl": { "type": "string", "nullable": true }, "headerText": { "type": "string", "nullable": true }, "footerText": { "type": "string", "nullable": true }, "showLogo": { "type": "boolean", "nullable": true }, "printQrCode": { "type": "boolean", "nullable": true }, "printVatBreakdown": { "type": "boolean", "nullable": true }, "kitchenTicketBeep": { "type": "boolean", "nullable": true }, "language": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Save location print settings", "tags": [ "Print Templates" ], "description": "Create or update print settings for a location", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "fontSize": { "type": "number", "minimum": 1, "maximum": 4, "nullable": true }, "fontFamily": { "type": "string", "enum": [ "a", "b" ], "nullable": true }, "lineSpacing": { "type": "number", "minimum": 1, "maximum": 5, "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "headerText": { "type": "string", "nullable": true }, "footerText": { "type": "string", "nullable": true }, "showLogo": { "type": "boolean", "nullable": true }, "printQrCode": { "type": "boolean", "nullable": true }, "printVatBreakdown": { "type": "boolean", "nullable": true }, "kitchenTicketBeep": { "type": "boolean", "nullable": true }, "language": { "type": "string", "nullable": true } } } } } }, "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "locationId": { "type": "number" }, "fontSize": { "type": "number", "nullable": true, "minimum": 1, "maximum": 4 }, "fontFamily": { "type": "string", "nullable": true, "enum": [ "a", "b" ] }, "lineSpacing": { "type": "number", "nullable": true, "minimum": 1, "maximum": 5 }, "logoUrl": { "type": "string", "nullable": true }, "headerText": { "type": "string", "nullable": true }, "footerText": { "type": "string", "nullable": true }, "showLogo": { "type": "boolean", "nullable": true }, "printQrCode": { "type": "boolean", "nullable": true }, "printVatBreakdown": { "type": "boolean", "nullable": true }, "kitchenTicketBeep": { "type": "boolean", "nullable": true }, "language": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete location print settings", "tags": [ "Print Templates" ], "description": "Delete print settings for a location (reset to defaults)", "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "locationId": { "type": "number" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/template-overrides": { "get": { "summary": "List location template overrides", "tags": [ "Print Templates" ], "description": "Get all template overrides for a specific location", "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "overrides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "locationId": { "type": "number" }, "templateType": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "overrideScope": { "type": "string", "enum": [ "full", "section", "settings" ] }, "customTemplateContent": { "type": "object", "nullable": true, "additionalProperties": true }, "sectionOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "settingsOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/template-overrides/{templateType}": { "get": { "summary": "Get location template override", "tags": [ "Print Templates" ], "description": "Get a specific template override for a location", "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true }, { "schema": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "in": "path", "name": "templateType", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "locationId": { "type": "number" }, "templateType": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "overrideScope": { "type": "string", "enum": [ "full", "section", "settings" ] }, "customTemplateContent": { "type": "object", "nullable": true, "additionalProperties": true }, "sectionOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "settingsOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Save location template override", "tags": [ "Print Templates" ], "description": "Create or update a template override for a location", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "overrideScope" ], "properties": { "overrideScope": { "type": "string", "enum": [ "full", "section", "settings" ] }, "customTemplateContent": { "type": "object", "nullable": true, "additionalProperties": true }, "sectionOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "settingsOverrides": { "type": "object", "nullable": true, "additionalProperties": true } } } } }, "required": true }, "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "locationId", "required": true }, { "schema": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "in": "path", "name": "templateType", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "locationId": { "type": "number" }, "templateType": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "overrideScope": { "type": "string", "enum": [ "full", "section", "settings" ] }, "customTemplateContent": { "type": "object", "nullable": true, "additionalProperties": true }, "sectionOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "settingsOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-templates": { "get": { "summary": "List print templates", "tags": [ "Print Templates" ], "description": "Get a list of all print templates with optional filtering", "parameters": [ { "schema": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "in": "query", "name": "type", "required": false, "description": "Filter by template type" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isActive", "required": false, "description": "Filter by active status" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isSystem", "required": false, "description": "Filter by system template status" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "number", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "version": { "type": "number" }, "isActive": { "type": "boolean" }, "isSystem": { "type": "boolean" }, "content": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "number", "nullable": true } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create print template", "tags": [ "Print Templates" ], "description": "Create a new custom print template", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "name", "content" ], "properties": { "type": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "content": { "type": "object", "additionalProperties": true } } } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "version": { "type": "number" }, "isActive": { "type": "boolean" }, "isSystem": { "type": "boolean" }, "content": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "number", "nullable": true } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-templates/{id}": { "get": { "summary": "Get print template", "tags": [ "Print Templates" ], "description": "Get a single print template by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "version": { "type": "number" }, "isActive": { "type": "boolean" }, "isSystem": { "type": "boolean" }, "content": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "number", "nullable": true } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "patch": { "summary": "Update print template", "tags": [ "Print Templates" ], "description": "Update an existing custom print template (system templates cannot be modified)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "content": { "type": "object", "additionalProperties": true }, "isActive": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "version": { "type": "number" }, "isActive": { "type": "boolean" }, "isSystem": { "type": "boolean" }, "content": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "number", "nullable": true } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete print template", "tags": [ "Print Templates" ], "description": "Delete a custom print template (system templates cannot be deleted)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-templates/type/{type}": { "get": { "summary": "Get active print template by type", "tags": [ "Print Templates" ], "description": "Get the currently active print template for a specific type", "parameters": [ { "schema": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "in": "path", "name": "type", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "version": { "type": "number" }, "isActive": { "type": "boolean" }, "isSystem": { "type": "boolean" }, "content": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "number", "nullable": true } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/template-overrides/{id}": { "patch": { "summary": "Update location template override", "tags": [ "Print Templates" ], "description": "Update an existing template override", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "overrideScope": { "type": "string", "enum": [ "full", "section", "settings" ] }, "customTemplateContent": { "type": "object", "nullable": true, "additionalProperties": true }, "sectionOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "settingsOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "isActive": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "locationId": { "type": "number" }, "templateType": { "type": "string", "enum": [ "kitchen_ticket", "purchase_receipt", "pre_check", "order_confirmation", "custom" ] }, "overrideScope": { "type": "string", "enum": [ "full", "section", "settings" ] }, "customTemplateContent": { "type": "object", "nullable": true, "additionalProperties": true }, "sectionOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "settingsOverrides": { "type": "object", "nullable": true, "additionalProperties": true }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete location template override", "tags": [ "Print Templates" ], "description": "Delete a template override for a location", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-jobs/custom": { "post": { "tags": [ "Printers" ], "description": "Create a custom print job with Star Micronics Markdown.\n\nThis endpoint allows sending raw Star Micronics Markdown content directly to a printer. Use this for custom receipt formats, promotional prints, or testing.\n\n**Star Micronics Markdown Reference:**\n- `[C]` - Center alignment\n- `[L]` - Left alignment\n- `[R]` - Right alignment\n- `[D:1]` to `[D:4]` - Font size (1 is normal, 4 is largest)\n- `[CUT]` - Cut paper\n- `---` - Horizontal line\n\n**Example:**\n```\n[C][D:2]Welcome to Karma!\n[C][D:1]---\n[L]Your custom content here\n[CUT]\n```", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group to print to" }, "content": { "type": "string", "description": "Star Micronics Markdown content to print", "minLength": 1, "maxLength": 10000 } }, "required": [ "printerGroupId", "content" ] } } }, "required": true }, "responses": { "201": { "description": "Custom print job created successfully", "content": { "application/json": { "schema": { "description": "Custom print job created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "correlationId": { "type": "string", "format": "uuid", "description": "Unique correlation ID for tracking the print job" }, "type": { "type": "string", "enum": [ "custom" ] }, "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group the job was sent to" } }, "required": [ "correlationId", "type", "printerGroupId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-jobs/kiosk-order-confirmation": { "post": { "summary": "Print kiosk order confirmation", "tags": [ "Printers" ], "description": "Print an order confirmation slip on the kiosk's printer.\n\nGuest-facing endpoint fired by the storefront confirmation page. Resolves the\npurchase's kitchen dispatch and prints an order confirmation (order number +\nQR code) to the specified printer group.\n\n**Flow:**\n1. Resolves `purchaseIntentId` → kitchen dispatch ID via the purchase's order.\n2. Validates the printer group belongs to the location.\n3. Sends an `order_confirmation` print job to the group.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseIntentId": { "type": "string", "format": "uuid", "description": "Purchase intent ID from the storefront payment flow" }, "printerId": { "type": "string", "format": "uuid", "description": "Printer ID from qrCode.printer — resolved to its group server-side" } }, "required": [ "purchaseIntentId", "printerId" ] } } }, "required": true }, "responses": { "201": { "description": "Print job created successfully", "content": { "application/json": { "schema": { "description": "Print job created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "correlationId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "order_confirmation" ] }, "printerGroupId": { "type": "string", "format": "uuid" } }, "required": [ "correlationId", "type", "printerGroupId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-jobs/kiosk-receipt": { "post": { "summary": "Print kiosk receipt", "tags": [ "Printers" ], "description": "Auto-print an order receipt on a kiosk's attached printer.\n\nFired by the storefront on the confirmation page when the kiosk's QR code has a `printer` UUID configured. The storefront only knows the `purchaseIntentId`; this endpoint resolves the underlying purchase plus the printer's group and issues a targeted print job so only the kiosk's printer produces the receipt.\n\n**Flow:**\n1. Resolves `purchase.id` from the given `purchaseIntentId` (scoped to the location).\n2. Resolves the printer's group (scoped to the location) so the wrong kiosk can't be targeted.\n3. Publishes a `purchase_receipt` print job with `targetPrinterId` set so only that physical printer picks it up.\n4. Returns the correlation ID for tracking.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseIntentId": { "type": "string", "format": "uuid", "description": "Purchase intent ID from the storefront payment flow" }, "printerId": { "type": "string", "format": "uuid", "description": "UUID of the kiosk-attached printer (read from qrCode.printer)" } }, "required": [ "purchaseIntentId", "printerId" ] } } }, "required": true }, "responses": { "201": { "description": "Print job created successfully", "content": { "application/json": { "schema": { "description": "Print job created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "correlationId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "purchase_receipt" ] }, "printerGroupId": { "type": "string", "format": "uuid" }, "printerId": { "type": "string", "format": "uuid" }, "purchaseId": { "type": "string" } }, "required": [ "correlationId", "type", "printerGroupId", "printerId", "purchaseId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-jobs/kitchen-ticket-reprint": { "post": { "tags": [ "Printers" ], "description": "Reprint a kitchen ticket for an existing order.\n\nThis endpoint reprints kitchen tickets for a kitchen dispatch (order). Items are automatically routed to the correct printer groups based on printer group item configuration.\n\n**Important:** Unlike the original print, this is a reprint operation that bypasses idempotency checks. Each call will create new print jobs.\n\n**Flow:**\n1. Fetches kitchen dispatch with items, events, and comments\n2. Fetches printer groups for the location\n3. Routes items to correct printer groups based on printer_group_items configuration\n4. Sends print jobs for each printer group with relevant items", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "ID of the kitchen dispatch (order) to reprint tickets for" } }, "required": [ "kitchenDispatchId" ] } } }, "required": true }, "responses": { "201": { "description": "Kitchen ticket reprint jobs created successfully", "content": { "application/json": { "schema": { "description": "Kitchen ticket reprint jobs created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "correlationId": { "type": "string", "format": "uuid", "description": "Unique correlation ID for tracking the print jobs" }, "type": { "type": "string", "enum": [ "kitchen_ticket" ] }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "ID of the kitchen dispatch" }, "message": { "type": "string", "description": "Status message indicating the print request was submitted" } }, "required": [ "correlationId", "type", "kitchenDispatchId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-jobs/order-confirmation": { "post": { "tags": [ "Printers" ], "description": "Create an order confirmation print job.\n\nThis endpoint prints an order confirmation slip for a kitchen dispatch (order). Used by POS when \"print order confirmation\" is enabled.\n\n**Order Confirmation Contents:**\n- Order number (daily ordinal)\n- Order date/time\n- QR code for order tracking\n- Table name (if applicable)\n\n**Flow:**\n1. Validates printer group belongs to location\n2. Fetches kitchen dispatch data\n3. Sends print job to printer service via Pub/Sub", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group to print to" }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "ID of the kitchen dispatch (order) to print confirmation for" } }, "required": [ "printerGroupId", "kitchenDispatchId" ] } } }, "required": true }, "responses": { "201": { "description": "Order confirmation print job created successfully", "content": { "application/json": { "schema": { "description": "Order confirmation print job created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "correlationId": { "type": "string", "format": "uuid", "description": "Unique correlation ID for tracking the print job" }, "type": { "type": "string", "enum": [ "order_confirmation" ] }, "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group the job was sent to" }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "ID of the kitchen dispatch" } }, "required": [ "correlationId", "type", "printerGroupId", "kitchenDispatchId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-jobs/pre-check": { "post": { "tags": [ "Printers" ], "description": "Create a pre-check (pro forma bill) print job for a table.\n\nThis endpoint prints a pre-check showing all items on a table's tab with totals and a payment QR code. Used when guests want to see their bill before paying.\n\n**Flow:**\n1. Validates printer group belongs to location\n2. Fetches tab with all items, prices, and table info\n3. Generates QR code URL for payment\n4. Sends complete data to printer service via Pub/Sub", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group to print to" }, "tabId": { "type": "string", "format": "uuid", "description": "ID of the tab (QR code/table) to print pre-check for" }, "selectedKdiItemIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional kitchen_dispatch_items UUIDs to restrict the pro forma to. When set, only these items (and their children) are printed; otherwise the entire unpaid tab is printed." } }, "required": [ "printerGroupId", "tabId" ] } } }, "required": true }, "responses": { "201": { "description": "Pre-check print job created successfully", "content": { "application/json": { "schema": { "description": "Pre-check print job created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "correlationId": { "type": "string", "format": "uuid", "description": "Unique correlation ID for tracking the print job" }, "type": { "type": "string", "enum": [ "pre_check" ] }, "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group the job was sent to" }, "tabId": { "type": "string", "format": "uuid", "description": "ID of the tab" } }, "required": [ "correlationId", "type", "printerGroupId", "tabId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-jobs/purchase-receipt": { "post": { "tags": [ "Printers" ], "description": "Create a purchase receipt print job.\n\nThis endpoint fetches the purchase data from the database and sends a complete print job to the printer service via Pub/Sub. The printer service will render the receipt using the appropriate template.\n\n**Flow:**\n1. Validates printer group belongs to location\n2. Fetches purchase data with line items, VAT breakdown, and location info\n3. Sends complete data to printer service via Pub/Sub\n4. Returns correlation ID for tracking", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group to print to" }, "purchaseId": { "type": "string", "description": "ID of the purchase to print receipt for" } }, "required": [ "printerGroupId", "purchaseId" ] } } }, "required": true }, "responses": { "201": { "description": "Print job created successfully", "content": { "application/json": { "schema": { "description": "Print job created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "correlationId": { "type": "string", "format": "uuid", "description": "Unique correlation ID for tracking the print job" }, "type": { "type": "string", "enum": [ "purchase_receipt", "kitchen_ticket", "pre_check", "order_confirmation", "test_print", "custom" ], "description": "Type of print job" }, "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group the job was sent to" }, "purchaseId": { "type": "string", "description": "ID of the purchase (for purchase_receipt type)" } }, "required": [ "correlationId", "type", "printerGroupId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-jobs/refund-receipt": { "post": { "tags": [ "Printers" ], "description": "Create a refund receipt print job.\n\nThis endpoint prints a refund receipt for a completed purchase refund. Used from the merchant dashboard when staff want to print a physical refund receipt.\n\n**Flow:**\n1. Validates printer group belongs to location\n2. Sends refund receipt print job to printer service via Pub/Sub\n3. Printer service fetches refund data and renders the receipt\n4. Returns correlation ID for tracking", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group to print to" }, "purchaseRefundId": { "type": "string", "description": "ID of the purchase refund to print receipt for" } }, "required": [ "printerGroupId", "purchaseRefundId" ] } } }, "required": true }, "responses": { "201": { "description": "Refund receipt print job created successfully", "content": { "application/json": { "schema": { "description": "Refund receipt print job created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "correlationId": { "type": "string", "format": "uuid", "description": "Unique correlation ID for tracking the print job" }, "type": { "type": "string", "enum": [ "refund_receipt" ] }, "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group the job was sent to" }, "purchaseRefundId": { "type": "string", "description": "ID of the purchase refund" } }, "required": [ "correlationId", "type", "printerGroupId", "purchaseRefundId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-jobs/terminal-receipt": { "post": { "tags": [ "Printers" ], "description": "Print a receipt on the Adyen terminal.\n\nCalled from the POS receipt dialog after payment completes. The actual printing is fire-and-forget — this returns 202 immediately.\n\n**Flow:**\n1. Proxies request to payment-service\n2. Payment-service fetches receipt data and sends print command to terminal\n3. Returns 202 Accepted immediately", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseIntentId": { "type": "string", "format": "uuid", "description": "ID of the purchase intent to print receipt for" }, "terminalId": { "type": "string", "format": "uuid", "description": "ID of the Adyen terminal to print on" } }, "required": [ "purchaseIntentId", "terminalId" ] } } }, "required": true }, "responses": { "202": { "description": "Terminal receipt print initiated", "content": { "application/json": { "schema": { "description": "Terminal receipt print initiated", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "terminal_receipt" ] }, "purchaseIntentId": { "type": "string", "format": "uuid" }, "terminalId": { "type": "string", "format": "uuid" } }, "required": [ "type", "purchaseIntentId", "terminalId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/print-jobs/test": { "post": { "tags": [ "Printers" ], "description": "Create a test print job.\n\nThis endpoint sends a test page to the specified printer group. Use this to verify printer connectivity and configuration.\n\n**Test Page Contents:**\n- Service name and timestamp\n- Custom message (if provided)\n- Printer configuration info", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group to send test print to" }, "message": { "type": "string", "description": "Optional custom message to include on the test print", "maxLength": 500 } }, "required": [ "printerGroupId" ] } } }, "required": true }, "responses": { "201": { "description": "Test print job created successfully", "content": { "application/json": { "schema": { "description": "Test print job created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "correlationId": { "type": "string", "format": "uuid", "description": "Unique correlation ID for tracking the print job" }, "type": { "type": "string", "enum": [ "test_print" ] }, "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group the job was sent to" } }, "required": [ "correlationId", "type", "printerGroupId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printer-dashboard": { "get": { "tags": [ "Printers" ], "description": "Get printer dashboard with summary stats and recent activity", "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "locationId", "required": false, "description": "Location ID. If not provided, uses X-Location-Id header or default location." } ], "responses": { "200": { "description": "Successfully retrieved printer dashboard", "content": { "application/json": { "schema": { "description": "Successfully retrieved printer dashboard", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "activePrinters": { "type": "integer" }, "pendingJobs": { "type": "integer" }, "printingJobs": { "type": "integer" }, "failedJobs24h": { "type": "integer" }, "completedJobs24h": { "type": "integer" } }, "required": [ "activePrinters", "pendingJobs", "printingJobs", "failedJobs24h", "completedJobs24h" ] }, "recentActivity": { "type": "array", "items": { "type": "object", "properties": { "jobId": { "type": "string" }, "jobNumber": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "printer": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "macAddress": { "type": "string", "nullable": true }, "isOnline": { "type": "boolean" } } }, "printerGroup": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "locationId": { "type": "integer" }, "locationName": { "type": "string" } } }, "currentStatus": { "type": "string" }, "statusChangedAt": { "type": "string", "format": "date-time" }, "retries": { "type": "integer" }, "duration": { "type": "integer", "nullable": true }, "contentType": { "type": "string" }, "contentPreview": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true }, "kitchenDispatch": { "type": "object", "nullable": true, "properties": { "orderNumber": { "type": "string" }, "tableNumber": { "type": "string", "nullable": true }, "totalAmount": { "type": "number", "nullable": true }, "itemCount": { "type": "integer" } } } } } } }, "required": [ "summary", "recentActivity" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printer-groups": { "get": { "tags": [ "Printers" ], "description": "List all printer groups (prep groups) for a location with their printers", "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "locationId", "required": false, "description": "Location ID to filter printer groups. If not provided, uses X-Location-Id header or default location." } ], "responses": { "200": { "description": "Successfully retrieved printer groups", "content": { "application/json": { "schema": { "description": "Successfully retrieved printer groups", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "printerGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer group identifier" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer group" }, "type": { "type": "string", "nullable": true, "description": "Type of the printer group" }, "color": { "type": "string", "nullable": true, "description": "Color for the printer group (hex code, e.g. #FF5733). Null renders as gray." }, "defaultItemState": { "type": "string", "nullable": true, "enum": [ "pending", "accepted", "ready_to_deliver", null ], "description": "Default item state for orders routed to this prep group. Null means use location/system default." }, "locationId": { "type": "integer", "description": "Location ID where the printer group is configured" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer group was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer group was last updated" }, "metaData": { "type": "object", "nullable": true, "properties": { "fontSize": { "type": "string", "nullable": true, "description": "Font size setting for receipts" }, "logotypeUrl": { "type": "string", "nullable": true, "description": "URL of the logo to print on receipts" }, "message": { "type": "string", "nullable": true, "description": "Custom message to print on receipts" }, "displayPayQRProforma": { "type": "boolean", "nullable": true, "description": "Whether to display payment QR code on proforma" }, "displayOrderQRReciept": { "type": "boolean", "nullable": true, "description": "Whether to display order QR code on receipt" } } }, "printers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer identifier" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility." }, "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Primary prep group memberships — the printer prints these groups' items via the flow engine." }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Secondary (\"ride-along\") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own." }, "locationId": { "type": "integer", "description": "Location ID where the printer is installed" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer (from printer group)" }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "nullable": true, "description": "Hardware type of the printer" }, "status": { "type": "string", "nullable": true, "description": "Last reported status code from the printer" }, "state": { "type": "string", "enum": [ "online", "offline" ], "description": "Current state of the printer (online if both printer is online and group is published)" }, "idle": { "type": "boolean", "nullable": true, "description": "Whether the printer is currently idle (not processing jobs)" }, "cloudPrntUrl": { "type": "string", "format": "uri", "description": "CloudPRNT polling URL to configure on the physical printer", "example": "https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer was last updated" } }, "required": [ "id", "locationId", "state", "cloudPrntUrl", "createdAt", "updatedAt" ] }, "description": "Printers in this group with CloudPRNT URLs" } }, "required": [ "id", "locationId", "createdAt", "updatedAt", "printers" ] } }, "total": { "type": "integer", "description": "Total number of printer groups" } }, "required": [ "printerGroups", "total" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "tags": [ "Printers" ], "description": "Create a new printer group (prep group)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name for the printer group" }, "type": { "type": "string", "enum": [ "bar", "kitchen", "all", "none" ], "description": "Type of the printer group (defaults to kitchen)" }, "color": { "type": "string", "nullable": true, "description": "Color for the printer group (hex code, e.g. #FF5733)" }, "defaultItemState": { "type": "string", "nullable": true, "enum": [ "pending", "accepted", "ready_to_deliver", null ], "description": "Default item state for orders routed to this prep group. Null means use location/system default." } }, "required": [ "name" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "locationId", "required": false, "description": "Location ID. If not provided, uses X-Location-Id header or default location." } ], "responses": { "201": { "description": "Successfully created printer group", "content": { "application/json": { "schema": { "description": "Successfully created printer group", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "printerGroup": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer group identifier" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer group" }, "type": { "type": "string", "nullable": true, "description": "Type of the printer group" }, "color": { "type": "string", "nullable": true, "description": "Color for the printer group (hex code, e.g. #FF5733). Null renders as gray." }, "defaultItemState": { "type": "string", "nullable": true, "enum": [ "pending", "accepted", "ready_to_deliver", null ], "description": "Default item state for orders routed to this prep group. Null means use location/system default." }, "locationId": { "type": "integer", "description": "Location ID where the printer group is configured" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer group was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer group was last updated" }, "metaData": { "type": "object", "nullable": true, "properties": { "fontSize": { "type": "string", "nullable": true, "description": "Font size setting for receipts" }, "logotypeUrl": { "type": "string", "nullable": true, "description": "URL of the logo to print on receipts" }, "message": { "type": "string", "nullable": true, "description": "Custom message to print on receipts" }, "displayPayQRProforma": { "type": "boolean", "nullable": true, "description": "Whether to display payment QR code on proforma" }, "displayOrderQRReciept": { "type": "boolean", "nullable": true, "description": "Whether to display order QR code on receipt" } } }, "printers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer identifier" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility." }, "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Primary prep group memberships — the printer prints these groups' items via the flow engine." }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Secondary (\"ride-along\") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own." }, "locationId": { "type": "integer", "description": "Location ID where the printer is installed" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer (from printer group)" }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "nullable": true, "description": "Hardware type of the printer" }, "status": { "type": "string", "nullable": true, "description": "Last reported status code from the printer" }, "state": { "type": "string", "enum": [ "online", "offline" ], "description": "Current state of the printer (online if both printer is online and group is published)" }, "idle": { "type": "boolean", "nullable": true, "description": "Whether the printer is currently idle (not processing jobs)" }, "cloudPrntUrl": { "type": "string", "format": "uri", "description": "CloudPRNT polling URL to configure on the physical printer", "example": "https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer was last updated" } }, "required": [ "id", "locationId", "state", "cloudPrntUrl", "createdAt", "updatedAt" ] }, "description": "Printers in this group with CloudPRNT URLs" } }, "required": [ "id", "locationId", "createdAt", "updatedAt", "printers" ] } }, "required": [ "printerGroup" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printer-groups/{printerGroupId}": { "get": { "tags": [ "Printers" ], "description": "Get a printer group by ID with its printers and CloudPRNT URLs", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerGroupId", "required": true, "description": "Printer Group UUID" } ], "responses": { "200": { "description": "Successfully retrieved printer group", "content": { "application/json": { "schema": { "description": "Successfully retrieved printer group", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "printerGroup": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer group identifier" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer group" }, "type": { "type": "string", "nullable": true, "description": "Type of the printer group" }, "color": { "type": "string", "nullable": true, "description": "Color for the printer group (hex code, e.g. #FF5733). Null renders as gray." }, "defaultItemState": { "type": "string", "nullable": true, "enum": [ "pending", "accepted", "ready_to_deliver", null ], "description": "Default item state for orders routed to this prep group. Null means use location/system default." }, "locationId": { "type": "integer", "description": "Location ID where the printer group is configured" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer group was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer group was last updated" }, "metaData": { "type": "object", "nullable": true, "properties": { "fontSize": { "type": "string", "nullable": true, "description": "Font size setting for receipts" }, "logotypeUrl": { "type": "string", "nullable": true, "description": "URL of the logo to print on receipts" }, "message": { "type": "string", "nullable": true, "description": "Custom message to print on receipts" }, "displayPayQRProforma": { "type": "boolean", "nullable": true, "description": "Whether to display payment QR code on proforma" }, "displayOrderQRReciept": { "type": "boolean", "nullable": true, "description": "Whether to display order QR code on receipt" } } }, "printers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer identifier" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility." }, "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Primary prep group memberships — the printer prints these groups' items via the flow engine." }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Secondary (\"ride-along\") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own." }, "locationId": { "type": "integer", "description": "Location ID where the printer is installed" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer (from printer group)" }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "nullable": true, "description": "Hardware type of the printer" }, "status": { "type": "string", "nullable": true, "description": "Last reported status code from the printer" }, "state": { "type": "string", "enum": [ "online", "offline" ], "description": "Current state of the printer (online if both printer is online and group is published)" }, "idle": { "type": "boolean", "nullable": true, "description": "Whether the printer is currently idle (not processing jobs)" }, "cloudPrntUrl": { "type": "string", "format": "uri", "description": "CloudPRNT polling URL to configure on the physical printer", "example": "https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer was last updated" } }, "required": [ "id", "locationId", "state", "cloudPrntUrl", "createdAt", "updatedAt" ] }, "description": "Printers in this group with CloudPRNT URLs" } }, "required": [ "id", "locationId", "createdAt", "updatedAt", "printers" ] } }, "required": [ "printerGroup" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "tags": [ "Printers" ], "description": "Update a printer group (prep group) name", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the printer group" }, "color": { "type": "string", "nullable": true, "description": "Color for the printer group (hex code, e.g. #FF5733). Set to null to remove." }, "defaultItemState": { "type": "string", "nullable": true, "enum": [ "pending", "accepted", "ready_to_deliver", null ], "description": "Default item state for orders routed to this prep group. Set to null to use location/system default." } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerGroupId", "required": true, "description": "Printer Group UUID" } ], "responses": { "200": { "description": "Successfully updated printer group", "content": { "application/json": { "schema": { "description": "Successfully updated printer group", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "printerGroup": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer group identifier" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer group" }, "type": { "type": "string", "nullable": true, "description": "Type of the printer group" }, "color": { "type": "string", "nullable": true, "description": "Color for the printer group (hex code, e.g. #FF5733). Null renders as gray." }, "defaultItemState": { "type": "string", "nullable": true, "enum": [ "pending", "accepted", "ready_to_deliver", null ], "description": "Default item state for orders routed to this prep group. Null means use location/system default." }, "locationId": { "type": "integer", "description": "Location ID where the printer group is configured" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer group was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer group was last updated" }, "metaData": { "type": "object", "nullable": true, "properties": { "fontSize": { "type": "string", "nullable": true, "description": "Font size setting for receipts" }, "logotypeUrl": { "type": "string", "nullable": true, "description": "URL of the logo to print on receipts" }, "message": { "type": "string", "nullable": true, "description": "Custom message to print on receipts" }, "displayPayQRProforma": { "type": "boolean", "nullable": true, "description": "Whether to display payment QR code on proforma" }, "displayOrderQRReciept": { "type": "boolean", "nullable": true, "description": "Whether to display order QR code on receipt" } } }, "printers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer identifier" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility." }, "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Primary prep group memberships — the printer prints these groups' items via the flow engine." }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Secondary (\"ride-along\") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own." }, "locationId": { "type": "integer", "description": "Location ID where the printer is installed" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer (from printer group)" }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "nullable": true, "description": "Hardware type of the printer" }, "status": { "type": "string", "nullable": true, "description": "Last reported status code from the printer" }, "state": { "type": "string", "enum": [ "online", "offline" ], "description": "Current state of the printer (online if both printer is online and group is published)" }, "idle": { "type": "boolean", "nullable": true, "description": "Whether the printer is currently idle (not processing jobs)" }, "cloudPrntUrl": { "type": "string", "format": "uri", "description": "CloudPRNT polling URL to configure on the physical printer", "example": "https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer was last updated" } }, "required": [ "id", "locationId", "state", "cloudPrntUrl", "createdAt", "updatedAt" ] }, "description": "Printers in this group with CloudPRNT URLs" } }, "required": [ "id", "locationId", "createdAt", "updatedAt", "printers" ] } }, "required": [ "printerGroup" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "tags": [ "Printers" ], "description": "Delete a printer group (prep group) and all its printers", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerGroupId", "required": true, "description": "Printer Group UUID" } ], "responses": { "200": { "description": "Successfully deleted printer group", "content": { "application/json": { "schema": { "description": "Successfully deleted printer group", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printer-groups/{printerGroupId}/events": { "get": { "tags": [ "Printers" ], "description": "List events for a printer group", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Number of events to return" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Offset for pagination" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerGroupId", "required": true, "description": "Printer Group UUID" } ], "responses": { "200": { "description": "Successfully retrieved printer events", "content": { "application/json": { "schema": { "description": "Successfully retrieved printer events", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "printerId": { "type": "string", "nullable": true }, "printerGroupId": { "type": "string", "format": "uuid" }, "printerGroupName": { "type": "string", "nullable": true }, "eventType": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "nullable": true } } } }, "totalCount": { "type": "integer" } }, "required": [ "events", "totalCount" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printer-groups/{printerGroupId}/jobs": { "get": { "tags": [ "Printers" ], "description": "List print jobs for a printer group", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Number of jobs to return" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Offset for pagination" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Filter jobs created at or after this ISO 8601 datetime" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "Filter jobs created at or before this ISO 8601 datetime" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerGroupId", "required": true, "description": "Printer Group UUID" } ], "responses": { "200": { "description": "Successfully retrieved print jobs", "content": { "application/json": { "schema": { "description": "Successfully retrieved print jobs", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "printerGroupId": { "type": "string", "format": "uuid" }, "printerGroupName": { "type": "string", "nullable": true }, "claimedByPrinter": { "type": "string", "nullable": true }, "status": { "type": "string" }, "retries": { "type": "integer" }, "metadata": { "type": "object", "nullable": true }, "content": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "totalCount": { "type": "integer" } }, "required": [ "jobs", "totalCount" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printer-groups/{printerGroupId}/jobs/{jobId}": { "get": { "tags": [ "Printers" ], "description": "Get a single print job by ID with its events timeline", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerGroupId", "required": true, "description": "Printer Group UUID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "jobId", "required": true, "description": "Print Job UUID" } ], "responses": { "200": { "description": "Successfully retrieved print job with events", "content": { "application/json": { "schema": { "description": "Successfully retrieved print job with events", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "printerGroupId": { "type": "string", "format": "uuid" }, "printerGroupName": { "type": "string", "nullable": true }, "claimedByPrinter": { "type": "string", "nullable": true }, "status": { "type": "string" }, "retries": { "type": "integer" }, "metadata": { "type": "object", "nullable": true }, "content": { "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventType": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "printerId": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true } } } } } } }, "required": [ "job" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printer-groups/{printerGroupId}/printers": { "post": { "tags": [ "Printers" ], "description": "Add a printer to an existing printer group", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "description": "Hardware type of the printer" }, "terminalId": { "type": "string", "format": "uuid", "description": "Terminal ID for terminal printers (v400m, v400cplus, s1f2)" } }, "required": [ "type" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerGroupId", "required": true, "description": "Printer Group UUID" } ], "responses": { "201": { "description": "Successfully added printer to group", "content": { "application/json": { "schema": { "description": "Successfully added printer to group", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "printer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer identifier" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility." }, "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Primary prep group memberships — the printer prints these groups' items via the flow engine." }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Secondary (\"ride-along\") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own." }, "locationId": { "type": "integer", "description": "Location ID where the printer is installed" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer (from printer group)" }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "nullable": true, "description": "Hardware type of the printer" }, "status": { "type": "string", "nullable": true, "description": "Last reported status code from the printer" }, "state": { "type": "string", "enum": [ "online", "offline" ], "description": "Current state of the printer (online if both printer is online and group is published)" }, "idle": { "type": "boolean", "nullable": true, "description": "Whether the printer is currently idle (not processing jobs)" }, "cloudPrntUrl": { "type": "string", "format": "uri", "description": "CloudPRNT polling URL to configure on the physical printer", "example": "https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer was last updated" } }, "required": [ "id", "locationId", "state", "cloudPrntUrl", "createdAt", "updatedAt" ] } }, "required": [ "printer" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printers": { "get": { "tags": [ "Printers" ], "description": "List all printers for a location with CloudPRNT URLs", "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "locationId", "required": false, "description": "Location ID to filter printers. If not provided, uses X-Location-Id header or default location." } ], "responses": { "200": { "description": "Successfully retrieved printers", "content": { "application/json": { "schema": { "description": "Successfully retrieved printers", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "printers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer identifier" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility." }, "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Primary prep group memberships — the printer prints these groups' items via the flow engine." }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Secondary (\"ride-along\") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own." }, "locationId": { "type": "integer", "description": "Location ID where the printer is installed" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer (from printer group)" }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "nullable": true, "description": "Hardware type of the printer" }, "status": { "type": "string", "nullable": true, "description": "Last reported status code from the printer" }, "state": { "type": "string", "enum": [ "online", "offline" ], "description": "Current state of the printer (online if both printer is online and group is published)" }, "idle": { "type": "boolean", "nullable": true, "description": "Whether the printer is currently idle (not processing jobs)" }, "cloudPrntUrl": { "type": "string", "format": "uri", "description": "CloudPRNT polling URL to configure on the physical printer", "example": "https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer was last updated" } }, "required": [ "id", "locationId", "state", "cloudPrntUrl", "createdAt", "updatedAt" ] } }, "total": { "type": "integer", "description": "Total number of printers" } }, "required": [ "printers", "total" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "tags": [ "Printers" ], "description": "Create a new printer (optionally assign to a printer group)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional ID of the printer group to add this printer to. If not provided, printer will be created without a group (storage state)." }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "description": "Printer hardware model/type" }, "name": { "type": "string", "description": "Optional name for the printer" }, "terminalId": { "type": "string", "format": "uuid", "description": "Terminal ID for terminal printers (v400m, v400cplus, s1f2)" } }, "required": [ "type" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "locationId", "required": false, "description": "Location ID. If not provided, uses X-Location-Id header or default location." } ], "responses": { "201": { "description": "Successfully created printer", "content": { "application/json": { "schema": { "description": "Successfully created printer", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "printer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer identifier" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility." }, "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Primary prep group memberships — the printer prints these groups' items via the flow engine." }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Secondary (\"ride-along\") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own." }, "locationId": { "type": "integer", "description": "Location ID where the printer is installed" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer (from printer group)" }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "nullable": true, "description": "Hardware type of the printer" }, "status": { "type": "string", "nullable": true, "description": "Last reported status code from the printer" }, "state": { "type": "string", "enum": [ "online", "offline" ], "description": "Current state of the printer (online if both printer is online and group is published)" }, "idle": { "type": "boolean", "nullable": true, "description": "Whether the printer is currently idle (not processing jobs)" }, "cloudPrntUrl": { "type": "string", "format": "uri", "description": "CloudPRNT polling URL to configure on the physical printer", "example": "https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer was last updated" } }, "required": [ "id", "locationId", "state", "cloudPrntUrl", "createdAt", "updatedAt" ] } }, "required": [ "printer" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printers/{printerId}": { "get": { "tags": [ "Printers" ], "description": "Get a single printer by ID", "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "locationId", "required": false, "description": "Location ID for access verification. If not provided, uses X-Location-Id header or default location." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerId", "required": true, "description": "Printer UUID" } ], "responses": { "200": { "description": "Successfully retrieved printer", "content": { "application/json": { "schema": { "description": "Successfully retrieved printer", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "printer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer identifier" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility." }, "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Primary prep group memberships — the printer prints these groups' items via the flow engine." }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Secondary (\"ride-along\") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own." }, "locationId": { "type": "integer", "description": "Location ID where the printer is installed" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer (from printer group)" }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "nullable": true, "description": "Hardware type of the printer" }, "status": { "type": "string", "nullable": true, "description": "Last reported status code from the printer" }, "state": { "type": "string", "enum": [ "online", "offline" ], "description": "Current state of the printer (online if both printer is online and group is published)" }, "idle": { "type": "boolean", "nullable": true, "description": "Whether the printer is currently idle (not processing jobs)" }, "cloudPrntUrl": { "type": "string", "format": "uri", "description": "CloudPRNT polling URL to configure on the physical printer", "example": "https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer was last updated" } }, "required": [ "id", "locationId", "state", "cloudPrntUrl", "createdAt", "updatedAt" ] } }, "required": [ "printer" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "tags": [ "Printers" ], "description": "Update a printer (e.g. reassign to a different printer group)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the printer" }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "description": "Printer hardware model/type" }, "printerGroupId": { "type": "string", "format": "uuid", "description": "ID of the printer group to assign this printer to" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerId", "required": true, "description": "Printer UUID" } ], "responses": { "200": { "description": "Successfully updated printer", "content": { "application/json": { "schema": { "description": "Successfully updated printer", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "printer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique printer identifier" }, "printerGroupId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility." }, "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Primary prep group memberships — the printer prints these groups' items via the flow engine." }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Secondary (\"ride-along\") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own." }, "locationId": { "type": "integer", "description": "Location ID where the printer is installed" }, "name": { "type": "string", "nullable": true, "description": "Name of the printer (from printer group)" }, "type": { "type": "string", "enum": [ "tsp654", "tsp100", "any", "v400m", "v400cplus", "s1f2", "mcprint3" ], "nullable": true, "description": "Hardware type of the printer" }, "status": { "type": "string", "nullable": true, "description": "Last reported status code from the printer" }, "state": { "type": "string", "enum": [ "online", "offline" ], "description": "Current state of the printer (online if both printer is online and group is published)" }, "idle": { "type": "boolean", "nullable": true, "description": "Whether the printer is currently idle (not processing jobs)" }, "cloudPrntUrl": { "type": "string", "format": "uri", "description": "CloudPRNT polling URL to configure on the physical printer", "example": "https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the printer was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the printer was last updated" } }, "required": [ "id", "locationId", "state", "cloudPrntUrl", "createdAt", "updatedAt" ] } }, "required": [ "printer" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "tags": [ "Printers" ], "description": "Delete a printer", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerId", "required": true, "description": "Printer UUID" } ], "responses": { "200": { "description": "Successfully deleted printer", "content": { "application/json": { "schema": { "description": "Successfully deleted printer", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printers/{printerId}/events": { "get": { "tags": [ "Printers" ], "description": "List events for a single printer (online, offline, created, deleted)", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Number of events to return" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Offset for pagination" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerId", "required": true, "description": "Printer UUID" } ], "responses": { "200": { "description": "Successfully retrieved printer events", "content": { "application/json": { "schema": { "description": "Successfully retrieved printer events", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "printerId": { "type": "string", "nullable": true }, "printerGroupId": { "type": "string", "format": "uuid" }, "printerGroupName": { "type": "string", "nullable": true }, "eventType": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "nullable": true } } } }, "totalCount": { "type": "integer" } }, "required": [ "events", "totalCount" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printers/{printerId}/groups": { "put": { "tags": [ "Printers" ], "description": "Set which printer groups a printer belongs to (replaces all memberships)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Primary prep group UUIDs the printer prints for. Empty array removes all primary memberships." }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional. Prep groups this printer is a ride-along (\"secondary\") member of. When the printer fires a primary print, items from these groups in the same kitchen dispatch are appended in smaller font. Secondary memberships never trigger a print on their own and may not overlap with primary IDs." } }, "required": [ "printerGroupIds" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerId", "required": true, "description": "Printer UUID" } ], "responses": { "200": { "description": "Successfully set printer groups", "content": { "application/json": { "schema": { "description": "Successfully set printer groups", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "printerId": { "type": "string", "format": "uuid" }, "printerGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "secondaryPrinterGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "printerId", "printerGroupIds" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/printers/{printerId}/groups/{printerGroupId}": { "delete": { "tags": [ "Printers" ], "description": "Remove a printer from a specific printer group", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerId", "required": true, "description": "Printer UUID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "printerGroupId", "required": true, "description": "Printer Group UUID to remove the printer from" } ], "responses": { "200": { "description": "Successfully removed printer from group", "content": { "application/json": { "schema": { "description": "Successfully removed printer from group", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/public/orders/create": { "post": { "tags": [ "Public" ], "description": "Creates an order at a location. A new tab is opened per call unless an existing destination is provided. Optionally associate the order with a guest via user_id, email, or phone.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "location_id", "items" ], "properties": { "location_id": { "type": "number", "description": "Location to place the order at" }, "ordering_member": { "type": "object", "description": "Optional guest identification. Provide one of user_id, email, or phone. If omitted, an anonymous guest is created for this order.", "properties": { "user_id": { "type": "number", "description": "Karma user ID" }, "email": { "type": "string", "format": "email", "description": "Guest email" }, "phone": { "type": "string", "description": "Guest phone number" }, "name": { "type": "string", "description": "Display name for new guests" } } }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "quantity_cents" ], "properties": { "id": { "type": "number", "description": "Inventory item ID" }, "quantity_cents": { "type": "number", "minimum": 1, "description": "Quantity in cents (100 = 1 unit, 50 = half)" }, "variants": { "type": "array", "description": "Optional variants to apply (e.g. size, milk type)", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "number", "description": "Variant ID" }, "quantity_cents": { "type": "number", "description": "Quantity in cents (100 = 1 unit, 50 = 0.5). Defaults to 100." } } } }, "price_cents": { "type": "number", "description": "Optional price override in cents. Defaults to the item's configured price." }, "coursing_order": { "type": "number", "description": "Optional coursing order (0 = send immediately). Omit to use default." } } } }, "vouchers": { "type": "array", "description": "Optional voucher codes to apply to the order", "items": { "type": "string" } }, "order_destination": { "type": "string", "enum": [ "NONE", "TAB", "QR", "KD" ], "default": "NONE", "description": "Where to attach the order. NONE creates a fresh tab. TAB/QR/KD attach to an existing destination identified by order_destination_id." }, "order_destination_id": { "type": "string", "description": "UUID of the destination tab, QR code, or kitchen dispatch. Required when order_destination is not NONE." }, "order_type": { "type": "string", "enum": [ "TAKEAWAY", "OTC", "TABLE" ], "default": "OTC", "description": "Fulfillment type. Defaults to OTC (over the counter)." } } } } }, "required": true }, "responses": { "201": { "description": "Order created", "content": { "application/json": { "schema": { "description": "Order created", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Kitchen dispatch UUID" }, "tabId": { "type": "string", "description": "Tab UUID" }, "totalAmountCents": { "type": "number", "description": "Order total in cents" } } } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchase/lookup-session/{sessionId}": { "get": { "tags": [ "Purchases" ], "description": "Look up purchase intent ID by Adyen session ID (stored in psp_request_ref). Used when Adyen redirects back with sessionId but no purchaseIntentId in URL.\n\n**Permissions:** 🔵 `purchases.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID for permission validation" }, { "schema": { "type": "string" }, "in": "path", "name": "sessionId", "required": true, "description": "Adyen session ID (psp_request_ref)" } ], "responses": { "200": { "description": "Purchase intent found for session", "content": { "application/json": { "schema": { "description": "Purchase intent found for session", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchaseIntentId": { "type": "string", "format": "uuid", "description": "Purchase intent UUID" }, "locationId": { "type": "number", "description": "Location ID" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases": { "get": { "tags": [ "Purchases" ], "description": "List purchases with automatic BigQuery routing for historical data", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID to filter purchases (required for permissions)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Start date for date range filter (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "End date for date range filter (ISO 8601)" }, { "schema": { "type": "number" }, "in": "query", "name": "userId", "required": false, "description": "Filter by user ID" }, { "schema": { "type": "number" }, "in": "query", "name": "minAmount", "required": false, "description": "Minimum amount in cents" }, { "schema": { "type": "number" }, "in": "query", "name": "maxAmount", "required": false, "description": "Maximum amount in cents" }, { "schema": { "type": "number" }, "in": "query", "name": "minRefundedAmount", "required": false, "description": "Minimum refunded amount in cents" }, { "schema": { "type": "number" }, "in": "query", "name": "maxRefundedAmount", "required": false, "description": "Maximum refunded amount in cents" }, { "schema": { "type": "string" }, "in": "query", "name": "paymentMethod", "required": false, "description": "Filter by payment method" }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false, "description": "Filter by payment status" }, { "schema": { "type": "string" }, "in": "query", "name": "customerEmail", "required": false, "description": "Filter by customer email (partial match)" }, { "schema": { "type": "number" }, "in": "query", "name": "itemId", "required": false, "description": "Filter purchases containing a specific inventory item ID" }, { "schema": { "type": "string" }, "in": "query", "name": "tableId", "required": false, "description": "Filter by table/storefront QR code UUID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "tabId", "required": false, "description": "Filter by tab UUID" }, { "schema": { "type": "string" }, "in": "query", "name": "tabType", "required": false, "description": "Filter by tab type (comma-separated: takeaway, over_the_counter, table)" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number for pagination" }, { "schema": { "type": "number", "minimum": 1, "maximum": 1000, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Number of results per page (max 1000)" } ], "responses": { "200": { "description": "Purchases retrieved successfully", "content": { "application/json": { "schema": { "description": "Purchases retrieved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Purchase ID" }, "locationId": { "type": "number", "description": "Location ID" }, "userId": { "type": "number", "nullable": true, "description": "User ID who made the purchase" }, "amount": { "type": "number", "description": "Total amount in cents" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, EUR)" }, "paymentMethod": { "type": "string", "nullable": true, "description": "Payment method used" }, "paymentProvider": { "type": "string", "nullable": true, "description": "Payment provider (e.g., stripe, adyen)" }, "status": { "type": "string", "description": "Payment status (pending, completed, failed, etc.)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "tabId": { "type": "string", "nullable": true, "format": "uuid", "description": "Tab ID if part of a tab" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Line item ID" }, "inventoryItemId": { "type": "number", "description": "Inventory item ID" }, "quantityCents": { "type": "number", "description": "Quantity in cents (100 = 1x)" }, "unitPriceCents": { "type": "number", "description": "Price per unit in cents" }, "totalPriceCents": { "type": "number", "description": "Total price in cents" }, "title": { "type": "string", "description": "Item title" }, "category": { "type": "string", "nullable": true, "description": "Item category" }, "channel": { "type": "string", "nullable": true, "description": "Order channel (POS, KIOSK, QR, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM)", "enum": [ "POS", "KIOSK", "QR", "ONLINE", "TAKEAWAY", "MOVE", "MERGE", "SPLIT", "SYSTEM" ] }, "isTakeaway": { "type": "boolean", "description": "Whether this specific item is takeaway (can differ from the tab-level tabType)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } } }, "description": "Purchased items" }, "metadata": { "type": "object", "nullable": true, "description": "Additional metadata", "additionalProperties": true } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases/{id}": { "get": { "tags": [ "Purchases" ], "description": "Get a single purchase by ID", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID for permission validation" }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Purchase ID" } ], "responses": { "200": { "description": "Purchase retrieved successfully", "content": { "application/json": { "schema": { "description": "Purchase retrieved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "id": { "type": "number", "description": "Purchase ID" }, "locationId": { "type": "number", "description": "Location ID" }, "userId": { "type": "number", "nullable": true, "description": "User ID who made the purchase" }, "amount": { "type": "number", "description": "Total amount in cents" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, EUR)" }, "paymentMethod": { "type": "string", "nullable": true, "description": "Payment method used" }, "paymentProvider": { "type": "string", "nullable": true, "description": "Payment provider (e.g., stripe, adyen)" }, "status": { "type": "string", "description": "Payment status (pending, completed, failed, etc.)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "tabId": { "type": "string", "nullable": true, "format": "uuid", "description": "Tab ID if part of a tab" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Line item ID" }, "inventoryItemId": { "type": "number", "description": "Inventory item ID" }, "quantityCents": { "type": "number", "description": "Quantity in cents (100 = 1x)" }, "unitPriceCents": { "type": "number", "description": "Price per unit in cents" }, "totalPriceCents": { "type": "number", "description": "Total price in cents" }, "title": { "type": "string", "description": "Item title" }, "category": { "type": "string", "nullable": true, "description": "Item category" }, "channel": { "type": "string", "nullable": true, "description": "Order channel (POS, KIOSK, QR, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM)", "enum": [ "POS", "KIOSK", "QR", "ONLINE", "TAKEAWAY", "MOVE", "MERGE", "SPLIT", "SYSTEM" ] }, "isTakeaway": { "type": "boolean", "description": "Whether this specific item is takeaway (can differ from the tab-level tabType)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } } }, "description": "Purchased items" }, "metadata": { "type": "object", "nullable": true, "description": "Additional metadata", "additionalProperties": true } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases/{purchaseIntentId}/cash-register/fetch": { "post": { "tags": [ "Purchases" ], "description": "Fetch cash register info from cash-register service for a purchase that has a receipt ID but missing other cash register fields. Used to backfill data for older purchases.\n\n**Permissions:** ⚪ `purchases.write`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID for permission validation" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "purchaseIntentId", "required": true, "description": "Purchase intent UUID" } ], "responses": { "200": { "description": "Cash register info fetched successfully", "content": { "application/json": { "schema": { "description": "Cash register info fetched successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchaseIntentId": { "type": "string", "format": "uuid" }, "cashRegister": { "type": "object", "nullable": true, "description": "Cash register receipt data (SKV required fields). Null if not registered with cash register.", "properties": { "receiptNumber": { "type": "number", "description": "Löpnummer - running receipt number from unbroken ascending series" }, "registerId": { "type": "string", "description": "Kassabeteckning - cash register designation/ID" }, "controlUnit": { "type": "string", "nullable": true, "description": "Kontrollenhetens tillverkningsnummer - control unit serial number" } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases/{purchaseIntentId}/cash-register/register": { "post": { "tags": [ "Purchases" ], "description": "Register a purchase with the cash register service (efterregistrering). Used for purchases that were not registered at the time of payment. Location must have an active cash register configuration.\n\n**Permissions:** ⚪ `purchases.write`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID for permission validation" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "purchaseIntentId", "required": true, "description": "Purchase intent UUID" } ], "responses": { "200": { "description": "Purchase registered with cash register successfully", "content": { "application/json": { "schema": { "description": "Purchase registered with cash register successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchaseIntentId": { "type": "string", "format": "uuid" }, "cashRegister": { "type": "object", "nullable": true, "description": "Cash register receipt data (SKV required fields). Null if not registered with cash register.", "properties": { "receiptNumber": { "type": "number", "description": "Löpnummer - running receipt number from unbroken ascending series" }, "registerId": { "type": "string", "description": "Kassabeteckning - cash register designation/ID" }, "controlUnit": { "type": "string", "nullable": true, "description": "Kontrollenhetens tillverkningsnummer - control unit serial number" } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases/{purchaseIntentId}/connect-customer": { "post": { "tags": [ "Purchases" ], "description": "Connect a customer to a purchase by email. Optionally enroll in loyalty and award retroactive points.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Customer email address (used to find or create user)" }, "name": { "type": "string", "description": "Customer name (optional, used to update user profile)" }, "phone": { "type": "string", "description": "Customer phone number (optional)" }, "enrollInLoyalty": { "type": "boolean", "description": "Enroll customer in location loyalty program and award retroactive points" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID for permission validation" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "purchaseIntentId", "required": true, "description": "Purchase intent UUID" } ], "responses": { "200": { "description": "Customer connected successfully", "content": { "application/json": { "schema": { "description": "Customer connected successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the connection was successful" }, "userId": { "type": "number", "description": "The user ID of the connected customer" }, "isNewUser": { "type": "boolean", "description": "Whether a new user was created" }, "loyaltyEnrolled": { "type": "boolean", "description": "Whether the user was enrolled in loyalty program" }, "pointsAwarded": { "type": "number", "description": "Total loyalty points awarded (welcome + purchase)" }, "message": { "type": "string", "description": "Human-readable result message" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases/{purchaseIntentId}/email-receipt": { "post": { "tags": [ "Purchases" ], "description": "Send a receipt email copy to a specified email address.\n\nValidates the purchase is confirmed, then triggers the receipt email Cloud Function via PubSub.\nThe email uses the same template as automatic storefront receipt emails.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address to send the receipt to" } }, "required": [ "email" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "purchaseIntentId", "required": true, "description": "The purchase intent ID" } ], "responses": { "202": { "description": "Receipt email send initiated", "content": { "application/json": { "schema": { "description": "Receipt email send initiated", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchaseIntentId": { "type": "string", "format": "uuid" }, "email": { "type": "string" } }, "required": [ "purchaseIntentId", "email" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases/{purchaseIntentId}/order-details": { "get": { "tags": [ "Purchases" ], "description": "Get unified order purchase details by purchase intent ID (matches storefront-web format)", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID for permission validation" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "purchaseIntentId", "required": true, "description": "Purchase intent UUID" } ], "responses": { "200": { "description": "Order purchase details retrieved successfully", "content": { "application/json": { "schema": { "description": "Order purchase details retrieved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "orderInfo": { "type": "object", "nullable": true, "properties": { "orderState": { "type": "string", "enum": [ "initial", "sent_to_kitchen", "accepted", "ready_to_deliver", "delivered", "cancelled" ], "description": "Current order state" }, "deliveryKind": { "type": "string", "enum": [ "takeaway", "table", "room" ], "nullable": true, "description": "Order delivery type" }, "orderNumber": { "type": "number", "nullable": true, "description": "Daily order number for kitchen display" }, "tableName": { "type": "string", "nullable": true, "description": "Table name if order is for table service" }, "paymentFlow": { "type": "string", "enum": [ "instant", "open_tab" ], "nullable": true, "description": "Payment timing (instant = pay now, open_tab = pay later)" }, "tabId": { "type": "string", "format": "uuid", "nullable": true, "description": "Tab UUID if order is part of a tab" }, "hasBeenScheduled": { "type": "boolean", "description": "Whether order has been scheduled for future preparation" }, "desiredPickupTime": { "type": "number", "nullable": true, "description": "Desired pickup time (Unix timestamp)" }, "phoneNumber": { "type": "string", "nullable": true, "description": "Customer phone number" } } }, "purchaseInfo": { "type": "object", "nullable": true, "properties": { "purchasedAtEpochSeconds": { "type": "number", "description": "Purchase timestamp (Unix seconds)" }, "totalAmountCents": { "type": "number", "nullable": true, "description": "Total purchase amount in cents (from purchases.amount_cents)" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "product", "tip" ], "description": "Line item type" }, "title": { "type": "string", "description": "Item title" }, "amountCents": { "type": "number", "description": "Total item amount in cents" }, "appliedTotalDiscountAmountCents": { "type": "number", "nullable": true, "description": "Total discount applied to this line item in cents" }, "quantity": { "type": "number", "description": "Quantity of this item" }, "appliedModifications": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Modification name (e.g., \"Extra cheese\")" }, "priceAdjustmentCents": { "type": "number", "description": "Price adjustment in cents (positive for surcharge, negative for discount)" } } }, "description": "Applied modifications (extras, options, etc.)" } } }, "description": "Purchased items with quantities and modifications" }, "vatBreakdown": { "type": "object", "properties": { "vatPercentage": { "type": "number", "description": "VAT percentage (e.g., 12 for 12%)" }, "vatAmountCents": { "type": "number", "description": "VAT amount in cents" }, "netAmountCents": { "type": "number", "description": "Net amount (excluding VAT) in cents" }, "grossAmountCents": { "type": "number", "description": "Gross amount (including VAT) in cents" } }, "description": "VAT calculation breakdown" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, EUR)" } } }, "tabInfo": { "type": "object", "nullable": true, "properties": { "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "remainingAmountCents": { "type": "number", "nullable": true, "description": "Remaining unpaid amount on the tab in cents" }, "qrCodeId": { "type": "string", "format": "uuid", "nullable": true, "description": "QR code UUID associated with this tab" } } } }, "description": "Unified order purchase data (matches storefront-service response format)" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases/{purchaseIntentId}/receipt": { "get": { "tags": [ "Purchases" ], "description": "Get receipt data for email generation with hierarchical line items", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID for permission validation" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "purchaseIntentId", "required": true, "description": "Purchase intent UUID" } ], "responses": { "200": { "description": "Receipt email data retrieved successfully", "content": { "application/json": { "schema": { "description": "Receipt email data retrieved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchaseIntentId": { "type": "string", "format": "uuid", "description": "Purchase intent UUID" }, "purchasedAt": { "type": "string", "format": "date-time", "description": "Purchase timestamp" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK)" }, "orderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "location": { "type": "object", "properties": { "name": { "type": "string", "description": "Location/restaurant name" }, "address": { "type": "string", "nullable": true, "description": "Full address" }, "phone": { "type": "string", "nullable": true, "description": "Contact phone number" }, "vatId": { "type": "string", "nullable": true, "description": "Organization number (organisationsnummer)" }, "logoUrl": { "type": "string", "nullable": true, "description": "Location logo URL" }, "storefrontSlug": { "type": "string", "nullable": true, "description": "Storefront URL slug" }, "language": { "type": "string", "nullable": true, "description": "Location language code (e.g. sv, en, no)" } } }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "product", "tip" ], "description": "Item type" }, "title": { "type": "string", "description": "Item title" }, "quantity": { "type": "number", "description": "Quantity" }, "unitPriceCents": { "type": "number", "description": "Unit price in cents" }, "totalPriceCents": { "type": "number", "description": "Total price including children in cents" }, "appliedDiscountCents": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "appliedModifications": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Modification name (e.g., \"Extra cheese\")" }, "priceAdjustmentCents": { "type": "number", "description": "Price adjustment in cents" } } }, "description": "Applied modifications (extras, sizes, etc.)" }, "children": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Child item title" }, "quantity": { "type": "number", "description": "Quantity" }, "unitPriceCents": { "type": "number", "nullable": true, "description": "Unit price in cents (null for zero-priced included variants)" }, "totalPriceCents": { "type": "number", "nullable": true, "description": "Total price in cents (null for zero-priced included variants)" }, "appliedModifications": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Modification name (e.g., \"Extra cheese\")" }, "priceAdjustmentCents": { "type": "number", "description": "Price adjustment in cents" } } }, "description": "Applied modifications" } } }, "description": "Child items (product variants, bundle items)" } } }, "description": "Hierarchical line items with children" }, "subtotalCents": { "type": "number", "description": "Subtotal before VAT in cents" }, "totalDiscountCents": { "type": "number", "description": "Total discounts in cents" }, "vatBreakdown": { "type": "array", "items": { "type": "object", "properties": { "rate": { "type": "number", "description": "VAT rate percentage (e.g., 12, 25)" }, "baseAmountCents": { "type": "number", "description": "Base amount before VAT in cents" }, "vatAmountCents": { "type": "number", "description": "VAT amount in cents" } } }, "description": "VAT breakdown by rate" }, "totalCents": { "type": "number", "description": "Total amount in cents" }, "appliedVouchers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Voucher code" }, "appliedAmountCents": { "type": "number", "description": "Amount discounted in cents" } } }, "description": "Applied vouchers/discounts" }, "customerEmail": { "type": "string", "nullable": true, "description": "Customer email address" }, "paymentMethod": { "type": "string", "nullable": true, "description": "Payment method (e.g., \"visa 4242\")" }, "paymentBrand": { "type": "string", "nullable": true, "description": "Payment brand (e.g., \"visa\")" }, "paymentLast4": { "type": "string", "nullable": true, "description": "Last 4 digits of card" }, "tableName": { "type": "string", "nullable": true, "description": "Table name if applicable" }, "deliveryKind": { "type": "string", "nullable": true, "description": "Delivery type (takeaway, table, counter)" }, "cashRegister": { "type": "object", "nullable": true, "description": "Cash register receipt data (SKV required fields). Null if not registered with cash register.", "properties": { "receiptNumber": { "type": "number", "description": "Löpnummer - running receipt number from unbroken ascending series" }, "registerId": { "type": "string", "description": "Kassabeteckning - cash register designation/ID" }, "controlUnit": { "type": "string", "nullable": true, "description": "Kontrollenhetens tillverkningsnummer - control unit serial number" } } } }, "description": "Receipt email data with hierarchical line items" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases/{purchaseIntentId}/receipt/print": { "get": { "tags": [ "Purchases" ], "description": "Render a purchase receipt as Adyen terminal OutputText for printing. Proxies to printer-service.\n\n**Permissions:** 🔵 `purchases.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID for permission validation" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "purchaseIntentId", "required": true, "description": "Purchase intent UUID" } ], "responses": { "200": { "description": "Adyen OutputText payload ready to ship in a Nexo PrintRequest envelope", "content": { "application/json": { "schema": { "description": "Adyen OutputText payload ready to ship in a Nexo PrintRequest envelope", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "outputText": { "type": "array", "description": "Ordered list of Nexo OutputText lines.", "items": { "type": "object", "properties": { "Text": { "type": "string" }, "CharacterStyle": { "type": "string", "enum": [ "Bold", "Normal" ] }, "Alignment": { "type": "string", "enum": [ "Left", "Centred", "Right" ] }, "EndOfLineFlag": { "type": "boolean" } }, "required": [ "Text" ] } }, "qrCode": { "type": "object", "nullable": true, "description": "Optional QR follow-up. Print as a separate Nexo envelope after the text slip.", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } }, "required": [ "outputText" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/purchases/by-intent/{intentId}": { "get": { "tags": [ "Purchases" ], "description": "Get a single purchase by intent ID (UUID)", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID for permission validation" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "intentId", "required": true, "description": "Purchase intent ID (UUID)" } ], "responses": { "200": { "description": "Purchase retrieved successfully", "content": { "application/json": { "schema": { "description": "Purchase retrieved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "id": { "type": "number", "description": "Purchase ID" }, "locationId": { "type": "number", "description": "Location ID" }, "userId": { "type": "number", "nullable": true, "description": "User ID who made the purchase" }, "amount": { "type": "number", "description": "Total amount in cents" }, "currency": { "type": "string", "description": "Currency code (e.g., SEK, EUR)" }, "paymentMethod": { "type": "string", "nullable": true, "description": "Payment method used" }, "paymentProvider": { "type": "string", "nullable": true, "description": "Payment provider (e.g., stripe, adyen)" }, "status": { "type": "string", "description": "Payment status (pending, completed, failed, etc.)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "tabId": { "type": "string", "nullable": true, "format": "uuid", "description": "Tab ID if part of a tab" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Line item ID" }, "inventoryItemId": { "type": "number", "description": "Inventory item ID" }, "quantityCents": { "type": "number", "description": "Quantity in cents (100 = 1x)" }, "unitPriceCents": { "type": "number", "description": "Price per unit in cents" }, "totalPriceCents": { "type": "number", "description": "Total price in cents" }, "title": { "type": "string", "description": "Item title" }, "category": { "type": "string", "nullable": true, "description": "Item category" }, "channel": { "type": "string", "nullable": true, "description": "Order channel (POS, KIOSK, QR, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM)", "enum": [ "POS", "KIOSK", "QR", "ONLINE", "TAKEAWAY", "MOVE", "MERGE", "SPLIT", "SYSTEM" ] }, "isTakeaway": { "type": "boolean", "description": "Whether this specific item is takeaway (can differ from the tab-level tabType)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } } }, "description": "Purchased items" }, "metadata": { "type": "object", "nullable": true, "description": "Additional metadata", "additionalProperties": true } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/reporting/export-settings": { "get": { "summary": "Get saved accounting export configuration for a location", "tags": [ "Reporting" ], "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "locationId", "required": true }, { "schema": { "type": "string", "enum": [ "sie", "gbat10" ] }, "in": "query", "name": "exportType", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "exportSettings": { "type": "object", "nullable": true, "properties": { "locationId": { "type": "integer" }, "exportType": { "type": "string", "enum": [ "sie", "gbat10" ] }, "mappings": { "type": "object", "description": "Per-key account number (string) or feature toggle (boolean). Keys are produced by the frontend mapping registries (e.g. \"psp_adyen\", \"vat_25\").", "additionalProperties": { "type": [ "string", "boolean" ] } }, "includeKarmaFees": { "type": "boolean" }, "splitByCostCenter": { "type": "boolean", "description": "When true, the purchase summary endpoint groups sales / VAT / PSP rows by cost center and the SIE/GBAT10 exports emit one #OBJEKT per CC." }, "updatedAt": { "type": "string" }, "updatedByRetailerUserId": { "type": "integer", "nullable": true }, "updatedByName": { "type": "string", "nullable": true } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" }, "executionTimeMs": { "type": "integer" } } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" }, "executionTimeMs": { "type": "integer" } } } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" }, "executionTimeMs": { "type": "integer" } } } } } } } } } }, "put": { "summary": "Save accounting export configuration for a location", "tags": [ "Reporting" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "locationId", "exportType", "mappings", "includeKarmaFees" ], "properties": { "locationId": { "type": "integer" }, "exportType": { "type": "string", "enum": [ "sie", "gbat10" ] }, "mappings": { "type": "object", "additionalProperties": { "type": [ "string", "boolean" ] } }, "includeKarmaFees": { "type": "boolean" }, "splitByCostCenter": { "type": "boolean", "default": false } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "exportSettings": { "type": "object", "nullable": true, "properties": { "locationId": { "type": "integer" }, "exportType": { "type": "string", "enum": [ "sie", "gbat10" ] }, "mappings": { "type": "object", "description": "Per-key account number (string) or feature toggle (boolean). Keys are produced by the frontend mapping registries (e.g. \"psp_adyen\", \"vat_25\").", "additionalProperties": { "type": [ "string", "boolean" ] } }, "includeKarmaFees": { "type": "boolean" }, "splitByCostCenter": { "type": "boolean", "description": "When true, the purchase summary endpoint groups sales / VAT / PSP rows by cost center and the SIE/GBAT10 exports emit one #OBJEKT per CC." }, "updatedAt": { "type": "string" }, "updatedByRetailerUserId": { "type": "integer", "nullable": true }, "updatedByName": { "type": "string", "nullable": true } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" }, "executionTimeMs": { "type": "integer" } } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" }, "executionTimeMs": { "type": "integer" } } } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" }, "executionTimeMs": { "type": "integer" } } } } } } } } } } }, "/api/v1/reporting/purchase-summary": { "get": { "summary": "Get aggregated purchase data for accounting export", "tags": [ "Reporting" ], "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID to get purchase summary for" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "startDate", "required": true, "description": "Start date in YYYY-MM-DD format" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "endDate", "required": true, "description": "End date in YYYY-MM-DD format (inclusive)" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "splitByCostCenter", "required": false, "description": "When true, rows in items / vats / psp gain optional costCenterCode + costCenterName, and the response includes a top-level costCenters array. Defaults to false for byte-identical legacy behaviour." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchaseSummary": { "type": "object", "properties": { "items": { "type": "array", "description": "Line items grouped by accounting account", "items": { "type": "object", "properties": { "account": { "type": "string", "description": "Account number or \"no_account\" for unmapped items" }, "description": { "type": "string", "nullable": true, "description": "Account description" }, "amount": { "type": "integer", "description": "Total amount in cents (excluding VAT)" }, "comment": { "type": "array", "description": "List of items without account mapping (only for no_account)", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "costCenterCode": { "type": "string", "description": "Cost-center identifier (cost_centers.code, falling back to id). Only present when splitByCostCenter=true AND the underlying tab had a cost_center_id." }, "costCenterName": { "type": "string", "description": "Human-readable CC name. Paired with costCenterCode." } }, "required": [ "account", "amount" ] } }, "vats": { "type": "array", "description": "VAT amounts grouped by rate", "items": { "type": "object", "properties": { "vat": { "type": "integer", "description": "VAT rate as percentage (e.g., 25, 12, 6)" }, "amount": { "type": "integer", "description": "Total VAT amount in cents" }, "costCenterCode": { "type": "string" }, "costCenterName": { "type": "string" } }, "required": [ "vat", "amount" ] } }, "psp": { "type": "array", "description": "Totals grouped by payment service provider", "items": { "type": "object", "properties": { "psp": { "type": "string", "description": "PSP name (e.g., adyen, swish)" }, "amount": { "type": "integer", "description": "Total amount in cents (including VAT and tips)" }, "tips": { "type": "integer", "description": "Tips amount in cents" }, "costCenterCode": { "type": "string" }, "costCenterName": { "type": "string" } }, "required": [ "psp", "amount", "tips" ] } }, "fees": { "type": "array", "description": "Karma fees grouped by PSP (never split per cost center)", "items": { "type": "object", "properties": { "psp": { "type": "string", "description": "PSP name" }, "vat": { "type": "integer", "description": "VAT on fees in cents" }, "amount": { "type": "integer", "description": "Fee amount in cents (excluding VAT)" } }, "required": [ "psp", "vat", "amount" ] } }, "costCenters": { "type": "array", "description": "Distinct cost centers that contributed at least one non-zero row. Only present when splitByCostCenter=true.", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] } } }, "required": [ "items", "vats", "psp", "fees" ] } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" }, "executionTimeMs": { "type": "integer" } } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" }, "executionTimeMs": { "type": "integer" } } } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" }, "executionTimeMs": { "type": "integer" } } } } } } } } } } }, "/api/v1/reviews": { "post": { "summary": "Create review", "tags": [ "Reviews" ], "description": "Create a new review for a purchase. Reviews are linked to purchases via purchase_intent_id and can only be created once per purchase (duplicate submissions are idempotent).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "purchaseIntentId", "rating" ], "additionalProperties": false, "properties": { "purchaseIntentId": { "type": "string", "format": "uuid", "description": "UUID of the purchase intent this review is for" }, "reviewTags": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Array of review tag values" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Rating from 1 to 5 stars" } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "reviewId" ], "properties": { "reviewId": { "type": "string", "format": "uuid", "description": "UUID of the created review" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/reviews/{purchaseIntentId}": { "get": { "summary": "Get review by purchase intent ID", "tags": [ "Reviews" ], "description": "Get a review by purchase intent ID. Returns null if no review exists for the given purchase (not a 404 error).", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "purchaseIntentId", "required": true, "description": "UUID of the purchase intent to get the review for" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "nullable": true, "properties": { "reviewId": { "type": "string", "format": "uuid", "description": "Unique identifier for the review" }, "reviewTags": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Array of review tag values (e.g., \"GOOD_FOOD_OR_DRINKS\", \"FRIENDLY_STAFF\")" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Rating from 1 to 5 stars" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/roles": { "get": { "summary": "List roles", "tags": [ "Roles" ], "description": "List all roles in a company with optional filters\n\nNote: KARMELEON role is automatically filtered from results\n\n**Permissions:** 🔵 `roles.read`", "parameters": [ { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "number", "minimum": 1, "maximum": 1000, "default": 50 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "locationId": { "type": "number", "nullable": true, "description": "NULL = global role, number = location-specific role" }, "permissionIds": { "type": "array", "items": { "type": "number" } }, "isGlobal": { "type": "boolean", "description": "True if this is a global/default role (available to all locations)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create role", "tags": [ "Roles" ], "description": "Create a new role in the company\n\n**Permissions:** 🟢 `roles.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "permissionIds" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "nullable": true, "description": "Optional role description" }, "permissionIds": { "type": "array", "items": { "type": "number" }, "description": "Array of permission IDs to assign to this role" } } } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "locationId": { "type": "number", "nullable": true, "description": "NULL = global role, number = location-specific role" }, "permissionIds": { "type": "array", "items": { "type": "number" } }, "isGlobal": { "type": "boolean", "description": "True if this is a global/default role (available to all locations)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/roles/{id}": { "get": { "summary": "Get role", "tags": [ "Roles" ], "description": "Get a single role by ID\n\n**Permissions:** 🔵 `roles.read`", "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "id", "required": true, "description": "Role ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "locationId": { "type": "number", "nullable": true, "description": "NULL = global role, number = location-specific role" }, "permissionIds": { "type": "array", "items": { "type": "number" } }, "isGlobal": { "type": "boolean", "description": "True if this is a global/default role (available to all locations)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update role", "tags": [ "Roles" ], "description": "Update an existing role\n\nNote: Cannot update system roles or KARMELEON role\n\n**Permissions:** 🟠 `roles.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "description": "Optional role description" }, "permissionIds": { "type": "array", "items": { "type": "number" }, "description": "Array of permission IDs to assign to this role" } } } } } }, "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "id", "required": true, "description": "Role ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "locationId": { "type": "number", "nullable": true, "description": "NULL = global role, number = location-specific role" }, "permissionIds": { "type": "array", "items": { "type": "number" } }, "isGlobal": { "type": "boolean", "description": "True if this is a global/default role (available to all locations)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete role", "tags": [ "Roles" ], "description": "Delete a role\n\nNote: Cannot delete system roles, KARMELEON role, or roles in use by users\n\n**Permissions:** 🔴 `roles.delete`", "parameters": [ { "schema": { "type": "number" }, "in": "path", "name": "id", "required": true, "description": "Role ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "number" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/schedules": { "get": { "summary": "List schedules", "tags": [ "Schedules" ], "description": "List schedules with optional filtering", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP", "VOUCHER", "EARNING_RULE", "BOOKING", "LOYALTY_REWARD" ] }, "in": "query", "name": "entityType", "required": false, "description": "Filter by entity type" }, { "schema": { "type": "string" }, "in": "query", "name": "entityId", "required": false, "description": "Filter by entity ID" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isActive", "required": false, "description": "Filter by active status" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "schedules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique schedule ID" }, "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP", "VOUCHER", "EARNING_RULE", "BOOKING", "LOYALTY_REWARD" ], "description": "Type of entity being scheduled" }, "entityId": { "type": "string", "description": "ID of the entity being scheduled" }, "locationId": { "type": "number", "description": "Location ID this schedule applies to" }, "name": { "type": "string", "nullable": true, "description": "Schedule name" }, "description": { "type": "string", "nullable": true, "description": "Schedule description" }, "isActive": { "type": "boolean", "description": "Whether schedule is active" }, "priority": { "type": "number", "description": "Priority for conflicting schedules (higher = more important)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule ID" }, "scheduleId": { "type": "string", "description": "Schedule ID this rule belongs to" }, "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "nullable": true, "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "nullable": true, "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "nullable": true, "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "description": "Whether entity is available during this rule" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "scheduleId", "ruleType", "isAvailable", "createdAt" ] }, "description": "Schedule rules defining availability patterns" } }, "required": [ "id", "entityType", "entityId", "locationId", "isActive", "priority", "createdAt", "updatedAt", "rules" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "schedules", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create schedule", "tags": [ "Schedules" ], "description": "Create a new schedule with rules\n\n**Permissions:** 🟢 `schedules.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP", "VOUCHER", "EARNING_RULE", "BOOKING", "LOYALTY_REWARD" ], "description": "Type of entity being scheduled" }, "entityId": { "type": "string", "description": "ID of the entity to schedule" }, "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Schedule name" }, "description": { "type": "string", "description": "Schedule description" }, "isActive": { "type": "boolean", "default": true, "description": "Whether schedule is active" }, "priority": { "type": "number", "default": 0, "description": "Priority for conflicting schedules" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "default": true, "description": "Whether entity is available during this rule" } }, "required": [ "ruleType" ] }, "description": "Schedule rules defining availability patterns" } }, "required": [ "entityType", "entityId", "locationId", "rules" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique schedule ID" }, "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP", "VOUCHER", "EARNING_RULE", "BOOKING", "LOYALTY_REWARD" ], "description": "Type of entity being scheduled" }, "entityId": { "type": "string", "description": "ID of the entity being scheduled" }, "locationId": { "type": "number", "description": "Location ID this schedule applies to" }, "name": { "type": "string", "nullable": true, "description": "Schedule name" }, "description": { "type": "string", "nullable": true, "description": "Schedule description" }, "isActive": { "type": "boolean", "description": "Whether schedule is active" }, "priority": { "type": "number", "description": "Priority for conflicting schedules (higher = more important)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule ID" }, "scheduleId": { "type": "string", "description": "Schedule ID this rule belongs to" }, "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "nullable": true, "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "nullable": true, "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "nullable": true, "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "description": "Whether entity is available during this rule" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "scheduleId", "ruleType", "isAvailable", "createdAt" ] }, "description": "Schedule rules defining availability patterns" } }, "required": [ "id", "entityType", "entityId", "locationId", "isActive", "priority", "createdAt", "updatedAt", "rules" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/schedules/{id}": { "get": { "summary": "Get schedule", "tags": [ "Schedules" ], "description": "Get a single schedule by ID with its rules", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Schedule ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique schedule ID" }, "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP", "VOUCHER", "EARNING_RULE", "BOOKING", "LOYALTY_REWARD" ], "description": "Type of entity being scheduled" }, "entityId": { "type": "string", "description": "ID of the entity being scheduled" }, "locationId": { "type": "number", "description": "Location ID this schedule applies to" }, "name": { "type": "string", "nullable": true, "description": "Schedule name" }, "description": { "type": "string", "nullable": true, "description": "Schedule description" }, "isActive": { "type": "boolean", "description": "Whether schedule is active" }, "priority": { "type": "number", "description": "Priority for conflicting schedules (higher = more important)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule ID" }, "scheduleId": { "type": "string", "description": "Schedule ID this rule belongs to" }, "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "nullable": true, "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "nullable": true, "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "nullable": true, "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "description": "Whether entity is available during this rule" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "scheduleId", "ruleType", "isAvailable", "createdAt" ] }, "description": "Schedule rules defining availability patterns" } }, "required": [ "id", "entityType", "entityId", "locationId", "isActive", "priority", "createdAt", "updatedAt", "rules" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update schedule", "tags": [ "Schedules" ], "description": "Update an existing schedule\n\n**Permissions:** 🟠 `schedules.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "priority": { "type": "number" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Schedule ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique schedule ID" }, "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP", "VOUCHER", "EARNING_RULE", "BOOKING", "LOYALTY_REWARD" ], "description": "Type of entity being scheduled" }, "entityId": { "type": "string", "description": "ID of the entity being scheduled" }, "locationId": { "type": "number", "description": "Location ID this schedule applies to" }, "name": { "type": "string", "nullable": true, "description": "Schedule name" }, "description": { "type": "string", "nullable": true, "description": "Schedule description" }, "isActive": { "type": "boolean", "description": "Whether schedule is active" }, "priority": { "type": "number", "description": "Priority for conflicting schedules (higher = more important)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule ID" }, "scheduleId": { "type": "string", "description": "Schedule ID this rule belongs to" }, "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "nullable": true, "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "nullable": true, "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "nullable": true, "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "description": "Whether entity is available during this rule" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "scheduleId", "ruleType", "isAvailable", "createdAt" ] }, "description": "Schedule rules defining availability patterns" } }, "required": [ "id", "entityType", "entityId", "locationId", "isActive", "priority", "createdAt", "updatedAt", "rules" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete schedule", "tags": [ "Schedules" ], "description": "Delete a schedule and its rules\n\n**Permissions:** 🔴 `schedules.delete`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Schedule ID" } ], "responses": { "200": { "description": "Schedule successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/schedules/{scheduleId}/rules": { "post": { "summary": "Add schedule rule", "tags": [ "Schedules" ], "description": "Add a new rule to an existing schedule\n\n**Permissions:** 🟢 `schedules.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "default": true, "description": "Whether entity is available during this rule" } }, "required": [ "ruleType" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "scheduleId", "required": true, "description": "Schedule ID" } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule ID" }, "scheduleId": { "type": "string", "description": "Schedule ID this rule belongs to" }, "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "nullable": true, "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "nullable": true, "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "nullable": true, "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "description": "Whether entity is available during this rule" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "scheduleId", "ruleType", "isAvailable", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Replace schedule rules", "tags": [ "Schedules" ], "description": "Replace all rules for a schedule in a single operation\n\n**Permissions:** 🟠 `schedules.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "default": true, "description": "Whether entity is available during this rule" } }, "required": [ "ruleType" ] }, "description": "New rules to replace existing rules", "minItems": 1 } }, "required": [ "rules" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "scheduleId", "required": true, "description": "Schedule ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique schedule ID" }, "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP", "VOUCHER", "EARNING_RULE", "BOOKING", "LOYALTY_REWARD" ], "description": "Type of entity being scheduled" }, "entityId": { "type": "string", "description": "ID of the entity being scheduled" }, "locationId": { "type": "number", "description": "Location ID this schedule applies to" }, "name": { "type": "string", "nullable": true, "description": "Schedule name" }, "description": { "type": "string", "nullable": true, "description": "Schedule description" }, "isActive": { "type": "boolean", "description": "Whether schedule is active" }, "priority": { "type": "number", "description": "Priority for conflicting schedules (higher = more important)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule ID" }, "scheduleId": { "type": "string", "description": "Schedule ID this rule belongs to" }, "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "nullable": true, "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "nullable": true, "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "nullable": true, "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "description": "Whether entity is available during this rule" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "scheduleId", "ruleType", "isAvailable", "createdAt" ] }, "description": "Schedule rules defining availability patterns" } }, "required": [ "id", "entityType", "entityId", "locationId", "isActive", "priority", "createdAt", "updatedAt", "rules" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/schedules/check-availability": { "get": { "summary": "Check availability", "tags": [ "Schedules" ], "description": "Check entity availability at a specific time based on schedules", "parameters": [ { "schema": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP", "VOUCHER", "EARNING_RULE", "BOOKING", "LOYALTY_REWARD" ] }, "in": "query", "name": "entityType", "required": true, "description": "Type of entity to check" }, { "schema": { "type": "string" }, "in": "query", "name": "entityId", "required": true, "description": "ID of the entity to check" }, { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Location ID" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "checkTime", "required": false, "description": "Time to check availability (defaults to now)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "isAvailable": { "type": "boolean", "description": "Whether entity is available at the specified time" }, "matchingSchedules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique schedule ID" }, "entityType": { "type": "string", "enum": [ "MENU", "ITEM", "LOCATION", "MODIFIER", "CATEGORY", "MENU_LAYOUT", "VARIANT_GROUP", "VOUCHER", "EARNING_RULE", "BOOKING", "LOYALTY_REWARD" ], "description": "Type of entity being scheduled" }, "entityId": { "type": "string", "description": "ID of the entity being scheduled" }, "locationId": { "type": "number", "description": "Location ID this schedule applies to" }, "name": { "type": "string", "nullable": true, "description": "Schedule name" }, "description": { "type": "string", "nullable": true, "description": "Schedule description" }, "isActive": { "type": "boolean", "description": "Whether schedule is active" }, "priority": { "type": "number", "description": "Priority for conflicting schedules (higher = more important)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule ID" }, "scheduleId": { "type": "string", "description": "Schedule ID this rule belongs to" }, "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "nullable": true, "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "nullable": true, "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "nullable": true, "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "description": "Whether entity is available during this rule" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "scheduleId", "ruleType", "isAvailable", "createdAt" ] }, "description": "Schedule rules defining availability patterns" } }, "required": [ "id", "entityType", "entityId", "locationId", "isActive", "priority", "createdAt", "updatedAt", "rules" ] }, "description": "Schedules that apply to this entity" } }, "required": [ "isAvailable", "matchingSchedules" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/schedules/rules/{ruleId}": { "put": { "summary": "Update schedule rule", "tags": [ "Schedules" ], "description": "Update an existing schedule rule\n\n**Permissions:** 🟠 `schedules.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ] }, "weekday": { "type": "number", "nullable": true, "minimum": 0, "maximum": 6 }, "startTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$" }, "endTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$" }, "startDate": { "type": "string", "nullable": true, "format": "date" }, "endDate": { "type": "string", "nullable": true, "format": "date" }, "validFrom": { "type": "string", "nullable": true, "format": "date" }, "validTo": { "type": "string", "nullable": true, "format": "date" }, "isAvailable": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "ruleId", "required": true, "description": "Rule ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique rule ID" }, "scheduleId": { "type": "string", "description": "Schedule ID this rule belongs to" }, "ruleType": { "type": "string", "enum": [ "WEEKDAY", "DATE_RANGE", "SPECIFIC_DATE" ], "description": "Type of schedule rule" }, "weekday": { "type": "number", "nullable": true, "minimum": 0, "maximum": 6, "description": "Day of week (0=Sunday, 6=Saturday)" }, "startTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "Start time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "endTime": { "type": "string", "nullable": true, "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$", "description": "End time in HH:MM or HH:MM:SS format (seconds are stripped)" }, "startDate": { "type": "string", "nullable": true, "format": "date", "description": "Start date for date range rules" }, "endDate": { "type": "string", "nullable": true, "format": "date", "description": "End date for date range rules" }, "validFrom": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid from date" }, "validTo": { "type": "string", "nullable": true, "format": "date", "description": "Rule valid until date" }, "isAvailable": { "type": "boolean", "description": "Whether entity is available during this rule" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "scheduleId", "ruleType", "isAvailable", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete schedule rule", "tags": [ "Schedules" ], "description": "Delete a schedule rule\n\n**Permissions:** 🔴 `schedules.delete`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "ruleId", "required": true, "description": "Rule ID" } ], "responses": { "200": { "description": "Rule successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/settlements/{settlementId}": { "get": { "summary": "Get settlement details", "tags": [ "Settlements" ], "description": "Get settlement details by ID", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "settlementId", "required": true, "description": "ID of the settlement to retrieve" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "id", "tabMemberId", "state", "createdAt", "updatedAt" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the settlement" }, "tabMemberId": { "type": "string", "format": "uuid", "description": "ID of the tab member who owns this settlement" }, "paymentId": { "type": "integer", "nullable": true, "description": "Payment ID if settlement has been processed for payment" }, "state": { "type": "string", "enum": [ "in_preparation", "payment_in_progress", "settled", "cancelled" ], "description": "Current state of the settlement" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the settlement was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the settlement was last updated" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/settlements/active": { "post": { "summary": "Get or create active settlement", "tags": [ "Settlements" ], "description": "Get or create active settlement for a tab member", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "tabMember" ], "additionalProperties": false, "properties": { "tabMember": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "integer", "description": "User ID (Priority 1 - highest priority)" }, "email": { "type": "string", "format": "email", "description": "Email address (Priority 2)" }, "phone": { "type": "string", "description": "Phone number (Priority 3)" }, "identifier": { "type": "string", "description": "Device identifier or session ID (Priority 4 - lowest priority)" } }, "description": "Tab member identification. The system uses priority order: id > email > phone > identifier" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "ID of the tab to get settlement for" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "tabSettlementId", "state", "isNew" ], "additionalProperties": false, "properties": { "tabSettlementId": { "type": "string", "format": "uuid", "description": "Unique identifier for the settlement" }, "state": { "type": "string", "enum": [ "in_preparation", "payment_in_progress", "settled", "cancelled" ], "description": "Current state of the settlement" }, "isNew": { "type": "boolean", "description": "Whether this settlement was just created (true) or already existed (false)" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/statistics/items-aggregated": { "get": { "tags": [ "Statistics" ], "description": "Retrieve aggregated items and modifications with pagination.\n\n**Query Routing**: Automatically routes to BigQuery for historical data (>24 hours) or PostgreSQL for recent data.\n\n**Item Types**:\n- `regular_item` - Normal menu items\n- Other types - Item modifications (extras)\n\n**Use Cases**:\n- Item sales reports\n- Menu performance analysis\n- VAT reporting\n\n**Permissions:** 🔵 `statistics.read`", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "locationIds", "required": true, "description": "Comma-separated list of location IDs" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": true, "description": "Start date (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": true, "description": "End date (YYYY-MM-DD)" }, { "schema": { "type": "string", "default": "1" }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "string", "default": "50" }, "in": "query", "name": "limit", "required": false, "description": "Items per page (max 1000)" } ], "responses": { "200": { "description": "Aggregated items data", "content": { "application/json": { "schema": { "description": "Aggregated items data", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "locationName": { "type": "string", "nullable": true }, "locationId": { "type": "number" }, "itemId": { "type": "number", "nullable": true }, "articleNumber": { "type": "string", "nullable": true }, "itemType": { "type": "string" }, "discountPercentage": { "type": "number" }, "amountIncVat": { "type": "number" }, "vatAmount": { "type": "number" }, "amountExVat": { "type": "number" }, "vatRate": { "type": "number", "nullable": true }, "soldCount": { "type": "number" } }, "required": [ "locationId", "itemType", "amountIncVat", "vatAmount", "amountExVat", "soldCount" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number" }, "limit": { "type": "number" }, "total": { "type": "number" }, "totalPages": { "type": "number" } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "items", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" }, "source": { "type": "string", "enum": [ "bigquery", "postgres" ] } }, "required": [ "requestId", "timestamp", "executionTimeMs", "source" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/statistics/sale-summary": { "get": { "tags": [ "Statistics" ], "description": "Retrieve sale summary with items, extras (modifications), and tips for a date range.\n\n**Query Routing**: Automatically routes to BigQuery for historical data (>24 hours) or PostgreSQL for recent data.\n\n**Response includes**:\n- Items sold with VAT breakdown\n- Item modifications (extras) with VAT breakdown\n- Total tips\n- Summary totals\n\n**Permissions:** 🔵 `statistics.read`", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "locationIds", "required": true, "description": "Comma-separated list of location IDs" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": true, "description": "Start date (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": true, "description": "End date (YYYY-MM-DD)" } ], "responses": { "200": { "description": "Sale summary data", "content": { "application/json": { "schema": { "description": "Sale summary data", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "number", "nullable": true }, "soldCount": { "type": "number" }, "amountIncVat": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "number", "nullable": true } }, "required": [ "soldCount", "amountIncVat", "vatAmount" ] } }, "extras": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "number", "nullable": true }, "soldCount": { "type": "number" }, "amountIncVat": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "number", "nullable": true } }, "required": [ "soldCount", "amountIncVat", "vatAmount" ] } }, "totalTips": { "type": "number" }, "summary": { "type": "object", "properties": { "totalAmountIncVat": { "type": "number" }, "totalVatAmount": { "type": "number" }, "totalSoldCount": { "type": "number" } }, "required": [ "totalAmountIncVat", "totalVatAmount", "totalSoldCount" ] } }, "required": [ "items", "extras", "totalTips", "summary" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" }, "source": { "type": "string", "enum": [ "bigquery", "postgres" ] } }, "required": [ "requestId", "timestamp", "executionTimeMs", "source" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/statistics/time-series": { "get": { "tags": [ "Statistics" ], "description": "Retrieve time series data for a specific metric across locations and date range.\n\n**Query Routing**: Automatically routes to BigQuery for historical data (>24 hours) or PostgreSQL for recent data.\n\n**Available Metrics**:\n- `gmv` - Gross Merchandise Value\n- `orders_count` - Number of orders\n- `sold_count` - Number of items sold\n- `tips_amount` - Total tips amount\n- `saved_co2` - CO2 saved (grams)\n- `pushes_sent` - Push notifications sent\n\n**Target Options**:\n- `aggregated` - Combine all locations into single series\n- `locations` - Return separate series per location\n\n**Permissions:** 🔵 `statistics.read`", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "locationIds", "required": true, "description": "Comma-separated list of location IDs (e.g., \"100,101,102\")" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": true, "description": "Start date (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": true, "description": "End date (YYYY-MM-DD)" }, { "schema": { "type": "string", "enum": [ "gmv", "orders_count", "sold_count", "tips_amount", "saved_co2", "pushes_sent" ] }, "in": "query", "name": "metric", "required": true, "description": "Metric to retrieve" }, { "schema": { "type": "string", "enum": [ "aggregated", "locations" ], "default": "aggregated" }, "in": "query", "name": "target", "required": false, "description": "Aggregation target" } ], "responses": { "200": { "description": "Time series data", "content": { "application/json": { "schema": { "description": "Time series data", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "metric": { "type": "string" }, "target": { "type": "string", "enum": [ "aggregated", "locations" ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "locationId": { "type": "number", "nullable": true }, "date": { "type": "string", "format": "date" }, "value": { "type": "number" } }, "required": [ "date", "value" ] } }, "summary": { "type": "object", "properties": { "total": { "type": "number" }, "average": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "total", "average", "min", "max" ] } }, "required": [ "metric", "target", "points", "summary" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" }, "source": { "type": "string", "enum": [ "bigquery", "postgres" ] } }, "required": [ "requestId", "timestamp", "executionTimeMs", "source" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/statistics/time-series-batch": { "get": { "tags": [ "Statistics" ], "description": "Retrieve time series data for MULTIPLE metrics in a single request. Much more efficient than calling the single-metric endpoint multiple times.\n\n**Query Routing**: Automatically routes to BigQuery for historical data (>24 hours) or PostgreSQL for recent data.\n\n**Available Metrics** (comma-separated):\n- `gmv` - Gross Merchandise Value\n- `orders_count` - Number of orders\n- `sold_count` - Number of items sold\n- `tips_amount` - Total tips amount\n- `saved_co2` - CO2 saved (grams)\n- `pushes_sent` - Push notifications sent\n\n**Target Options**:\n- `aggregated` - Combine all locations into single series\n- `locations` - Return separate series per location\n\n**Example**: `/api/v1/statistics/time-series-batch?metrics=gmv,orders_count,sold_count&locationIds=100,101&startDate=2025-01-01&endDate=2025-01-31`\n\n**Permissions:** 🔵 `statistics.read`", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "locationIds", "required": true, "description": "Comma-separated list of location IDs (e.g., \"100,101,102\")" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": true, "description": "Start date (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": true, "description": "End date (YYYY-MM-DD)" }, { "schema": { "type": "string" }, "in": "query", "name": "metrics", "required": true, "description": "Comma-separated list of metrics (e.g., \"gmv,orders_count,sold_count\")" }, { "schema": { "type": "string", "enum": [ "aggregated", "locations" ], "default": "aggregated" }, "in": "query", "name": "target", "required": false, "description": "Aggregation target" } ], "responses": { "200": { "description": "Time series data for multiple metrics", "content": { "application/json": { "schema": { "description": "Time series data for multiple metrics", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "aggregated", "locations" ] }, "metrics": { "type": "object", "additionalProperties": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "gmv", "orders_count", "sold_count", "tips_amount", "saved_co2", "pushes_sent" ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "locationId": { "type": "number", "nullable": true }, "date": { "type": "string", "format": "date" }, "value": { "type": "number" } }, "required": [ "date", "value" ] } }, "summary": { "type": "object", "properties": { "total": { "type": "number" }, "average": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "total", "average", "min", "max" ] } }, "required": [ "metric", "points", "summary" ] }, "description": "Object with metric names as keys and their data as values" } }, "required": [ "target", "metrics" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" }, "source": { "type": "string", "enum": [ "bigquery", "postgres" ] }, "metricsRequested": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs", "source", "metricsRequested" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/statistics/tips": { "get": { "tags": [ "Statistics" ], "description": "Retrieve tips for a location and date range.\n\n**Query Routing**: Automatically routes to BigQuery for historical data (>24 hours) or PostgreSQL for recent data.\n\n**Response includes**:\n- Tips by date with VAT breakdown\n- Total amounts and counts\n\n**Permissions:** 🔵 `statistics.read`", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "startDate", "required": true, "description": "Start date (YYYY-MM-DD)" }, { "schema": { "type": "string", "format": "date" }, "in": "query", "name": "endDate", "required": true, "description": "End date (YYYY-MM-DD)" } ], "responses": { "200": { "description": "Tips data", "content": { "application/json": { "schema": { "description": "Tips data", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tips": { "type": "array", "items": { "type": "object", "properties": { "locationId": { "type": "number" }, "date": { "type": "string", "format": "date" }, "amountIncVat": { "type": "number" }, "vat": { "type": "number", "nullable": true }, "vatRate": { "type": "number", "nullable": true }, "count": { "type": "number" }, "title": { "type": "string", "nullable": true } }, "required": [ "locationId", "date", "amountIncVat", "count" ] } }, "summary": { "type": "object", "properties": { "totalAmount": { "type": "number" }, "totalCount": { "type": "number" } }, "required": [ "totalAmount", "totalCount" ] } }, "required": [ "tips", "summary" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" }, "source": { "type": "string", "enum": [ "bigquery", "postgres" ] } }, "required": [ "requestId", "timestamp", "executionTimeMs", "source" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/table-groups": { "get": { "summary": "List table groups", "tags": [ "Table Groups" ], "description": "List table groups with optional filtering and sorting\n\n**Permissions:** 🔵 `table_groups.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Search by name or description" }, { "schema": { "type": "string", "default": "name" }, "in": "query", "name": "sort", "required": false, "description": "Sort field (name, created_at)" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "in": "query", "name": "order", "required": false, "description": "Sort order" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tableGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique table group ID" }, "name": { "type": "string", "description": "Group name (e.g., \"Patio\", \"Main Dining Room\")" }, "description": { "type": "string", "nullable": true, "description": "Group description" }, "locationId": { "type": "number", "description": "Location ID" }, "tableIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of table UUIDs in this group" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last update timestamp" } }, "required": [ "id", "name", "locationId", "tableIds", "createdAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "tableGroups", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create table group", "tags": [ "Table Groups" ], "description": "Create a new table group\n\n**Permissions:** 🟢 `table_groups.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "minLength": 1, "description": "Group name" }, "description": { "type": "string", "description": "Group description" } }, "required": [ "locationId", "name" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique table group ID" }, "name": { "type": "string", "description": "Group name (e.g., \"Patio\", \"Main Dining Room\")" }, "description": { "type": "string", "nullable": true, "description": "Group description" }, "locationId": { "type": "number", "description": "Location ID" }, "tableIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of table UUIDs in this group" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last update timestamp" } }, "required": [ "id", "name", "locationId", "tableIds", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/table-groups/{id}": { "get": { "summary": "Get table group", "tags": [ "Table Groups" ], "description": "Get a single table group by ID with table UUIDs\n\n**Permissions:** 🔵 `table_groups.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Table group ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique table group ID" }, "name": { "type": "string", "description": "Group name (e.g., \"Patio\", \"Main Dining Room\")" }, "description": { "type": "string", "nullable": true, "description": "Group description" }, "locationId": { "type": "number", "description": "Location ID" }, "tableIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of table UUIDs in this group" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last update timestamp" } }, "required": [ "id", "name", "locationId", "tableIds", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update table group", "tags": [ "Table Groups" ], "description": "Update an existing table group\n\n**Permissions:** 🟠 `table_groups.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "nullable": true } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Table group ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique table group ID" }, "name": { "type": "string", "description": "Group name (e.g., \"Patio\", \"Main Dining Room\")" }, "description": { "type": "string", "nullable": true, "description": "Group description" }, "locationId": { "type": "number", "description": "Location ID" }, "tableIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of table UUIDs in this group" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last update timestamp" } }, "required": [ "id", "name", "locationId", "tableIds", "createdAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete table group", "tags": [ "Table Groups" ], "description": "Delete a table group\n\n**Permissions:** 🔴 `table_groups.delete`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Table group ID" } ], "responses": { "200": { "description": "Table group successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/staff": { "get": { "summary": "List staff for a location", "tags": [ "Tables" ], "description": "List retailer_users with access to a location. Powers the POS table-map Staff sidebar. Returns a minimal projection (id, name, color).\n\n**Permissions:** 🔵 `tables.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "staff": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": [ "null", "string" ] }, "color": { "type": [ "null", "string" ], "description": "Hex color (#RRGGBB) or null." } }, "required": [ "id" ] } } }, "required": [ "staff" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/retailer-users/{retailerUserId}/color": { "put": { "summary": "Update a staff member's color", "tags": [ "Tables" ], "description": "Set or clear the hex color used on the POS table-map staff badge. The target retailer_user must have access to the caller's active location.\n\n**Permissions:** 🟠 `tables.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "color": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex color (#RRGGBB) or null to clear." } }, "required": [ "color" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "retailerUserId", "required": true, "description": "Retailer user ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": [ "null", "string" ] }, "color": { "type": [ "null", "string" ] } }, "required": [ "id" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tables": { "get": { "summary": "List tables", "tags": [ "Tables" ], "description": "List tables with optional filtering\n\n**Permissions:** 🔵 `tables.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "string", "enum": [ "live", "paused", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by status" }, { "schema": { "type": "number" }, "in": "query", "name": "tableGroupId", "required": false, "description": "Filter by table group ID" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Search by name or description" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 999, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique table ID (UUID)" }, "name": { "type": "string", "description": "Table name/number" }, "description": { "type": "string", "nullable": true, "description": "Table description" }, "contextParams": { "type": "object", "additionalProperties": true, "description": "Custom context parameters" }, "locationId": { "type": "number", "description": "Location ID" }, "storefrontUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Full storefront URL for this table" }, "tableGroupId": { "type": "number", "nullable": true, "description": "Table group ID (if grouped)" }, "costCenterId": { "type": "number", "nullable": true, "description": "Cost center ID" }, "status": { "type": "string", "enum": [ "live", "paused", "deleted" ], "description": "Table status" }, "qrCodeImageUrl": { "type": "string", "format": "uri", "nullable": true, "description": "QR code image URL" }, "activeTabs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tab UUID" }, "state": { "type": "string", "description": "Tab state (started, initiated, etc.)" }, "orderTotal": { "type": "number", "description": "Total order amount in cents (legacy field)" }, "paidTotal": { "type": "number", "description": "Total paid amount in cents (legacy field)" }, "tipsTotal": { "type": "number", "description": "Total tips in cents" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "description": "Selected payment flow" }, "coursingOrder": { "type": "number", "nullable": true, "description": "Current coursing level for the tab (items below this level cannot be sent)" }, "memberCount": { "type": "number", "description": "Number of tab_members on this tab (party size for walk-ins)" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents (from tabs table)" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents (from tabs table)" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance in cents" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode" }, "storefrontQrCodeId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/QR code UUID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Tab creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Tab last update timestamp" }, "extras": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tab extras (only in single table endpoint)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kitchen dispatch UUID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "state": { "type": "string", "description": "Dispatch state" }, "tabUUID": { "type": "string", "description": "Tab UUID" }, "tabType": { "type": "string", "description": "Tab type (table, takeaway, etc.)" }, "tableName": { "type": "string", "nullable": true, "description": "Table name if applicable" }, "tabState": { "type": "string", "description": "Current tab state" }, "source": { "type": "string", "nullable": true, "description": "Source channel that created the dispatch (POS, QR, KIOSK, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM)" }, "message": { "type": "string", "nullable": true, "description": "Optional contextual message (e.g., \"Moved from Table 5\")" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text" }, "createdAt": { "type": "string", "format": "date-time", "description": "Comment timestamp" }, "tabMemberUUID": { "type": "string", "nullable": true, "description": "Tab member UUID who made the comment" }, "uuid": { "type": "string", "description": "Comment UUID" } }, "additionalProperties": true }, "description": "Dispatch comments" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kitchen dispatch item UUID" }, "itemId": { "type": "number", "nullable": true, "description": "Item ID from inventory" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications" }, "quantityCents": { "type": "number", "nullable": true, "description": "Item quantity in cents (e.g., 100 = 1.0, 50 = 0.5)" }, "coursingOrder": { "type": "number", "nullable": true, "description": "Coursing level for this item (e.g., 1=appetizer, 2=main, 3=dessert)" }, "isNonSurplus": { "type": "boolean", "description": "Whether item is non-surplus" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "title": { "type": "string", "nullable": true, "description": "Item title" }, "tabMember": { "type": "object", "properties": { "uuid": { "type": "string", "nullable": true, "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" } }, "additionalProperties": true }, "comments": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text" }, "createdAt": { "type": "string", "format": "date-time", "description": "Comment timestamp" }, "tabMemberUUID": { "type": "string", "nullable": true, "description": "Tab member UUID who made the comment" }, "uuid": { "type": "string", "description": "Comment UUID" } }, "additionalProperties": true }, "description": "Item comments" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Variant ID" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "description": "Variant price (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } }, "additionalProperties": true }, "description": "Item variants/modifications" } }, "additionalProperties": true }, "description": "Items in this dispatch" } }, "additionalProperties": true }, "description": "Kitchen dispatches (only in single table endpoint)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "enum": [ "tab", "user" ], "description": "Entity type (tab or user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order for display" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of the user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of the user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "additionalProperties": true }, "description": "Notes attached to this tab" } }, "required": [ "id", "state" ], "additionalProperties": true }, "description": "Active tabs on this table" }, "totalOrderAmountOnActiveTables": { "type": "number", "description": "Total order amount across active tabs" }, "totalPaidAmountOnActiveTables": { "type": "number", "description": "Total paid amount across active tabs" }, "isBookable": { "type": "boolean", "description": "Whether this table accepts bookings" }, "minCapacity": { "type": [ "null", "number" ], "description": "Minimum seating capacity" }, "maxCapacity": { "type": [ "null", "number" ], "description": "Maximum seating capacity" }, "seatingDurationMinutes": { "type": [ "null", "number" ], "description": "Per-table seating duration override (minutes)" }, "newTabPerGuest": { "type": "boolean", "description": "When true, every scan of this QR forces a brand-new tab instead of joining any existing open tab. Use for shared QRs at theme parks, festivals, multi-buyer kiosks, etc." }, "requireGuestCount": { "type": "boolean", "description": "When true, the POS prompts for guest count when seating an empty table, instead of creating a tab silently." }, "assignedRetailerUser": { "type": "object", "nullable": true, "description": "Server currently assigned to this table in POS (null when unassigned).", "properties": { "id": { "type": "number" }, "name": { "type": [ "null", "string" ] }, "color": { "type": [ "null", "string" ], "description": "Hex color (#RRGGBB) used by the staff badge." } }, "required": [ "id" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "contextParams", "locationId", "status", "activeTabs", "createdAt", "isBookable" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "tables", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create table", "tags": [ "Tables" ], "description": "Create a new table\n\n**Permissions:** 🟢 `tables.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Table name/number" }, "description": { "type": "string", "description": "Table description" }, "locationId": { "type": "number", "description": "Location ID" }, "tableGroupId": { "type": "number", "description": "Table group ID" }, "costCenterId": { "type": "number", "nullable": true, "description": "Cost center ID" }, "contextParams": { "type": "object", "additionalProperties": true, "description": "Custom context parameters" } }, "required": [ "name", "locationId" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique table ID (UUID)" }, "name": { "type": "string", "description": "Table name/number" }, "description": { "type": "string", "nullable": true, "description": "Table description" }, "contextParams": { "type": "object", "additionalProperties": true, "description": "Custom context parameters" }, "locationId": { "type": "number", "description": "Location ID" }, "storefrontUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Full storefront URL for this table" }, "tableGroupId": { "type": "number", "nullable": true, "description": "Table group ID (if grouped)" }, "costCenterId": { "type": "number", "nullable": true, "description": "Cost center ID" }, "status": { "type": "string", "enum": [ "live", "paused", "deleted" ], "description": "Table status" }, "qrCodeImageUrl": { "type": "string", "format": "uri", "nullable": true, "description": "QR code image URL" }, "activeTabs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tab UUID" }, "state": { "type": "string", "description": "Tab state (started, initiated, etc.)" }, "orderTotal": { "type": "number", "description": "Total order amount in cents (legacy field)" }, "paidTotal": { "type": "number", "description": "Total paid amount in cents (legacy field)" }, "tipsTotal": { "type": "number", "description": "Total tips in cents" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "description": "Selected payment flow" }, "coursingOrder": { "type": "number", "nullable": true, "description": "Current coursing level for the tab (items below this level cannot be sent)" }, "memberCount": { "type": "number", "description": "Number of tab_members on this tab (party size for walk-ins)" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents (from tabs table)" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents (from tabs table)" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance in cents" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode" }, "storefrontQrCodeId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/QR code UUID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Tab creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Tab last update timestamp" }, "extras": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tab extras (only in single table endpoint)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kitchen dispatch UUID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "state": { "type": "string", "description": "Dispatch state" }, "tabUUID": { "type": "string", "description": "Tab UUID" }, "tabType": { "type": "string", "description": "Tab type (table, takeaway, etc.)" }, "tableName": { "type": "string", "nullable": true, "description": "Table name if applicable" }, "tabState": { "type": "string", "description": "Current tab state" }, "source": { "type": "string", "nullable": true, "description": "Source channel that created the dispatch (POS, QR, KIOSK, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM)" }, "message": { "type": "string", "nullable": true, "description": "Optional contextual message (e.g., \"Moved from Table 5\")" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text" }, "createdAt": { "type": "string", "format": "date-time", "description": "Comment timestamp" }, "tabMemberUUID": { "type": "string", "nullable": true, "description": "Tab member UUID who made the comment" }, "uuid": { "type": "string", "description": "Comment UUID" } }, "additionalProperties": true }, "description": "Dispatch comments" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kitchen dispatch item UUID" }, "itemId": { "type": "number", "nullable": true, "description": "Item ID from inventory" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications" }, "quantityCents": { "type": "number", "nullable": true, "description": "Item quantity in cents (e.g., 100 = 1.0, 50 = 0.5)" }, "coursingOrder": { "type": "number", "nullable": true, "description": "Coursing level for this item (e.g., 1=appetizer, 2=main, 3=dessert)" }, "isNonSurplus": { "type": "boolean", "description": "Whether item is non-surplus" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "title": { "type": "string", "nullable": true, "description": "Item title" }, "tabMember": { "type": "object", "properties": { "uuid": { "type": "string", "nullable": true, "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" } }, "additionalProperties": true }, "comments": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text" }, "createdAt": { "type": "string", "format": "date-time", "description": "Comment timestamp" }, "tabMemberUUID": { "type": "string", "nullable": true, "description": "Tab member UUID who made the comment" }, "uuid": { "type": "string", "description": "Comment UUID" } }, "additionalProperties": true }, "description": "Item comments" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Variant ID" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "description": "Variant price (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } }, "additionalProperties": true }, "description": "Item variants/modifications" } }, "additionalProperties": true }, "description": "Items in this dispatch" } }, "additionalProperties": true }, "description": "Kitchen dispatches (only in single table endpoint)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "enum": [ "tab", "user" ], "description": "Entity type (tab or user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order for display" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of the user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of the user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "additionalProperties": true }, "description": "Notes attached to this tab" } }, "required": [ "id", "state" ], "additionalProperties": true }, "description": "Active tabs on this table" }, "totalOrderAmountOnActiveTables": { "type": "number", "description": "Total order amount across active tabs" }, "totalPaidAmountOnActiveTables": { "type": "number", "description": "Total paid amount across active tabs" }, "isBookable": { "type": "boolean", "description": "Whether this table accepts bookings" }, "minCapacity": { "type": [ "null", "number" ], "description": "Minimum seating capacity" }, "maxCapacity": { "type": [ "null", "number" ], "description": "Maximum seating capacity" }, "seatingDurationMinutes": { "type": [ "null", "number" ], "description": "Per-table seating duration override (minutes)" }, "newTabPerGuest": { "type": "boolean", "description": "When true, every scan of this QR forces a brand-new tab instead of joining any existing open tab. Use for shared QRs at theme parks, festivals, multi-buyer kiosks, etc." }, "requireGuestCount": { "type": "boolean", "description": "When true, the POS prompts for guest count when seating an empty table, instead of creating a tab silently." }, "assignedRetailerUser": { "type": "object", "nullable": true, "description": "Server currently assigned to this table in POS (null when unassigned).", "properties": { "id": { "type": "number" }, "name": { "type": [ "null", "string" ] }, "color": { "type": [ "null", "string" ], "description": "Hex color (#RRGGBB) used by the staff badge." } }, "required": [ "id" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "contextParams", "locationId", "status", "activeTabs", "createdAt", "isBookable" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tables/{id}": { "get": { "summary": "Get table details", "tags": [ "Tables" ], "description": "Get a single table by ID with active tabs\n\n**Permissions:** 🔵 `tables.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Table UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique table ID (UUID)" }, "name": { "type": "string", "description": "Table name/number" }, "description": { "type": "string", "nullable": true, "description": "Table description" }, "contextParams": { "type": "object", "additionalProperties": true, "description": "Custom context parameters" }, "locationId": { "type": "number", "description": "Location ID" }, "storefrontUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Full storefront URL for this table" }, "tableGroupId": { "type": "number", "nullable": true, "description": "Table group ID (if grouped)" }, "costCenterId": { "type": "number", "nullable": true, "description": "Cost center ID" }, "status": { "type": "string", "enum": [ "live", "paused", "deleted" ], "description": "Table status" }, "qrCodeImageUrl": { "type": "string", "format": "uri", "nullable": true, "description": "QR code image URL" }, "activeTabs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tab UUID" }, "state": { "type": "string", "description": "Tab state (started, initiated, etc.)" }, "orderTotal": { "type": "number", "description": "Total order amount in cents (legacy field)" }, "paidTotal": { "type": "number", "description": "Total paid amount in cents (legacy field)" }, "tipsTotal": { "type": "number", "description": "Total tips in cents" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "description": "Selected payment flow" }, "coursingOrder": { "type": "number", "nullable": true, "description": "Current coursing level for the tab (items below this level cannot be sent)" }, "memberCount": { "type": "number", "description": "Number of tab_members on this tab (party size for walk-ins)" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents (from tabs table)" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents (from tabs table)" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance in cents" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode" }, "storefrontQrCodeId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/QR code UUID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Tab creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Tab last update timestamp" }, "extras": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tab extras (only in single table endpoint)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kitchen dispatch UUID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "state": { "type": "string", "description": "Dispatch state" }, "tabUUID": { "type": "string", "description": "Tab UUID" }, "tabType": { "type": "string", "description": "Tab type (table, takeaway, etc.)" }, "tableName": { "type": "string", "nullable": true, "description": "Table name if applicable" }, "tabState": { "type": "string", "description": "Current tab state" }, "source": { "type": "string", "nullable": true, "description": "Source channel that created the dispatch (POS, QR, KIOSK, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM)" }, "message": { "type": "string", "nullable": true, "description": "Optional contextual message (e.g., \"Moved from Table 5\")" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text" }, "createdAt": { "type": "string", "format": "date-time", "description": "Comment timestamp" }, "tabMemberUUID": { "type": "string", "nullable": true, "description": "Tab member UUID who made the comment" }, "uuid": { "type": "string", "description": "Comment UUID" } }, "additionalProperties": true }, "description": "Dispatch comments" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kitchen dispatch item UUID" }, "itemId": { "type": "number", "nullable": true, "description": "Item ID from inventory" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications" }, "quantityCents": { "type": "number", "nullable": true, "description": "Item quantity in cents (e.g., 100 = 1.0, 50 = 0.5)" }, "coursingOrder": { "type": "number", "nullable": true, "description": "Coursing level for this item (e.g., 1=appetizer, 2=main, 3=dessert)" }, "isNonSurplus": { "type": "boolean", "description": "Whether item is non-surplus" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "title": { "type": "string", "nullable": true, "description": "Item title" }, "tabMember": { "type": "object", "properties": { "uuid": { "type": "string", "nullable": true, "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" } }, "additionalProperties": true }, "comments": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text" }, "createdAt": { "type": "string", "format": "date-time", "description": "Comment timestamp" }, "tabMemberUUID": { "type": "string", "nullable": true, "description": "Tab member UUID who made the comment" }, "uuid": { "type": "string", "description": "Comment UUID" } }, "additionalProperties": true }, "description": "Item comments" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Variant ID" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "description": "Variant price (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } }, "additionalProperties": true }, "description": "Item variants/modifications" } }, "additionalProperties": true }, "description": "Items in this dispatch" } }, "additionalProperties": true }, "description": "Kitchen dispatches (only in single table endpoint)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "enum": [ "tab", "user" ], "description": "Entity type (tab or user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order for display" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of the user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of the user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "additionalProperties": true }, "description": "Notes attached to this tab" } }, "required": [ "id", "state" ], "additionalProperties": true }, "description": "Active tabs on this table" }, "totalOrderAmountOnActiveTables": { "type": "number", "description": "Total order amount across active tabs" }, "totalPaidAmountOnActiveTables": { "type": "number", "description": "Total paid amount across active tabs" }, "isBookable": { "type": "boolean", "description": "Whether this table accepts bookings" }, "minCapacity": { "type": [ "null", "number" ], "description": "Minimum seating capacity" }, "maxCapacity": { "type": [ "null", "number" ], "description": "Maximum seating capacity" }, "seatingDurationMinutes": { "type": [ "null", "number" ], "description": "Per-table seating duration override (minutes)" }, "newTabPerGuest": { "type": "boolean", "description": "When true, every scan of this QR forces a brand-new tab instead of joining any existing open tab. Use for shared QRs at theme parks, festivals, multi-buyer kiosks, etc." }, "requireGuestCount": { "type": "boolean", "description": "When true, the POS prompts for guest count when seating an empty table, instead of creating a tab silently." }, "assignedRetailerUser": { "type": "object", "nullable": true, "description": "Server currently assigned to this table in POS (null when unassigned).", "properties": { "id": { "type": "number" }, "name": { "type": [ "null", "string" ] }, "color": { "type": [ "null", "string" ], "description": "Hex color (#RRGGBB) used by the staff badge." } }, "required": [ "id" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "contextParams", "locationId", "status", "activeTabs", "createdAt", "isBookable" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update table", "tags": [ "Tables" ], "description": "Update an existing table\n\n**Permissions:** 🟠 `tables.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "nullable": true }, "tableGroupId": { "type": "number", "nullable": true }, "costCenterId": { "type": "number", "nullable": true, "description": "Cost center ID" }, "status": { "type": "string", "enum": [ "live", "paused", "deleted" ] }, "contextParams": { "type": "object", "additionalProperties": true }, "isBookable": { "type": "boolean" }, "minCapacity": { "type": [ "number", "null" ] }, "maxCapacity": { "type": [ "number", "null" ] }, "seatingDurationMinutes": { "type": [ "number", "null" ] }, "newTabPerGuest": { "type": "boolean", "description": "Force a new tab on every scan (theme parks, festivals, shared kiosks)." }, "requireGuestCount": { "type": "boolean", "description": "Prompt POS staff for guest count when seating an empty table." }, "assignedRetailerUserId": { "type": [ "number", "null" ], "description": "Server (retailer_user) to assign to this table. Pass null to clear. Must reference an active retailer_user with access to this location." } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Table UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique table ID (UUID)" }, "name": { "type": "string", "description": "Table name/number" }, "description": { "type": "string", "nullable": true, "description": "Table description" }, "contextParams": { "type": "object", "additionalProperties": true, "description": "Custom context parameters" }, "locationId": { "type": "number", "description": "Location ID" }, "storefrontUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Full storefront URL for this table" }, "tableGroupId": { "type": "number", "nullable": true, "description": "Table group ID (if grouped)" }, "costCenterId": { "type": "number", "nullable": true, "description": "Cost center ID" }, "status": { "type": "string", "enum": [ "live", "paused", "deleted" ], "description": "Table status" }, "qrCodeImageUrl": { "type": "string", "format": "uri", "nullable": true, "description": "QR code image URL" }, "activeTabs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tab UUID" }, "state": { "type": "string", "description": "Tab state (started, initiated, etc.)" }, "orderTotal": { "type": "number", "description": "Total order amount in cents (legacy field)" }, "paidTotal": { "type": "number", "description": "Total paid amount in cents (legacy field)" }, "tipsTotal": { "type": "number", "description": "Total tips in cents" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "description": "Selected payment flow" }, "coursingOrder": { "type": "number", "nullable": true, "description": "Current coursing level for the tab (items below this level cannot be sent)" }, "memberCount": { "type": "number", "description": "Number of tab_members on this tab (party size for walk-ins)" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents (from tabs table)" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents (from tabs table)" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance in cents" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode" }, "storefrontQrCodeId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/QR code UUID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Tab creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Tab last update timestamp" }, "extras": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tab extras (only in single table endpoint)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kitchen dispatch UUID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "state": { "type": "string", "description": "Dispatch state" }, "tabUUID": { "type": "string", "description": "Tab UUID" }, "tabType": { "type": "string", "description": "Tab type (table, takeaway, etc.)" }, "tableName": { "type": "string", "nullable": true, "description": "Table name if applicable" }, "tabState": { "type": "string", "description": "Current tab state" }, "source": { "type": "string", "nullable": true, "description": "Source channel that created the dispatch (POS, QR, KIOSK, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM)" }, "message": { "type": "string", "nullable": true, "description": "Optional contextual message (e.g., \"Moved from Table 5\")" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text" }, "createdAt": { "type": "string", "format": "date-time", "description": "Comment timestamp" }, "tabMemberUUID": { "type": "string", "nullable": true, "description": "Tab member UUID who made the comment" }, "uuid": { "type": "string", "description": "Comment UUID" } }, "additionalProperties": true }, "description": "Dispatch comments" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kitchen dispatch item UUID" }, "itemId": { "type": "number", "nullable": true, "description": "Item ID from inventory" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications" }, "quantityCents": { "type": "number", "nullable": true, "description": "Item quantity in cents (e.g., 100 = 1.0, 50 = 0.5)" }, "coursingOrder": { "type": "number", "nullable": true, "description": "Coursing level for this item (e.g., 1=appetizer, 2=main, 3=dessert)" }, "isNonSurplus": { "type": "boolean", "description": "Whether item is non-surplus" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "title": { "type": "string", "nullable": true, "description": "Item title" }, "tabMember": { "type": "object", "properties": { "uuid": { "type": "string", "nullable": true, "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" } }, "additionalProperties": true }, "comments": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text" }, "createdAt": { "type": "string", "format": "date-time", "description": "Comment timestamp" }, "tabMemberUUID": { "type": "string", "nullable": true, "description": "Tab member UUID who made the comment" }, "uuid": { "type": "string", "description": "Comment UUID" } }, "additionalProperties": true }, "description": "Item comments" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Variant ID" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "description": "Variant price (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } }, "additionalProperties": true }, "description": "Item variants/modifications" } }, "additionalProperties": true }, "description": "Items in this dispatch" } }, "additionalProperties": true }, "description": "Kitchen dispatches (only in single table endpoint)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "enum": [ "tab", "user" ], "description": "Entity type (tab or user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order for display" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of the user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of the user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "additionalProperties": true }, "description": "Notes attached to this tab" } }, "required": [ "id", "state" ], "additionalProperties": true }, "description": "Active tabs on this table" }, "totalOrderAmountOnActiveTables": { "type": "number", "description": "Total order amount across active tabs" }, "totalPaidAmountOnActiveTables": { "type": "number", "description": "Total paid amount across active tabs" }, "isBookable": { "type": "boolean", "description": "Whether this table accepts bookings" }, "minCapacity": { "type": [ "null", "number" ], "description": "Minimum seating capacity" }, "maxCapacity": { "type": [ "null", "number" ], "description": "Maximum seating capacity" }, "seatingDurationMinutes": { "type": [ "null", "number" ], "description": "Per-table seating duration override (minutes)" }, "newTabPerGuest": { "type": "boolean", "description": "When true, every scan of this QR forces a brand-new tab instead of joining any existing open tab. Use for shared QRs at theme parks, festivals, multi-buyer kiosks, etc." }, "requireGuestCount": { "type": "boolean", "description": "When true, the POS prompts for guest count when seating an empty table, instead of creating a tab silently." }, "assignedRetailerUser": { "type": "object", "nullable": true, "description": "Server currently assigned to this table in POS (null when unassigned).", "properties": { "id": { "type": "number" }, "name": { "type": [ "null", "string" ] }, "color": { "type": [ "null", "string" ], "description": "Hex color (#RRGGBB) used by the staff badge." } }, "required": [ "id" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "contextParams", "locationId", "status", "activeTabs", "createdAt", "isBookable" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete table", "tags": [ "Tables" ], "description": "Delete a table (soft delete - sets status to deleted)\n\n**Permissions:** 🔴 `tables.delete`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Table UUID" } ], "responses": { "200": { "description": "Table successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tables/bulk": { "put": { "summary": "Bulk update tables", "tags": [ "Tables" ], "description": "Update multiple tables in a single request. Apply the same changes to all specified tables.\n\n**Permissions:** 🟠 `tables.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tableIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Array of table UUIDs to update" }, "tableGroupId": { "type": "number", "nullable": true, "description": "Table group ID to assign (null to remove from group)" }, "contextParamsToMerge": { "type": "object", "additionalProperties": true, "description": "Context parameters to merge into existing params" }, "contextParamsToDelete": { "type": "array", "items": { "type": "string" }, "description": "Context parameter keys to delete" }, "status": { "type": "string", "enum": [ "live", "paused", "deleted" ], "description": "Status to set on all tables" } }, "required": [ "tableIds" ] } } }, "required": true }, "responses": { "200": { "description": "Tables updated successfully", "content": { "application/json": { "schema": { "description": "Tables updated successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique table ID (UUID)" }, "name": { "type": "string", "description": "Table name/number" }, "description": { "type": "string", "nullable": true, "description": "Table description" }, "contextParams": { "type": "object", "additionalProperties": true, "description": "Custom context parameters" }, "locationId": { "type": "number", "description": "Location ID" }, "storefrontUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Full storefront URL for this table" }, "tableGroupId": { "type": "number", "nullable": true, "description": "Table group ID (if grouped)" }, "costCenterId": { "type": "number", "nullable": true, "description": "Cost center ID" }, "status": { "type": "string", "enum": [ "live", "paused", "deleted" ], "description": "Table status" }, "qrCodeImageUrl": { "type": "string", "format": "uri", "nullable": true, "description": "QR code image URL" }, "activeTabs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tab UUID" }, "state": { "type": "string", "description": "Tab state (started, initiated, etc.)" }, "orderTotal": { "type": "number", "description": "Total order amount in cents (legacy field)" }, "paidTotal": { "type": "number", "description": "Total paid amount in cents (legacy field)" }, "tipsTotal": { "type": "number", "description": "Total tips in cents" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "description": "Selected payment flow" }, "coursingOrder": { "type": "number", "nullable": true, "description": "Current coursing level for the tab (items below this level cannot be sent)" }, "memberCount": { "type": "number", "description": "Number of tab_members on this tab (party size for walk-ins)" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents (from tabs table)" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents (from tabs table)" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance in cents" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode" }, "storefrontQrCodeId": { "type": "string", "format": "uuid", "nullable": true, "description": "Table/QR code UUID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Tab creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Tab last update timestamp" }, "extras": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Tab extras (only in single table endpoint)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kitchen dispatch UUID" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "state": { "type": "string", "description": "Dispatch state" }, "tabUUID": { "type": "string", "description": "Tab UUID" }, "tabType": { "type": "string", "description": "Tab type (table, takeaway, etc.)" }, "tableName": { "type": "string", "nullable": true, "description": "Table name if applicable" }, "tabState": { "type": "string", "description": "Current tab state" }, "source": { "type": "string", "nullable": true, "description": "Source channel that created the dispatch (POS, QR, KIOSK, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM)" }, "message": { "type": "string", "nullable": true, "description": "Optional contextual message (e.g., \"Moved from Table 5\")" }, "comments": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text" }, "createdAt": { "type": "string", "format": "date-time", "description": "Comment timestamp" }, "tabMemberUUID": { "type": "string", "nullable": true, "description": "Tab member UUID who made the comment" }, "uuid": { "type": "string", "description": "Comment UUID" } }, "additionalProperties": true }, "description": "Dispatch comments" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Kitchen dispatch item UUID" }, "itemId": { "type": "number", "nullable": true, "description": "Item ID from inventory" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications" }, "quantityCents": { "type": "number", "nullable": true, "description": "Item quantity in cents (e.g., 100 = 1.0, 50 = 0.5)" }, "coursingOrder": { "type": "number", "nullable": true, "description": "Coursing level for this item (e.g., 1=appetizer, 2=main, 3=dessert)" }, "isNonSurplus": { "type": "boolean", "description": "Whether item is non-surplus" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "title": { "type": "string", "nullable": true, "description": "Item title" }, "tabMember": { "type": "object", "properties": { "uuid": { "type": "string", "nullable": true, "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" } }, "additionalProperties": true }, "comments": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "string", "description": "Comment text" }, "createdAt": { "type": "string", "format": "date-time", "description": "Comment timestamp" }, "tabMemberUUID": { "type": "string", "nullable": true, "description": "Tab member UUID who made the comment" }, "uuid": { "type": "string", "description": "Comment UUID" } }, "additionalProperties": true }, "description": "Item comments" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Variant ID" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "description": "Variant price (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } }, "additionalProperties": true }, "description": "Item variants/modifications" } }, "additionalProperties": true }, "description": "Items in this dispatch" } }, "additionalProperties": true }, "description": "Kitchen dispatches (only in single table endpoint)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "enum": [ "tab", "user" ], "description": "Entity type (tab or user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order for display" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of the user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user ID who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of the user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "additionalProperties": true }, "description": "Notes attached to this tab" } }, "required": [ "id", "state" ], "additionalProperties": true }, "description": "Active tabs on this table" }, "totalOrderAmountOnActiveTables": { "type": "number", "description": "Total order amount across active tabs" }, "totalPaidAmountOnActiveTables": { "type": "number", "description": "Total paid amount across active tabs" }, "isBookable": { "type": "boolean", "description": "Whether this table accepts bookings" }, "minCapacity": { "type": [ "null", "number" ], "description": "Minimum seating capacity" }, "maxCapacity": { "type": [ "null", "number" ], "description": "Maximum seating capacity" }, "seatingDurationMinutes": { "type": [ "null", "number" ], "description": "Per-table seating duration override (minutes)" }, "newTabPerGuest": { "type": "boolean", "description": "When true, every scan of this QR forces a brand-new tab instead of joining any existing open tab. Use for shared QRs at theme parks, festivals, multi-buyer kiosks, etc." }, "requireGuestCount": { "type": "boolean", "description": "When true, the POS prompts for guest count when seating an empty table, instead of creating a tab silently." }, "assignedRetailerUser": { "type": "object", "nullable": true, "description": "Server currently assigned to this table in POS (null when unassigned).", "properties": { "id": { "type": "number" }, "name": { "type": [ "null", "string" ] }, "color": { "type": [ "null", "string" ], "description": "Hex color (#RRGGBB) used by the staff badge." } }, "required": [ "id" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": [ "null", "string" ], "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "name", "contextParams", "locationId", "status", "activeTabs", "createdAt", "isBookable" ] }, "description": "Updated tables" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tab/{tabId}/payment-methods": { "get": { "summary": "Get Adyen payment methods", "tags": [ "Tabs" ], "description": "Returns available Adyen payment methods for the Advanced flow. No purchase is created.", "parameters": [ { "schema": { "type": "number", "minimum": 0 }, "in": "query", "name": "amountCents", "required": true, "description": "Payment amount in cents. 0 is a valid value: the storefront still hits this endpoint when the cart nets to 0 (voucher fully covers the order) and the handler short-circuits with an empty paymentMethodsResponse so the drawer can route to the complimentary settlement path without a PSP method selection." }, { "schema": { "type": "string" }, "in": "query", "name": "currencyCode", "required": true, "description": "ISO 4217 currency code (e.g. SEK, EUR)" }, { "schema": { "type": "string" }, "in": "query", "name": "countryCode", "required": false, "description": "ISO 3166-1 alpha-2 country code (e.g. SE, NL)" }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "tabMemberId", "required": false, "description": "Optional tab member UUID. When supplied, the handler resolves the paying user and includes a shopperReference so Adyen returns storedPaymentMethods (saved cards) for the shopper. Omit for guest checkouts." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Payment methods fetched successfully", "content": { "application/json": { "schema": { "description": "Payment methods fetched successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "additionalProperties": true, "properties": { "paymentMethodsResponse": { "type": "object", "additionalProperties": true, "description": "Adyen paymentMethodsResponse object" }, "clientKey": { "type": "string", "description": "Adyen client key for Drop-in/Components" }, "environment": { "type": "string", "enum": [ "test", "live" ], "description": "Adyen environment" }, "freeOrder": { "type": "boolean", "description": "True when amountCents=0 and no PSP picker is needed — drawer should auto-submit the intent for complimentary settlement." } } }, "meta": { "type": "object" } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tab/cancel": { "post": { "summary": "Cancel tab payment", "tags": [ "Tabs" ], "description": "Cancel a pending tab payment by purchase intent ID\n\n**Permissions:** 🟠 `tabs.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "purchase_intent_id" ], "properties": { "purchase_intent_id": { "type": "string", "format": "uuid", "description": "Purchase intent ID to cancel" } } } } }, "required": true }, "responses": { "200": { "description": "Payment canceled successfully", "content": { "application/json": { "schema": { "description": "Payment canceled successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchase_intent_id": { "type": "string", "format": "uuid" }, "tab_settlement_id": { "type": "string", "format": "uuid" }, "tab_id": { "type": "string", "format": "uuid" }, "canceled": { "type": "boolean" } } }, "meta": { "type": "object" } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tab/cancel-all": { "post": { "summary": "Cancel all tab payments", "tags": [ "Tabs" ], "description": "Cancel all pending payments for a specific tab\n\n**Permissions:** 🟠 `tabs.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "tab_id" ], "properties": { "tab_id": { "type": "string", "format": "uuid", "description": "Tab ID to cancel all payments for" } } } } }, "required": true }, "responses": { "200": { "description": "All payments canceled successfully", "content": { "application/json": { "schema": { "description": "All payments canceled successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tab_id": { "type": "string", "format": "uuid" }, "canceled_count": { "type": "number" }, "purchase_intent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "meta": { "type": "object" } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tab/pay": { "post": { "summary": "Pay for tab", "tags": [ "Tabs" ], "description": "Process a payment for a tab using various payment methods\n\n**Permissions:** 🟠 `tabs.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "tab_id", "payment_method" ], "properties": { "tab_id": { "type": "string", "format": "uuid", "description": "UUID of the tab to pay for" }, "tab_member_id": { "type": "string", "description": "ID of the tab member making the payment (UUID). Optional - will be auto-resolved from JWT token if not provided." }, "payment_method": { "type": "string", "enum": [ "prepaid", "invoice", "swish", "terminal", "online", "gift_card" ], "description": "Payment method to use" }, "kitchen_dispatch_items": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of kitchen dispatch item IDs to pay for (ITEM mode)" }, "amount_cents": { "type": "number", "minimum": 0, "description": "Amount to pay in cents (AMOUNT mode or triggers mode switch)" }, "terminal_id": { "type": "string", "format": "uuid", "description": "Terminal ID (required for terminal payments)" }, "return_url": { "type": "string", "format": "uri", "description": "Return URL after payment (required for online/swish payments)" }, "tip_amount_cents": { "type": "number", "minimum": 0, "default": 0, "description": "Tip amount in cents" }, "metadata": { "type": "object", "description": "Additional metadata for the payment" }, "voucher_codes": { "type": "array", "items": { "type": "string" }, "description": "Voucher codes to apply to the payment" }, "recipient_id": { "type": "string", "format": "uuid", "description": "Invoice recipient UUID (for invoice payments)" }, "gift_card_code": { "type": "string", "description": "Gift card code for gift_card payment method (format: XXXX-XXXX-XXXX)" }, "payment_data": { "type": "object", "additionalProperties": true, "description": "Adyen payment method data from Drop-in/Components (triggers Advanced flow when present)" }, "cancel_existing_payment": { "type": "boolean", "description": "User confirmed: cancel the in-progress Adyen CS payment and start a new one" }, "save_payment_method": { "type": "boolean", "description": "When true, persist the card token after Adyen Authorised so the user can re-use it. Default false. Honored when location has the instant_pay_v2 feature flag enabled." }, "selected_saved_payment_method_id": { "type": "string", "description": "UUID of a previously saved payment method to charge. Forwarded to payment-service alongside the Adyen Advanced PSP payload." } } } } }, "required": true }, "responses": { "200": { "description": "Payment initiated successfully", "content": { "application/json": { "schema": { "description": "Payment initiated successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchase_intent_id": { "type": "string", "format": "uuid" }, "tab_settlement_id": { "type": "string", "format": "uuid" }, "payment_method": { "type": "string" }, "payment_mode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ] }, "mode_switched": { "type": "boolean" }, "terminal_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Terminal ID for cancel functionality" }, "complimentary": { "type": "boolean", "description": "True when the server converted a 0 kr terminal request into a complimentary prepaid purchase (voucher-covered tab). terminal_id will be null and the payment is already sync-confirmed — no terminal-awaiting UI or card receipt should be shown." }, "psp_response": { "type": "object", "additionalProperties": true, "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "pspCheckoutResponse": { "type": "object", "additionalProperties": true, "properties": { "providedKarmaRef": { "type": "string" }, "pspInstruction": { "type": "object", "additionalProperties": true, "properties": { "psp": { "type": "string" }, "sessionData": { "type": "string" }, "sessionId": { "type": "string" }, "type": { "type": "string" } } }, "pspPaymentRequestId": { "type": "string" } } }, "checkoutUrl": { "type": "string" }, "checkoutUrlFallback": { "type": "object", "properties": { "purchaseIntentId": { "type": "string" }, "qrCodeSvgBase64": { "type": "string" } } }, "softpayRequestId": { "type": "string", "nullable": true, "description": "Softpay request ID for softpos terminal payments" } } } } }, "meta": { "type": "object" } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tab/pay/details": { "post": { "summary": "Submit Adyen payment details", "tags": [ "Tabs" ], "description": "Submit additional payment details (3DS, redirect) for an existing Adyen Advanced flow purchase.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "purchase_intent_id", "details" ], "properties": { "purchase_intent_id": { "type": "string", "format": "uuid", "description": "Purchase intent ID from the initial /tab/pay response" }, "details": { "type": "object", "additionalProperties": true, "description": "Adyen payment details object (from onAdditionalDetails callback)" } } } } }, "required": true }, "responses": { "200": { "description": "Payment details processed successfully", "content": { "application/json": { "schema": { "description": "Payment details processed successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "resultCode": { "type": "string", "description": "Adyen result code (Authorised, Refused, etc.)" }, "action": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Additional action required (another 3DS step)" }, "pspReference": { "type": "string", "nullable": true, "description": "Adyen PSP reference" } } }, "meta": { "type": "object" } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tab/recalculate": { "post": { "summary": "Recalculate tab balance", "tags": [ "Tabs" ], "description": "Recalculate tab balance from source of truth (kitchen dispatch items and purchases). Useful for fixing tabs with incorrect balance values.\n\n**Permissions:** 🟠 `tabs.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "tab_id" ], "properties": { "tab_id": { "type": "string", "format": "uuid", "description": "Tab ID to recalculate balance for" } } } } }, "required": true }, "responses": { "200": { "description": "Tab balance recalculated successfully", "content": { "application/json": { "schema": { "description": "Tab balance recalculated successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tab_id": { "type": "string", "format": "uuid" }, "total_amount_cents": { "type": "number", "description": "Recalculated total amount from kitchen dispatch items" }, "paid_amount_cents": { "type": "number", "description": "Recalculated paid amount from purchases" }, "remaining_balance_cents": { "type": "number", "description": "Calculated remaining balance (total - paid)" }, "item_count": { "type": "number", "description": "Number of kitchen dispatch items found" }, "purchase_count": { "type": "number", "description": "Number of confirmed purchases found" }, "previous_total": { "type": "number", "description": "Previous total_amount_cents value" }, "previous_paid": { "type": "number", "description": "Previous paid_amount_cents value" }, "total_changed": { "type": "boolean", "description": "Whether total amount was changed" }, "paid_changed": { "type": "boolean", "description": "Whether paid amount was changed" } } }, "meta": { "type": "object" } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs": { "get": { "summary": "List tabs", "tags": [ "Tabs" ], "description": "List tabs with optional filtering\n\n**Permissions:** 🔵 `tabs.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "string", "enum": [ "initiated", "started", "instant", "closed", "settled", "aborted", "action_required" ] }, "in": "query", "name": "state", "required": false, "description": "Filter by tab state" }, { "schema": { "type": "string" }, "in": "query", "name": "storefrontQrCodeId", "required": false, "description": "Filter by table/QR code UUID" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabs": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "latestState": { "type": "string", "enum": [ "initiated", "started", "instant", "closed", "settled", "aborted", "action_required" ], "description": "Current tab state" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "enum": [ "open_tab", "pay_upfront" ], "description": "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" }, "paymentSplit": { "type": "number", "nullable": true, "minimum": 2, "maximum": 10, "description": "Number of splits when in AMOUNT mode (2-10), null when in ITEM mode" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance to be paid in cents" }, "storefrontQrCodeId": { "type": "string", "nullable": true, "description": "Table/QR code UUID if applicable" }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation." }, "bookingConfirmationCode": { "type": "string", "nullable": true, "description": "Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page." }, "tabMembers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "storefrontSessionId": { "type": "string", "nullable": true, "description": "Storefront session ID" }, "initiator": { "type": "boolean", "description": "Whether this member initiated the tab" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retail user ID if applicable" }, "clientId": { "type": "string", "nullable": true, "description": "Client identifier (user UUID for identification)" }, "userEmail": { "type": "string", "nullable": true, "description": "User email (canonical, never overridden per-location)" }, "userName": { "type": "string", "nullable": true, "description": "Override-merged display name (falls back through retailer.name → ulo.display_name → users.name)" }, "isEnrolledInLoyalty": { "type": "boolean", "description": "Whether user is enrolled in location loyalty program" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "initiator", "memberType", "isEnrolledInLoyalty", "createdAt", "updatedAt" ] }, "description": "Tab members" }, "memberCount": { "type": "number", "description": "Number of guest tab_members (party size; excludes staff)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "latestState": { "type": "string", "description": "Current state of the dispatch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch item UUID" }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "itemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "tabMemberId": { "type": "string", "nullable": true, "description": "Tab member UUID who ordered this" }, "parentKitchenDispatchItemId": { "type": "string", "nullable": true, "description": "Parent kitchen dispatch item UUID (for nested items)" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications in cents" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "quantity": { "type": "number", "description": "Quantity ordered" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (for fractional items)" }, "splitOfKdi": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of original item if this is a split item (for grouping)" }, "tabSettlementId": { "type": "string", "nullable": true, "description": "Settlement UUID if paid" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state (payment_in_progress, settled)" }, "status": { "type": "string", "nullable": true, "description": "Item status" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "paidAmount": { "type": "number", "nullable": true, "description": "Amount paid for this item in cents" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "itemTitle": { "type": "string", "nullable": true, "description": "Item title from inventory" }, "itemTitlePrep": { "type": "string", "nullable": true, "description": "Item prep name from inventory" }, "itemDescription": { "type": "string", "nullable": true, "description": "Item description from inventory" }, "itemImageUrl": { "type": "string", "nullable": true, "description": "Item image URL from inventory" }, "tabMember": { "type": "object", "nullable": true, "description": "Guest/user information for the person who ordered this item", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" }, "phone": { "type": "string", "description": "Member phone number" }, "imageUrl": { "type": "string", "description": "Member profile image URL" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated user" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retailer user ID if staff member" } } }, "comments": { "type": "array", "description": "Comments on this item", "items": { "type": "object", "properties": { "comment": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "tabMemberUUID": { "type": "string", "nullable": true }, "uuid": { "type": "string", "format": "uuid" } } } }, "variants": { "type": "array", "description": "Variants/modifications on this item", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number", "description": "Price in cents (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } } } } }, "required": [ "uuid", "kitchenDispatchId", "price", "basePrice", "quantity", "createdAt", "updatedAt" ] }, "description": "Items in this dispatch" } }, "required": [ "uuid", "tabId", "locationId", "latestState", "createdAt", "updatedAt", "kitchenDispatchItems" ] }, "description": "Kitchen dispatches with items" }, "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "tab_vouchers.id (use with DELETE /vouchers/applied/:id)" }, "discountId": { "type": "number", "description": "discounts.id" }, "discountCode": { "type": "string", "description": "Voucher code as entered" }, "appliedAt": { "type": "string", "format": "date-time" }, "voucherName": { "type": "string", "nullable": true, "description": "discounts.name (internal name)" }, "voucherType": { "type": "string", "nullable": true }, "typeSpecification": { "type": "object", "nullable": true, "additionalProperties": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "hasUsesLeft": { "type": "boolean", "description": "Computed: maxUses null/0 OR timesUsed < maxUses" }, "remainingBalanceCents": { "type": "number", "nullable": true, "description": "For gift cards" }, "displayTitle": { "type": "string", "nullable": true, "description": "Guest-facing title" }, "displayDescription": { "type": "string", "nullable": true, "description": "Guest-facing description" }, "displayImageUrl": { "type": "string", "nullable": true, "description": "Thumbnail URL" } }, "required": [ "id", "discountId", "discountCode", "appliedAt", "timesUsed", "hasUsesLeft" ] }, "description": "Vouchers attached to this tab (from POS or storefront)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "description": "Entity type (tab, user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order (0 = first/top)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] }, "description": "Notes attached to this tab" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "locationId", "latestState", "paymentMode", "totalAmountCents", "paidAmountCents", "remainingBalanceCents", "tabMembers", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "tabs", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}": { "get": { "summary": "Get tab details", "tags": [ "Tabs" ], "description": "Get a single tab by ID with members and kitchen dispatch items\n\n**Permissions:** 🔵 `tabs.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "latestState": { "type": "string", "enum": [ "initiated", "started", "instant", "closed", "settled", "aborted", "action_required" ], "description": "Current tab state" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "enum": [ "open_tab", "pay_upfront" ], "description": "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" }, "paymentSplit": { "type": "number", "nullable": true, "minimum": 2, "maximum": 10, "description": "Number of splits when in AMOUNT mode (2-10), null when in ITEM mode" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance to be paid in cents" }, "storefrontQrCodeId": { "type": "string", "nullable": true, "description": "Table/QR code UUID if applicable" }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation." }, "bookingConfirmationCode": { "type": "string", "nullable": true, "description": "Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page." }, "tabMembers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "storefrontSessionId": { "type": "string", "nullable": true, "description": "Storefront session ID" }, "initiator": { "type": "boolean", "description": "Whether this member initiated the tab" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retail user ID if applicable" }, "clientId": { "type": "string", "nullable": true, "description": "Client identifier (user UUID for identification)" }, "userEmail": { "type": "string", "nullable": true, "description": "User email (canonical, never overridden per-location)" }, "userName": { "type": "string", "nullable": true, "description": "Override-merged display name (falls back through retailer.name → ulo.display_name → users.name)" }, "isEnrolledInLoyalty": { "type": "boolean", "description": "Whether user is enrolled in location loyalty program" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "initiator", "memberType", "isEnrolledInLoyalty", "createdAt", "updatedAt" ] }, "description": "Tab members" }, "memberCount": { "type": "number", "description": "Number of guest tab_members (party size; excludes staff)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "latestState": { "type": "string", "description": "Current state of the dispatch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch item UUID" }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "itemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "tabMemberId": { "type": "string", "nullable": true, "description": "Tab member UUID who ordered this" }, "parentKitchenDispatchItemId": { "type": "string", "nullable": true, "description": "Parent kitchen dispatch item UUID (for nested items)" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications in cents" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "quantity": { "type": "number", "description": "Quantity ordered" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (for fractional items)" }, "splitOfKdi": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of original item if this is a split item (for grouping)" }, "tabSettlementId": { "type": "string", "nullable": true, "description": "Settlement UUID if paid" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state (payment_in_progress, settled)" }, "status": { "type": "string", "nullable": true, "description": "Item status" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "paidAmount": { "type": "number", "nullable": true, "description": "Amount paid for this item in cents" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "itemTitle": { "type": "string", "nullable": true, "description": "Item title from inventory" }, "itemTitlePrep": { "type": "string", "nullable": true, "description": "Item prep name from inventory" }, "itemDescription": { "type": "string", "nullable": true, "description": "Item description from inventory" }, "itemImageUrl": { "type": "string", "nullable": true, "description": "Item image URL from inventory" }, "tabMember": { "type": "object", "nullable": true, "description": "Guest/user information for the person who ordered this item", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" }, "phone": { "type": "string", "description": "Member phone number" }, "imageUrl": { "type": "string", "description": "Member profile image URL" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated user" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retailer user ID if staff member" } } }, "comments": { "type": "array", "description": "Comments on this item", "items": { "type": "object", "properties": { "comment": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "tabMemberUUID": { "type": "string", "nullable": true }, "uuid": { "type": "string", "format": "uuid" } } } }, "variants": { "type": "array", "description": "Variants/modifications on this item", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number", "description": "Price in cents (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } } } } }, "required": [ "uuid", "kitchenDispatchId", "price", "basePrice", "quantity", "createdAt", "updatedAt" ] }, "description": "Items in this dispatch" } }, "required": [ "uuid", "tabId", "locationId", "latestState", "createdAt", "updatedAt", "kitchenDispatchItems" ] }, "description": "Kitchen dispatches with items" }, "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "tab_vouchers.id (use with DELETE /vouchers/applied/:id)" }, "discountId": { "type": "number", "description": "discounts.id" }, "discountCode": { "type": "string", "description": "Voucher code as entered" }, "appliedAt": { "type": "string", "format": "date-time" }, "voucherName": { "type": "string", "nullable": true, "description": "discounts.name (internal name)" }, "voucherType": { "type": "string", "nullable": true }, "typeSpecification": { "type": "object", "nullable": true, "additionalProperties": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "hasUsesLeft": { "type": "boolean", "description": "Computed: maxUses null/0 OR timesUsed < maxUses" }, "remainingBalanceCents": { "type": "number", "nullable": true, "description": "For gift cards" }, "displayTitle": { "type": "string", "nullable": true, "description": "Guest-facing title" }, "displayDescription": { "type": "string", "nullable": true, "description": "Guest-facing description" }, "displayImageUrl": { "type": "string", "nullable": true, "description": "Thumbnail URL" } }, "required": [ "id", "discountId", "discountCode", "appliedAt", "timesUsed", "hasUsesLeft" ] }, "description": "Vouchers attached to this tab (from POS or storefront)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "description": "Entity type (tab, user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order (0 = first/top)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] }, "description": "Notes attached to this tab" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "locationId", "latestState", "paymentMode", "totalAmountCents", "paidAmountCents", "remainingBalanceCents", "tabMembers", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}/close": { "post": { "summary": "Close a tab", "tags": [ "Tabs" ], "description": "Close a tab by setting its state to closed or aborted. Use force=true to close any tab regardless of state.\n\n**Permissions:** 🟠 `tabs.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "description": "Optional comment explaining why the tab is being closed" }, "force": { "type": "boolean", "description": "If true, forces the tab to close (state becomes \"aborted\"). If false, normal close (state becomes \"closed\") and only works on non-closed tabs", "default": false } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "latestState": { "type": "string", "enum": [ "initiated", "started", "instant", "closed", "settled", "aborted", "action_required" ], "description": "Current tab state" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "enum": [ "open_tab", "pay_upfront" ], "description": "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" }, "paymentSplit": { "type": "number", "nullable": true, "minimum": 2, "maximum": 10, "description": "Number of splits when in AMOUNT mode (2-10), null when in ITEM mode" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance to be paid in cents" }, "storefrontQrCodeId": { "type": "string", "nullable": true, "description": "Table/QR code UUID if applicable" }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation." }, "bookingConfirmationCode": { "type": "string", "nullable": true, "description": "Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page." }, "tabMembers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "storefrontSessionId": { "type": "string", "nullable": true, "description": "Storefront session ID" }, "initiator": { "type": "boolean", "description": "Whether this member initiated the tab" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retail user ID if applicable" }, "clientId": { "type": "string", "nullable": true, "description": "Client identifier (user UUID for identification)" }, "userEmail": { "type": "string", "nullable": true, "description": "User email (canonical, never overridden per-location)" }, "userName": { "type": "string", "nullable": true, "description": "Override-merged display name (falls back through retailer.name → ulo.display_name → users.name)" }, "isEnrolledInLoyalty": { "type": "boolean", "description": "Whether user is enrolled in location loyalty program" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "initiator", "memberType", "isEnrolledInLoyalty", "createdAt", "updatedAt" ] }, "description": "Tab members" }, "memberCount": { "type": "number", "description": "Number of guest tab_members (party size; excludes staff)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "latestState": { "type": "string", "description": "Current state of the dispatch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch item UUID" }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "itemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "tabMemberId": { "type": "string", "nullable": true, "description": "Tab member UUID who ordered this" }, "parentKitchenDispatchItemId": { "type": "string", "nullable": true, "description": "Parent kitchen dispatch item UUID (for nested items)" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications in cents" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "quantity": { "type": "number", "description": "Quantity ordered" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (for fractional items)" }, "splitOfKdi": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of original item if this is a split item (for grouping)" }, "tabSettlementId": { "type": "string", "nullable": true, "description": "Settlement UUID if paid" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state (payment_in_progress, settled)" }, "status": { "type": "string", "nullable": true, "description": "Item status" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "paidAmount": { "type": "number", "nullable": true, "description": "Amount paid for this item in cents" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "itemTitle": { "type": "string", "nullable": true, "description": "Item title from inventory" }, "itemTitlePrep": { "type": "string", "nullable": true, "description": "Item prep name from inventory" }, "itemDescription": { "type": "string", "nullable": true, "description": "Item description from inventory" }, "itemImageUrl": { "type": "string", "nullable": true, "description": "Item image URL from inventory" }, "tabMember": { "type": "object", "nullable": true, "description": "Guest/user information for the person who ordered this item", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" }, "phone": { "type": "string", "description": "Member phone number" }, "imageUrl": { "type": "string", "description": "Member profile image URL" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated user" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retailer user ID if staff member" } } }, "comments": { "type": "array", "description": "Comments on this item", "items": { "type": "object", "properties": { "comment": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "tabMemberUUID": { "type": "string", "nullable": true }, "uuid": { "type": "string", "format": "uuid" } } } }, "variants": { "type": "array", "description": "Variants/modifications on this item", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number", "description": "Price in cents (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } } } } }, "required": [ "uuid", "kitchenDispatchId", "price", "basePrice", "quantity", "createdAt", "updatedAt" ] }, "description": "Items in this dispatch" } }, "required": [ "uuid", "tabId", "locationId", "latestState", "createdAt", "updatedAt", "kitchenDispatchItems" ] }, "description": "Kitchen dispatches with items" }, "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "tab_vouchers.id (use with DELETE /vouchers/applied/:id)" }, "discountId": { "type": "number", "description": "discounts.id" }, "discountCode": { "type": "string", "description": "Voucher code as entered" }, "appliedAt": { "type": "string", "format": "date-time" }, "voucherName": { "type": "string", "nullable": true, "description": "discounts.name (internal name)" }, "voucherType": { "type": "string", "nullable": true }, "typeSpecification": { "type": "object", "nullable": true, "additionalProperties": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "hasUsesLeft": { "type": "boolean", "description": "Computed: maxUses null/0 OR timesUsed < maxUses" }, "remainingBalanceCents": { "type": "number", "nullable": true, "description": "For gift cards" }, "displayTitle": { "type": "string", "nullable": true, "description": "Guest-facing title" }, "displayDescription": { "type": "string", "nullable": true, "description": "Guest-facing description" }, "displayImageUrl": { "type": "string", "nullable": true, "description": "Thumbnail URL" } }, "required": [ "id", "discountId", "discountCode", "appliedAt", "timesUsed", "hasUsesLeft" ] }, "description": "Vouchers attached to this tab (from POS or storefront)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "description": "Entity type (tab, user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order (0 = first/top)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] }, "description": "Notes attached to this tab" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "locationId", "latestState", "paymentMode", "totalAmountCents", "paidAmountCents", "remainingBalanceCents", "tabMembers", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}/coursing": { "patch": { "summary": "Advance tab coursing", "tags": [ "Tabs" ], "description": "Advance the coursing order for a tab. If coursingOrder is provided in the body, sets to that specific value. Otherwise, advances to the next available coursing level from the location's coursings. Used for POS coursing feature to control when items from each course can be sent to the kitchen.\n\n**Permissions:** 🟠 `tabs.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "coursingOrder": { "type": "number", "nullable": true, "description": "Specific coursing order to set. If omitted, advances to the next available coursing level." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "previousCoursingOrder": { "type": "number", "nullable": true, "description": "Previous coursing order value" }, "coursingOrder": { "type": "number", "nullable": true, "description": "New coursing order value" }, "coursingTitle": { "type": "string", "nullable": true, "description": "Title of the new coursing level (e.g., \"Appetizers\", \"Main Course\")" } }, "required": [ "tabId", "previousCoursingOrder", "coursingOrder" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}/debug": { "get": { "summary": "Debug: single tab", "tags": [ "Tabs" ], "description": "Debug endpoint for a specific tab with detailed balance verification, per-item allocation breakdowns, and per-purchase line item details. Useful for diagnosing individual tab balance issues.\n\n**Permissions:** 🔵 `tabs.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Detailed debug info for a single tab", "content": { "application/json": { "schema": { "description": "Detailed debug info for a single tab", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tab": { "type": "object", "additionalProperties": true }, "balance": { "type": "object", "additionalProperties": true }, "summary": { "type": "object", "additionalProperties": true }, "verification": { "type": "object", "additionalProperties": true }, "purchases": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}/join": { "post": { "summary": "Join a tab by its UUID", "tags": [ "Tabs" ], "description": "Join a specific tab directly by UUID — no QR code required.\n\nUsed by the direct tab link feature (?tab=UUID in storefront-web).\nReturns 400 if the tab is closed/settled.\nIdempotent — safe to call multiple times with the same identifier.\n\n**Permissions:** 🔵 `tabs.read`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tabMember": { "type": "object", "description": "User identification using priority system", "properties": { "id": { "type": "number", "description": "User ID (authenticated users, priority 1)" }, "email": { "type": "string", "format": "email", "description": "Email address (priority 2)" }, "phone": { "type": "string", "description": "Phone number (priority 3)" }, "identifier": { "type": "string", "description": "Device identifier (priority 4)" } } } }, "required": [ "tabMember" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "tabMemberId": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "isNewMember": { "type": "boolean", "description": "True if newly joined, false if already a member" }, "tabState": { "type": "string", "description": "Current tab state" } }, "required": [ "tabId", "tabMemberId", "isNewMember", "tabState" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}/members": { "post": { "summary": "Add a member to a tab", "tags": [ "Tabs" ], "description": "Add a user as a member to an existing tab. Looks up user by userId (priority 1), email (priority 2), or phone (priority 3). If user is already a member, returns existing member. Useful for POS \"Add Loyalty Member\" functionality.\n\n**Permissions:** 🟠 `tabs.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "number", "description": "User ID (Priority 1 - direct lookup)" }, "email": { "type": "string", "format": "email", "description": "Email address (Priority 2 - lookup by email)" }, "phone": { "type": "string", "description": "Phone number (Priority 3 - lookup by phone)" } }, "additionalProperties": false, "description": "At least one of userId, email, or phone is required. Resolution priority: userId > email > phone" } } }, "description": "At least one of userId, email, or phone is required. Resolution priority: userId > email > phone" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabMember": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "storefrontSessionId": { "type": "string", "nullable": true, "description": "Storefront session ID" }, "initiator": { "type": "boolean", "description": "Whether this member initiated the tab" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retail user ID if applicable" }, "clientId": { "type": "string", "nullable": true, "description": "Client identifier (user UUID for identification)" }, "userEmail": { "type": "string", "nullable": true, "description": "User email (canonical, never overridden per-location)" }, "userName": { "type": "string", "nullable": true, "description": "Override-merged display name (falls back through retailer.name → ulo.display_name → users.name)" }, "isEnrolledInLoyalty": { "type": "boolean", "description": "Whether user is enrolled in location loyalty program" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "initiator", "memberType", "isEnrolledInLoyalty", "createdAt", "updatedAt" ] }, "isNewMember": { "type": "boolean", "description": "True if member was newly created, false if already existed" }, "user": { "type": "object", "nullable": true, "properties": { "id": { "type": "number", "description": "User ID" }, "email": { "type": "string", "nullable": true, "description": "User email" }, "name": { "type": "string", "nullable": true, "description": "User name" }, "phone": { "type": "string", "nullable": true, "description": "User phone" } }, "required": [ "id" ] } }, "required": [ "tabMember", "isNewMember", "user" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}/members/{memberUuid}": { "delete": { "summary": "Remove a tab member", "tags": [ "Tabs" ], "description": "Delete a tab member row. Refuses with 409 MEMBER_HAS_ORDERS when the member is referenced by any kitchen dispatch, settlement, voucher reservation, purchase, or comment (history is never cascade-deleted). Refuses with 409 CANNOT_REMOVE_INITIATOR for the initiator member. Use this from the POS guests tab to remove guests added by mistake.\n\n**Permissions:** 🟠 `tabs.update`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "memberUuid", "required": true, "description": "Tab member UUID to remove" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "removed": { "type": "boolean", "enum": [ true ] }, "memberUuid": { "type": "string", "format": "uuid" } }, "required": [ "removed", "memberUuid" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}/members/{memberUuid}/contact": { "patch": { "summary": "Upsert guest contact on a tab member", "tags": [ "Tabs" ], "description": "Overwrite email/phone/name on the user row attached to an anonymous tab member. Mirrors the kiosk-commit contact-overwrite semantics so a kiosk pay-upfront flow can record the guest's email before payment (avoiding \"no recipient address on file\" skips on the receipt-email cloud function). Registered accounts (users.guest=false) are refused — use the identify endpoint for those.\n\n**Permissions:** 🟠 `tabs.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Guest email (overwrites existing non-empty value)" }, "phone": { "type": "string", "description": "Guest phone (overwrites existing non-empty value)" }, "name": { "type": "string", "description": "Guest name (overwrites existing non-empty value)" } }, "additionalProperties": false, "description": "At least one of email, phone, or name is required. Non-empty fields are written to the tab member's user row; empty fields are ignored. Only applies to anonymous guest users (users.guest=true)." } } }, "description": "At least one of email, phone, or name is required. Non-empty fields are written to the tab member's user row; empty fields are ignored. Only applies to anonymous guest users (users.guest=true)." }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "memberUuid", "required": true, "description": "Tab member UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabMember": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "userId": { "type": "number" } }, "required": [ "uuid", "userId" ], "additionalProperties": false }, "user": { "type": "object", "properties": { "id": { "type": "number" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "tabMember", "user" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}/members/{memberUuid}/identify": { "patch": { "summary": "Identify an anonymous tab member", "tags": [ "Tabs" ], "description": "Link an anonymous tab member to a known user. Looks up user by userId (priority 1), email (priority 2), or phone (priority 3), then updates the tab member record to associate with that user. Useful for POS \"Identify Guest\" functionality when an anonymous guest needs to be linked to their loyalty account.\n\n**Permissions:** 🟠 `tabs.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "number", "description": "User ID (Priority 1 - direct lookup)" }, "email": { "type": "string", "format": "email", "description": "Email address (Priority 2 - lookup by email)" }, "phone": { "type": "string", "description": "Phone number (Priority 3 - lookup by phone)" } }, "additionalProperties": false, "description": "At least one of userId, email, or phone is required. Resolution priority: userId > email > phone" } } }, "description": "At least one of userId, email, or phone is required. Resolution priority: userId > email > phone" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "memberUuid", "required": true, "description": "Tab member UUID to identify" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabMember": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "storefrontSessionId": { "type": "string", "nullable": true, "description": "Storefront session ID" }, "initiator": { "type": "boolean", "description": "Whether this member initiated the tab" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retail user ID if applicable" }, "clientId": { "type": "string", "nullable": true, "description": "Client identifier (user UUID for identification)" }, "userEmail": { "type": "string", "nullable": true, "description": "User email (canonical, never overridden per-location)" }, "userName": { "type": "string", "nullable": true, "description": "Override-merged display name (falls back through retailer.name → ulo.display_name → users.name)" }, "isEnrolledInLoyalty": { "type": "boolean", "description": "Whether user is enrolled in location loyalty program" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "initiator", "memberType", "isEnrolledInLoyalty", "createdAt", "updatedAt" ] }, "user": { "type": "object", "nullable": true, "properties": { "id": { "type": "number", "description": "User ID" }, "email": { "type": "string", "nullable": true, "description": "User email" }, "name": { "type": "string", "nullable": true, "description": "User name" }, "phone": { "type": "string", "nullable": true, "description": "User phone" } }, "required": [ "id" ] } }, "required": [ "tabMember", "user" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}/settle": { "post": { "summary": "Settle a fully paid tab", "tags": [ "Tabs" ], "description": "Settle a tab when its remaining balance is 0. This endpoint:\n\n1. **Validates** the tab can be settled:\n - Tab must exist\n - Tab must have remaining_balance_cents = 0 (fully paid)\n - Tab must not already be closed/settled/aborted\n\n2. **Updates** the tab state to 'settled'\n\n3. **Converts amount payments** to proportional item allocations (if any):\n - Amount payments (type='amount') get converted to product allocations\n - Each payer gets a proportional share of each item based on their pre-discount payment value\n - Original amount line items get quantity_cents set to 0 to mark as converted\n\n**Use cases:**\n- When balance reaches 0 via payments\n- Manual settlement by staff\n- This is the single source of truth for settling tabs\n\n**Note:** If all payments were for specific items (ITEM mode), no conversion is needed.\n\n**Permissions:** 🟠 `tabs.update`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "latestState": { "type": "string", "enum": [ "initiated", "started", "instant", "closed", "settled", "aborted", "action_required" ], "description": "Current tab state" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "enum": [ "open_tab", "pay_upfront" ], "description": "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" }, "paymentSplit": { "type": "number", "nullable": true, "minimum": 2, "maximum": 10, "description": "Number of splits when in AMOUNT mode (2-10), null when in ITEM mode" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance to be paid in cents" }, "storefrontQrCodeId": { "type": "string", "nullable": true, "description": "Table/QR code UUID if applicable" }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation." }, "bookingConfirmationCode": { "type": "string", "nullable": true, "description": "Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page." }, "tabMembers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "storefrontSessionId": { "type": "string", "nullable": true, "description": "Storefront session ID" }, "initiator": { "type": "boolean", "description": "Whether this member initiated the tab" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retail user ID if applicable" }, "clientId": { "type": "string", "nullable": true, "description": "Client identifier (user UUID for identification)" }, "userEmail": { "type": "string", "nullable": true, "description": "User email (canonical, never overridden per-location)" }, "userName": { "type": "string", "nullable": true, "description": "Override-merged display name (falls back through retailer.name → ulo.display_name → users.name)" }, "isEnrolledInLoyalty": { "type": "boolean", "description": "Whether user is enrolled in location loyalty program" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "initiator", "memberType", "isEnrolledInLoyalty", "createdAt", "updatedAt" ] }, "description": "Tab members" }, "memberCount": { "type": "number", "description": "Number of guest tab_members (party size; excludes staff)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "latestState": { "type": "string", "description": "Current state of the dispatch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch item UUID" }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "itemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "tabMemberId": { "type": "string", "nullable": true, "description": "Tab member UUID who ordered this" }, "parentKitchenDispatchItemId": { "type": "string", "nullable": true, "description": "Parent kitchen dispatch item UUID (for nested items)" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications in cents" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "quantity": { "type": "number", "description": "Quantity ordered" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (for fractional items)" }, "splitOfKdi": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of original item if this is a split item (for grouping)" }, "tabSettlementId": { "type": "string", "nullable": true, "description": "Settlement UUID if paid" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state (payment_in_progress, settled)" }, "status": { "type": "string", "nullable": true, "description": "Item status" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "paidAmount": { "type": "number", "nullable": true, "description": "Amount paid for this item in cents" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "itemTitle": { "type": "string", "nullable": true, "description": "Item title from inventory" }, "itemTitlePrep": { "type": "string", "nullable": true, "description": "Item prep name from inventory" }, "itemDescription": { "type": "string", "nullable": true, "description": "Item description from inventory" }, "itemImageUrl": { "type": "string", "nullable": true, "description": "Item image URL from inventory" }, "tabMember": { "type": "object", "nullable": true, "description": "Guest/user information for the person who ordered this item", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" }, "phone": { "type": "string", "description": "Member phone number" }, "imageUrl": { "type": "string", "description": "Member profile image URL" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated user" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retailer user ID if staff member" } } }, "comments": { "type": "array", "description": "Comments on this item", "items": { "type": "object", "properties": { "comment": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "tabMemberUUID": { "type": "string", "nullable": true }, "uuid": { "type": "string", "format": "uuid" } } } }, "variants": { "type": "array", "description": "Variants/modifications on this item", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number", "description": "Price in cents (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } } } } }, "required": [ "uuid", "kitchenDispatchId", "price", "basePrice", "quantity", "createdAt", "updatedAt" ] }, "description": "Items in this dispatch" } }, "required": [ "uuid", "tabId", "locationId", "latestState", "createdAt", "updatedAt", "kitchenDispatchItems" ] }, "description": "Kitchen dispatches with items" }, "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "tab_vouchers.id (use with DELETE /vouchers/applied/:id)" }, "discountId": { "type": "number", "description": "discounts.id" }, "discountCode": { "type": "string", "description": "Voucher code as entered" }, "appliedAt": { "type": "string", "format": "date-time" }, "voucherName": { "type": "string", "nullable": true, "description": "discounts.name (internal name)" }, "voucherType": { "type": "string", "nullable": true }, "typeSpecification": { "type": "object", "nullable": true, "additionalProperties": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "hasUsesLeft": { "type": "boolean", "description": "Computed: maxUses null/0 OR timesUsed < maxUses" }, "remainingBalanceCents": { "type": "number", "nullable": true, "description": "For gift cards" }, "displayTitle": { "type": "string", "nullable": true, "description": "Guest-facing title" }, "displayDescription": { "type": "string", "nullable": true, "description": "Guest-facing description" }, "displayImageUrl": { "type": "string", "nullable": true, "description": "Thumbnail URL" } }, "required": [ "id", "discountId", "discountCode", "appliedAt", "timesUsed", "hasUsesLeft" ] }, "description": "Vouchers attached to this tab (from POS or storefront)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "description": "Entity type (tab, user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order (0 = first/top)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] }, "description": "Notes attached to this tab" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "amountPaymentsConverted": { "type": "boolean", "description": "Whether amount payments were converted to item allocations" }, "amountPaymentsCount": { "type": "number", "description": "Number of amount payments that were converted" }, "newLineItemsCount": { "type": "number", "description": "Number of new product line items created from conversion" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{id}/timeline": { "get": { "summary": "Get tab timeline", "tags": [ "Tabs" ], "description": "Get a unified timeline of all events for a specific tab, including state transitions, order events, member joins, and payments. Events are sorted by creation time descending.\n\n**Permissions:** 🔵 `tabs.read`", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Tab timeline events", "content": { "application/json": { "schema": { "description": "Tab timeline events", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Event UUID" }, "source": { "type": "string", "enum": [ "tab_event", "order_event", "member_joined", "purchase" ], "description": "Event source" }, "eventType": { "type": "string", "description": "Event type (e.g. started, closed, pending, confirmed)" }, "description": { "type": "string", "description": "Human-readable event description" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event occurred" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Additional event-specific data" } }, "required": [ "uuid", "source", "eventType", "description", "createdAt" ] } } }, "required": [ "events" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/checkout-summary": { "post": { "summary": "Get checkout summary", "tags": [ "Tabs" ], "description": "Get checkout summary for a tab member's locked items. Returns items, totals, VAT breakdown, and kitchenDispatchItems array for payment processing.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tabMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Tab member UUID (Priority 1)" }, "email": { "type": "string", "description": "Email address (Priority 2)" }, "phone": { "type": "string", "description": "Phone number (Priority 3)" }, "identifier": { "type": "string", "description": "Device/client identifier (Priority 4)" } }, "description": "Tab member identification. Provide at least one identifier. Priority: id > email > phone > identifier" } }, "required": [ "tabMember" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Checkout summary retrieved successfully", "content": { "application/json": { "schema": { "description": "Checkout summary retrieved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode indicator: ITEM for item-based, AMOUNT for split-based" }, "tabId": { "type": "string", "description": "Tab UUID" }, "tabMemberId": { "type": "string", "description": "Resolved tab member UUID" }, "clientId": { "type": "string", "nullable": true, "description": "Client UUID for session correlation" }, "items": { "type": "array", "items": { "type": "object", "properties": { "kitchenDispatchItemId": { "type": "string", "description": "Kitchen dispatch item UUID" }, "itemId": { "type": "number", "description": "Inventory item ID" }, "title": { "type": "string", "description": "Item title" }, "quantity": { "type": "number", "description": "Actual quantity (quantity_cents / 100)" }, "basePrice": { "type": "number", "description": "Base item price in cents" }, "variantsPrice": { "type": "number", "description": "Total variants price in cents" }, "totalPrice": { "type": "number", "description": "Total price (basePrice + variantsPrice) * quantity in cents" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "vat": { "type": "number", "description": "VAT rate in basis points (1200 = 12%, defaults to 1200 if item has no VAT)" }, "vatId": { "type": "number", "description": "VAT ID for mapping (defaults to 1 if item has no VAT ID)" }, "vatAmountCents": { "type": "number", "description": "Calculated VAT amount in cents (VAT-inclusive calculation)" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Variant ID" }, "name": { "type": "string", "description": "Variant name/title from inventory" }, "quantity_cents": { "type": "number", "description": "Quantity in cents (100 = 1x)" }, "price_cents": { "type": "number", "nullable": true, "description": "Price override in cents" }, "comments": { "type": "array", "items": { "type": "string" }, "description": "Variant-specific comments" }, "variants": { "type": "array", "items": { "type": "object" }, "description": "Nested variants (recursive structure)" } }, "required": [ "id" ] }, "description": "Selected variants for this item" }, "comments": { "type": "array", "items": { "type": "string" }, "description": "Item comments" } }, "required": [ "kitchenDispatchItemId", "itemId", "title", "quantity", "basePrice", "variantsPrice", "totalPrice", "vat", "vatId", "vatAmountCents", "variants", "comments" ] }, "description": "Locked items for checkout (ITEM mode only)" }, "totals": { "type": "object", "properties": { "subtotal": { "type": "number", "description": "Sum of all item totalPrice (before discounts) in cents" }, "discounts": { "type": "number", "description": "Total discounts applied in cents" }, "totalAmountInCents": { "type": "number", "description": "Final total (subtotal - discounts) in cents" }, "vatBreakdown": { "type": "object", "additionalProperties": { "type": "number" }, "description": "VAT breakdown by rate. Keys are formatted like \"12 %\", \"25 %\". Values in cents.", "example": { "12 %": 1200, "25 %": 500 } } }, "required": [ "subtotal", "discounts", "totalAmountInCents", "vatBreakdown" ] }, "kitchenDispatchItems": { "type": "array", "items": { "type": "string" }, "description": "Kitchen dispatch item UUIDs for payment call (ITEM mode only)" }, "paymentSplit": { "type": "number", "description": "Number of ways the tab is split, 2-10 (AMOUNT mode only)" }, "totalAmountCents": { "type": "number", "description": "Total tab amount in cents (AMOUNT mode only)" }, "splitAmountCents": { "type": "number", "description": "Amount per split in cents, rounded up (AMOUNT mode only)" }, "paidAmountCents": { "type": "number", "description": "Total amount already paid in cents (AMOUNT mode only)" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance in cents (AMOUNT mode only)" }, "paidSplits": { "type": "number", "description": "Number of splits already paid (AMOUNT mode only)" }, "remainingSplits": { "type": "number", "description": "Number of splits remaining to pay (AMOUNT mode only)" }, "vatBreakdown": { "type": "object", "additionalProperties": { "type": "number" }, "description": "VAT breakdown by rate. Keys are formatted like \"12 %\", \"25 %\". Values in cents. Present in both modes." } }, "required": [ "paymentMode", "tabId", "tabMemberId", "clientId" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/discounts": { "get": { "summary": "Get tab discounts", "tags": [ "Tabs" ], "description": "Retrieve all items with discounts or price changes on a tab", "parameters": [ { "schema": { "type": "string", "enum": [ "DISCOUNT_PERCENTAGE", "DISCOUNT_FIXED", "PRICE_SET", "DISCOUNT_REMOVED" ] }, "in": "query", "name": "changeType", "required": false, "description": "Filter by type of price change" }, { "schema": { "type": "integer" }, "in": "query", "name": "appliedBy", "required": false, "description": "Filter by retailer user ID who applied the change" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Response status" }, "data": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "type": "object", "required": [ "id", "kitchenDispatchItemId", "tabId", "appliedBy", "previousPrice", "newPrice", "basePrice", "changeType", "reasonCode", "createdAt" ], "properties": { "id": { "type": "integer", "description": "Unique identifier for this price event" }, "kitchenDispatchItemId": { "type": "string", "format": "uuid", "description": "UUID of the kitchen dispatch item that was modified" }, "tabId": { "type": "string", "format": "uuid", "description": "UUID of the tab containing the item" }, "appliedBy": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "integer", "description": "Retailer user ID of the staff member" }, "name": { "type": "string", "nullable": true, "description": "Name of the staff member" }, "email": { "type": "string", "nullable": true, "format": "email", "description": "Email of the staff member" } } }, "previousPrice": { "type": "integer", "description": "Previous price in cents" }, "newPrice": { "type": "integer", "description": "New price in cents" }, "previousDiscount": { "type": "integer", "nullable": true, "description": "Previous discount amount in cents (null if no previous discount)" }, "newDiscount": { "type": "integer", "nullable": true, "description": "New discount amount in cents (null if no discount)" }, "basePrice": { "type": "integer", "description": "Original base price in cents (for reference)" }, "changeType": { "type": "string", "enum": [ "DISCOUNT_PERCENTAGE", "DISCOUNT_FIXED", "PRICE_SET", "DISCOUNT_REMOVED" ], "description": "Type of price change applied to the item" }, "discountPercentage": { "type": "number", "nullable": true, "description": "For percentage discounts: the percentage value (e.g., 15.5 for 15.5% off)" }, "discountAmountCents": { "type": "integer", "nullable": true, "description": "For fixed discounts: the fixed amount in cents" }, "reasonCode": { "type": "string", "description": "Reason code for the price change (PRICE_MATCH, GOODWILL, etc.)", "example": "PRICE_MATCH" }, "notes": { "type": "string", "nullable": true, "description": "Optional notes explaining the price adjustment" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the price change was applied" } } }, "description": "List of price change events" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/items": { "get": { "summary": "Get selected items", "tags": [ "Tabs" ], "description": "Get current selected items state for a tab", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "stateValidToEpoch": { "type": "number", "description": "Timestamp (milliseconds since epoch) when this state expires" }, "selectedItems": { "type": "array", "items": { "type": "object", "properties": { "tabMemberId": { "type": "string", "format": "uuid", "description": "UUID of the tab member who claimed this item" }, "clientId": { "type": "string", "format": "uuid", "description": "UUID of the client (from storefront sessions) for compatibility" }, "itemId": { "type": "string", "format": "uuid", "description": "UUID of the inventory item that was claimed" }, "isLocked": { "type": "boolean", "description": "Whether this item is locked for checkout (cannot be unclaimed by others)" } }, "required": [ "tabMemberId", "clientId", "itemId", "isLocked" ] }, "description": "Array of currently claimed items with their lock status" }, "hasLockedMembers": { "type": "boolean", "description": "True if any member has locked their selections for checkout (blocks split changes)" } }, "required": [ "stateValidToEpoch", "selectedItems", "hasLockedMembers" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/items/{itemId}/discount": { "delete": { "summary": "Remove item discount", "tags": [ "Tabs" ], "description": "Remove any discount from an item and restore its base price", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "reasonCode" ], "properties": { "reasonCode": { "type": "string", "description": "Reason code for removing the discount" }, "notes": { "type": "string", "description": "Optional notes" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab containing the item" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "itemId", "required": true, "description": "UUID of the kitchen dispatch item to restore" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Response status" }, "data": { "type": "object", "required": [ "priceEvent" ], "properties": { "priceEvent": { "type": "object", "required": [ "id", "kitchenDispatchItemId", "tabId", "appliedBy", "previousPrice", "newPrice", "basePrice", "changeType", "reasonCode", "createdAt" ], "properties": { "id": { "type": "integer", "description": "Unique identifier for this price event" }, "kitchenDispatchItemId": { "type": "string", "format": "uuid", "description": "UUID of the kitchen dispatch item that was modified" }, "tabId": { "type": "string", "format": "uuid", "description": "UUID of the tab containing the item" }, "appliedBy": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "integer", "description": "Retailer user ID of the staff member" }, "name": { "type": "string", "nullable": true, "description": "Name of the staff member" }, "email": { "type": "string", "nullable": true, "format": "email", "description": "Email of the staff member" } } }, "previousPrice": { "type": "integer", "description": "Previous price in cents" }, "newPrice": { "type": "integer", "description": "New price in cents" }, "previousDiscount": { "type": "integer", "nullable": true, "description": "Previous discount amount in cents (null if no previous discount)" }, "newDiscount": { "type": "integer", "nullable": true, "description": "New discount amount in cents (null if no discount)" }, "basePrice": { "type": "integer", "description": "Original base price in cents (for reference)" }, "changeType": { "type": "string", "enum": [ "DISCOUNT_PERCENTAGE", "DISCOUNT_FIXED", "PRICE_SET", "DISCOUNT_REMOVED" ], "description": "Type of price change applied to the item" }, "discountPercentage": { "type": "number", "nullable": true, "description": "For percentage discounts: the percentage value (e.g., 15.5 for 15.5% off)" }, "discountAmountCents": { "type": "integer", "nullable": true, "description": "For fixed discounts: the fixed amount in cents" }, "reasonCode": { "type": "string", "description": "Reason code for the price change (PRICE_MATCH, GOODWILL, etc.)", "example": "PRICE_MATCH" }, "notes": { "type": "string", "nullable": true, "description": "Optional notes explaining the price adjustment" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the price change was applied" } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/items/{itemId}/price": { "put": { "summary": "Update item price", "tags": [ "Tabs" ], "description": "Apply a discount or set a new price on a kitchen dispatch item", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "reasonCode" ], "properties": { "action": { "type": "string", "enum": [ "discount", "set_price" ], "description": "Type of action: \"discount\" for applying discounts, \"set_price\" for setting arbitrary price" }, "discountType": { "type": "string", "enum": [ "percentage", "fixed" ], "description": "Required when action is \"discount\": type of discount to apply" }, "value": { "type": "number", "description": "Required when action is \"discount\": percentage (1-100) or cents for fixed discount", "minimum": 0 }, "priceInCents": { "type": "integer", "description": "Required when action is \"set_price\": new price in cents", "minimum": 0 }, "reasonCode": { "type": "string", "description": "Required reason code explaining why the price is being adjusted", "example": "PRICE_MATCH" }, "notes": { "type": "string", "description": "Optional notes providing additional context for the price adjustment" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab containing the item" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "itemId", "required": true, "description": "UUID of the kitchen dispatch item to modify" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Response status" }, "data": { "type": "object", "required": [ "priceEvent" ], "properties": { "priceEvent": { "type": "object", "required": [ "id", "kitchenDispatchItemId", "tabId", "appliedBy", "previousPrice", "newPrice", "basePrice", "changeType", "reasonCode", "createdAt" ], "properties": { "id": { "type": "integer", "description": "Unique identifier for this price event" }, "kitchenDispatchItemId": { "type": "string", "format": "uuid", "description": "UUID of the kitchen dispatch item that was modified" }, "tabId": { "type": "string", "format": "uuid", "description": "UUID of the tab containing the item" }, "appliedBy": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "integer", "description": "Retailer user ID of the staff member" }, "name": { "type": "string", "nullable": true, "description": "Name of the staff member" }, "email": { "type": "string", "nullable": true, "format": "email", "description": "Email of the staff member" } } }, "previousPrice": { "type": "integer", "description": "Previous price in cents" }, "newPrice": { "type": "integer", "description": "New price in cents" }, "previousDiscount": { "type": "integer", "nullable": true, "description": "Previous discount amount in cents (null if no previous discount)" }, "newDiscount": { "type": "integer", "nullable": true, "description": "New discount amount in cents (null if no discount)" }, "basePrice": { "type": "integer", "description": "Original base price in cents (for reference)" }, "changeType": { "type": "string", "enum": [ "DISCOUNT_PERCENTAGE", "DISCOUNT_FIXED", "PRICE_SET", "DISCOUNT_REMOVED" ], "description": "Type of price change applied to the item" }, "discountPercentage": { "type": "number", "nullable": true, "description": "For percentage discounts: the percentage value (e.g., 15.5 for 15.5% off)" }, "discountAmountCents": { "type": "integer", "nullable": true, "description": "For fixed discounts: the fixed amount in cents" }, "reasonCode": { "type": "string", "description": "Reason code for the price change (PRICE_MATCH, GOODWILL, etc.)", "example": "PRICE_MATCH" }, "notes": { "type": "string", "nullable": true, "description": "Optional notes explaining the price adjustment" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the price change was applied" } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/items/{itemId}/price-history": { "get": { "summary": "Get item price history", "tags": [ "Tabs" ], "description": "Retrieve the complete price change history for a kitchen dispatch item", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "itemId", "required": true, "description": "UUID of the kitchen dispatch item" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Response status" }, "data": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "type": "object", "required": [ "id", "kitchenDispatchItemId", "tabId", "appliedBy", "previousPrice", "newPrice", "basePrice", "changeType", "reasonCode", "createdAt" ], "properties": { "id": { "type": "integer", "description": "Unique identifier for this price event" }, "kitchenDispatchItemId": { "type": "string", "format": "uuid", "description": "UUID of the kitchen dispatch item that was modified" }, "tabId": { "type": "string", "format": "uuid", "description": "UUID of the tab containing the item" }, "appliedBy": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "integer", "description": "Retailer user ID of the staff member" }, "name": { "type": "string", "nullable": true, "description": "Name of the staff member" }, "email": { "type": "string", "nullable": true, "format": "email", "description": "Email of the staff member" } } }, "previousPrice": { "type": "integer", "description": "Previous price in cents" }, "newPrice": { "type": "integer", "description": "New price in cents" }, "previousDiscount": { "type": "integer", "nullable": true, "description": "Previous discount amount in cents (null if no previous discount)" }, "newDiscount": { "type": "integer", "nullable": true, "description": "New discount amount in cents (null if no discount)" }, "basePrice": { "type": "integer", "description": "Original base price in cents (for reference)" }, "changeType": { "type": "string", "enum": [ "DISCOUNT_PERCENTAGE", "DISCOUNT_FIXED", "PRICE_SET", "DISCOUNT_REMOVED" ], "description": "Type of price change applied to the item" }, "discountPercentage": { "type": "number", "nullable": true, "description": "For percentage discounts: the percentage value (e.g., 15.5 for 15.5% off)" }, "discountAmountCents": { "type": "integer", "nullable": true, "description": "For fixed discounts: the fixed amount in cents" }, "reasonCode": { "type": "string", "description": "Reason code for the price change (PRICE_MATCH, GOODWILL, etc.)", "example": "PRICE_MATCH" }, "notes": { "type": "string", "nullable": true, "description": "Optional notes explaining the price adjustment" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the price change was applied" } } }, "description": "List of price change events" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/items/batch": { "post": { "summary": "Batch claim and unclaim items", "tags": [ "Tabs" ], "description": "Atomically claim and unclaim items for a tab member in a single operation. Emits a single webhook event for the combined change.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tabMemberId": { "type": "string", "format": "uuid", "description": "UUID of the tab member performing the batch operation" }, "clientId": { "type": "string", "format": "uuid", "description": "UUID of the client (from storefront sessions)" }, "claim": { "type": "array", "items": { "type": "string" }, "description": "Item IDs to claim (UUIDs in ITEM mode, virtual IDs like \"split-index-N\" in AMOUNT mode)" }, "unclaim": { "type": "array", "items": { "type": "string" }, "description": "Item IDs to unclaim (UUIDs in ITEM mode, virtual IDs like \"split-index-N\" in AMOUNT mode)" }, "mode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode for the batch operation" } }, "required": [ "tabMemberId", "clientId" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "stateValidToEpoch": { "type": "number", "description": "Timestamp when this state expires" }, "selectedItems": { "type": "array", "items": { "type": "object", "properties": { "tabMemberId": { "type": "string", "format": "uuid", "description": "UUID of the tab member who claimed this item" }, "clientId": { "type": "string", "format": "uuid", "description": "UUID of the client (from storefront sessions) for compatibility" }, "itemId": { "type": "string", "format": "uuid", "description": "UUID of the inventory item that was claimed" }, "isLocked": { "type": "boolean", "description": "Whether this item is locked for checkout (cannot be unclaimed by others)" } }, "required": [ "tabMemberId", "clientId", "itemId", "isLocked" ] }, "description": "Updated list of selected items" }, "hasLockedMembers": { "type": "boolean", "description": "True if any member has locked their selections for checkout" } }, "required": [ "success", "stateValidToEpoch", "selectedItems", "hasLockedMembers" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "409": { "description": "Selections are locked for checkout", "content": { "application/json": { "schema": { "description": "Selections are locked for checkout", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SELECTIONS_LOCKED" ] }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/items/bulk-price": { "put": { "summary": "Bulk update item prices", "tags": [ "Tabs" ], "description": "Apply discounts or set new prices on multiple kitchen dispatch items in a single request. Only sends items that need to be updated.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "reasonCode" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "kitchenDispatchItemId" ], "properties": { "kitchenDispatchItemId": { "type": "string", "format": "uuid", "description": "UUID of the kitchen dispatch item to modify" }, "newPrice": { "type": "integer", "description": "New price in cents (for set_price action)", "minimum": 0 }, "discountPercent": { "type": "number", "description": "Percentage discount to apply (1-100)", "minimum": 0, "maximum": 100 }, "removeDiscount": { "type": "boolean", "description": "Set to true to remove discount and restore base price" } } }, "description": "Array of items to update. Each item should specify exactly one of: newPrice, discountPercent, or removeDiscount", "minItems": 1 }, "reasonCode": { "type": "string", "description": "Reason code explaining why the prices are being adjusted", "example": "PRICE_MATCH" }, "notes": { "type": "string", "description": "Optional notes providing additional context for the price adjustments" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab containing the items" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data", "meta" ], "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Response status" }, "data": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "kitchenDispatchItemId", "previousPrice", "newPrice", "changeType", "success" ], "properties": { "kitchenDispatchItemId": { "type": "string", "format": "uuid", "description": "UUID of the modified item" }, "previousPrice": { "type": "integer", "description": "Previous price in cents" }, "newPrice": { "type": "integer", "description": "New price in cents" }, "changeType": { "type": "string", "enum": [ "DISCOUNT_PERCENTAGE", "DISCOUNT_FIXED", "PRICE_SET", "DISCOUNT_REMOVED" ], "description": "Type of price change applied to the item" }, "success": { "type": "boolean", "description": "Whether the update succeeded" }, "error": { "type": "string", "description": "Error message if update failed" } } }, "description": "Results for each item update" }, "totalUpdated": { "type": "integer", "description": "Number of items successfully updated" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/items/claim": { "post": { "summary": "Claim items", "tags": [ "Tabs" ], "description": "Claim specific items for a tab member", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tabMemberId": { "type": "string", "format": "uuid", "description": "UUID of the tab member claiming the items" }, "clientId": { "type": "string", "format": "uuid", "description": "UUID of the client (from storefront sessions) for storage efficiency" }, "items": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of item IDs to claim. In ITEM mode: inventory item UUIDs. In AMOUNT mode: virtual IDs like \"split-index-0\"." }, "mode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode: ITEM for individual item claiming, AMOUNT for split claiming" } }, "required": [ "tabMemberId", "clientId", "items" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "stateValidToEpoch": { "type": "number", "description": "Timestamp when this state expires" }, "selectedItems": { "type": "array", "items": { "type": "object", "properties": { "tabMemberId": { "type": "string", "format": "uuid", "description": "UUID of the tab member who claimed this item" }, "clientId": { "type": "string", "format": "uuid", "description": "UUID of the client (from storefront sessions) for compatibility" }, "itemId": { "type": "string", "format": "uuid", "description": "UUID of the inventory item that was claimed" }, "isLocked": { "type": "boolean", "description": "Whether this item is locked for checkout (cannot be unclaimed by others)" } }, "required": [ "tabMemberId", "clientId", "itemId", "isLocked" ] }, "description": "Updated list of selected items" }, "hasLockedMembers": { "type": "boolean", "description": "True if any member has locked their selections for checkout" } }, "required": [ "success", "stateValidToEpoch", "selectedItems", "hasLockedMembers" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "409": { "description": "Selections are locked for checkout", "content": { "application/json": { "schema": { "description": "Selections are locked for checkout", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SELECTIONS_LOCKED" ] }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/items/lock": { "post": { "summary": "Lock item selections", "tags": [ "Tabs" ], "description": "Lock a tab member's selections for checkout (prevents further modifications)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tabMemberId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the tab member to lock/unlock selections for (nullable)" }, "clientId": { "type": "string", "format": "uuid", "description": "UUID of the client (fallback identifier when tabMemberId is not available)" }, "claimAfterUnlock": { "type": "boolean", "description": "If true, freed items are re-claimed to the caller after force-unlock of another member." }, "skipCascadeCancel": { "type": "boolean", "description": "When true, bypass the auto-cancel of any payment_in_progress settlements for the unlocked member. Use only for staff force-unlock flows. Default false." } }, "anyOf": [ { "required": [ "tabMemberId" ] }, { "required": [ "clientId" ] } ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "stateValidToEpoch": { "type": "number", "description": "Timestamp when this state expires" }, "selectedItems": { "type": "array", "items": { "type": "object", "properties": { "tabMemberId": { "type": "string", "format": "uuid", "description": "UUID of the tab member who claimed this item" }, "clientId": { "type": "string", "format": "uuid", "description": "UUID of the client (from storefront sessions) for compatibility" }, "itemId": { "type": "string", "format": "uuid", "description": "UUID of the inventory item that was claimed" }, "isLocked": { "type": "boolean", "description": "Whether this item is locked for checkout (cannot be unclaimed by others)" } }, "required": [ "tabMemberId", "clientId", "itemId", "isLocked" ] }, "description": "Updated list of selected items" }, "hasLockedMembers": { "type": "boolean", "description": "True if any member has locked their selections for checkout" } }, "required": [ "success", "stateValidToEpoch", "selectedItems", "hasLockedMembers" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/items/unclaim": { "post": { "summary": "Unclaim items", "tags": [ "Tabs" ], "description": "Unclaim (release) specific items for a tab member", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tabMemberId": { "type": "string", "format": "uuid", "description": "UUID of the tab member unclaiming the items" }, "items": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of item IDs to unclaim. In ITEM mode: inventory item UUIDs. In AMOUNT mode: virtual IDs like \"split-index-0\"." }, "mode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode: ITEM for individual item unclaiming, AMOUNT for split unclaiming" } }, "required": [ "tabMemberId", "items" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "stateValidToEpoch": { "type": "number", "description": "Timestamp when this state expires" }, "selectedItems": { "type": "array", "items": { "type": "object", "properties": { "tabMemberId": { "type": "string", "format": "uuid", "description": "UUID of the tab member who claimed this item" }, "clientId": { "type": "string", "format": "uuid", "description": "UUID of the client (from storefront sessions) for compatibility" }, "itemId": { "type": "string", "format": "uuid", "description": "UUID of the inventory item that was claimed" }, "isLocked": { "type": "boolean", "description": "Whether this item is locked for checkout (cannot be unclaimed by others)" } }, "required": [ "tabMemberId", "clientId", "itemId", "isLocked" ] }, "description": "Updated list of selected items" }, "hasLockedMembers": { "type": "boolean", "description": "True if any member has locked their selections for checkout" } }, "required": [ "success", "stateValidToEpoch", "selectedItems", "hasLockedMembers" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "409": { "description": "Selections are locked for checkout", "content": { "application/json": { "schema": { "description": "Selections are locked for checkout", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SELECTIONS_LOCKED" ] }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/items/unlock": { "post": { "summary": "Unlock item selections", "tags": [ "Tabs" ], "description": "Unlock a tab member's selections (allows modifications again)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tabMemberId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the tab member to lock/unlock selections for (nullable)" }, "clientId": { "type": "string", "format": "uuid", "description": "UUID of the client (fallback identifier when tabMemberId is not available)" }, "claimAfterUnlock": { "type": "boolean", "description": "If true, freed items are re-claimed to the caller after force-unlock of another member." }, "skipCascadeCancel": { "type": "boolean", "description": "When true, bypass the auto-cancel of any payment_in_progress settlements for the unlocked member. Use only for staff force-unlock flows. Default false." } }, "anyOf": [ { "required": [ "tabMemberId" ] }, { "required": [ "clientId" ] } ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "UUID of the tab" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "stateValidToEpoch": { "type": "number", "description": "Timestamp when this state expires" }, "selectedItems": { "type": "array", "items": { "type": "object", "properties": { "tabMemberId": { "type": "string", "format": "uuid", "description": "UUID of the tab member who claimed this item" }, "clientId": { "type": "string", "format": "uuid", "description": "UUID of the client (from storefront sessions) for compatibility" }, "itemId": { "type": "string", "format": "uuid", "description": "UUID of the inventory item that was claimed" }, "isLocked": { "type": "boolean", "description": "Whether this item is locked for checkout (cannot be unclaimed by others)" } }, "required": [ "tabMemberId", "clientId", "itemId", "isLocked" ] }, "description": "Updated list of selected items" }, "hasLockedMembers": { "type": "boolean", "description": "True if any member has locked their selections for checkout" } }, "required": [ "success", "stateValidToEpoch", "selectedItems", "hasLockedMembers" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/move/dispatch": { "post": { "summary": "Move dispatch to another table", "tags": [ "Tabs" ], "description": "Move an entire kitchen_dispatch from a tab to another table", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "dispatchId": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID to move" }, "destinationTableId": { "type": "string", "format": "uuid", "description": "Destination table (storefront_qr_code) UUID" } }, "required": [ "dispatchId", "destinationTableId" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "Source tab UUID" } ], "responses": { "200": { "description": "Dispatch moved successfully", "content": { "application/json": { "schema": { "description": "Dispatch moved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "sourceTabId": { "type": "string", "format": "uuid" }, "destinationTabId": { "type": "string", "format": "uuid" }, "movedItemCount": { "type": "integer" }, "tabMerged": { "type": "boolean" } }, "required": [ "success", "message", "sourceTabId", "destinationTabId", "movedItemCount", "tabMerged" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/move/items": { "post": { "summary": "Move items to another table", "tags": [ "Tabs" ], "description": "Move specific kitchen_dispatch_items from a tab to another table", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "itemIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of kitchen_dispatch_item UUIDs to move", "minItems": 1 }, "destinationTableId": { "type": "string", "format": "uuid", "description": "Destination table (storefront_qr_code) UUID" } }, "required": [ "itemIds", "destinationTableId" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "Source tab UUID" } ], "responses": { "200": { "description": "Items moved successfully", "content": { "application/json": { "schema": { "description": "Items moved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "sourceTabId": { "type": "string", "format": "uuid" }, "destinationTabId": { "type": "string", "format": "uuid" }, "movedItemCount": { "type": "integer" }, "tabMerged": { "type": "boolean" } }, "required": [ "success", "message", "sourceTabId", "destinationTabId", "movedItemCount", "tabMerged" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/move/tab": { "post": { "summary": "Move tab to another table", "tags": [ "Tabs" ], "description": "Move an entire tab to another table. If destination table has an active tab, tabs are merged.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "destinationTableId": { "type": "string", "format": "uuid", "description": "Destination table (storefront_qr_code) UUID" } }, "required": [ "destinationTableId" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "Source tab UUID" } ], "responses": { "200": { "description": "Tab moved or merged successfully", "content": { "application/json": { "schema": { "description": "Tab moved or merged successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "sourceTabId": { "type": "string", "format": "uuid" }, "destinationTabId": { "type": "string", "format": "uuid" }, "movedItemCount": { "type": "integer" }, "tabMerged": { "type": "boolean" } }, "required": [ "success", "message", "sourceTabId", "destinationTabId", "movedItemCount", "tabMerged" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/payment-split": { "post": { "summary": "Set payment split", "tags": [ "Tabs" ], "description": "Set payment split for a tab (switches to AMOUNT mode).\n\nThis endpoint allows users to split the entire tab bill evenly among multiple people.\nWhen a split is set, the tab switches from ITEM mode to AMOUNT mode.\n\n**Constraints:**\n- Split can only be set when no payments have been made yet\n- Split can be changed until someone locks items for checkout\n- Split value must be between 2 and 10\n- Tab must have items (total_amount_cents > 0)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "payment_split" ], "properties": { "payment_split": { "type": "integer", "minimum": 2, "maximum": 10, "description": "Number of ways to split the tab (2-10)" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "The UUID of the tab" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabId": { "type": "string", "format": "uuid" }, "paymentMode": { "type": "string", "enum": [ "AMOUNT" ] }, "paymentSplit": { "type": "integer", "description": "Number of splits" }, "totalAmountCents": { "type": "integer", "description": "Total tab amount in cents" }, "splitAmountCents": { "type": "integer", "description": "Amount per split in cents (rounded up)" }, "remainingBalanceCents": { "type": "integer", "description": "Remaining balance in cents" }, "paidSplits": { "type": "integer", "description": "Number of splits already paid" }, "remainingSplits": { "type": "integer", "description": "Number of splits remaining" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Clear payment split", "tags": [ "Tabs" ], "description": "Clear payment split for a tab (reverts to ITEM mode).\n\nThis endpoint allows users to cancel/clear a previously set payment split.\nWhen cleared, the tab switches from AMOUNT mode back to ITEM mode.\n\n**Constraints:**\n- Can only be cleared when no payments have been made yet\n- Cannot be cleared while items are locked for checkout\n- Tab must currently be in AMOUNT mode (split mode)\n\n**Use cases:**\n- User changed their mind about splitting\n- Split was set by mistake\n- Group decided to pay individually instead", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "The UUID of the tab" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabId": { "type": "string", "format": "uuid" }, "paymentMode": { "type": "string", "enum": [ "ITEM" ], "description": "Payment mode after clearing (always ITEM)" }, "previousPaymentSplit": { "type": "integer", "nullable": true, "description": "The previous split value that was cleared" }, "clearedSelections": { "type": "boolean", "description": "Whether Redis selections were cleared" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/{tabId}/purchases": { "get": { "summary": "Get purchases for a tab", "tags": [ "Tabs" ], "description": "Get all confirmed purchases for a specific tab, including payer information and totals. Used to display payment history in the POS tab view.\n\n**Permissions:** 🔵 `purchases.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "tabId", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Purchase ID" }, "intentId": { "type": "string", "description": "Payment intent ID" }, "purchasedAt": { "type": "string", "format": "date-time", "description": "When the purchase was completed" }, "state": { "type": "string", "description": "Purchase state" }, "currencyCode": { "type": "string", "description": "Currency code (e.g., SEK)" }, "payerUuid": { "type": "string", "format": "uuid", "nullable": true, "description": "Tab member UUID who paid" }, "payerName": { "type": "string", "nullable": true, "description": "Name of the payer" }, "payerEmail": { "type": "string", "nullable": true, "description": "Email of the payer" }, "psp": { "type": "string", "nullable": true, "description": "Payment service provider (e.g. adyen, swish, gift_card, cash, prepaid, invoice, softpay)" }, "totalAmountCents": { "type": "number", "description": "Total purchase amount in cents" }, "lineItemCount": { "type": "number", "description": "Number of line items in the purchase" } }, "required": [ "id", "intentId", "purchasedAt", "state", "totalAmountCents", "lineItemCount" ] }, "description": "List of purchases for this tab" }, "summary": { "type": "object", "properties": { "totalPaidCents": { "type": "number", "description": "Total amount paid across all purchases in cents" }, "purchaseCount": { "type": "number", "description": "Number of purchases" }, "totalItemCount": { "type": "number", "description": "Total number of line items across all purchases" } }, "required": [ "totalPaidCents", "purchaseCount", "totalItemCount" ] } }, "required": [ "purchases", "summary" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/check-exists": { "post": { "summary": "Check if tab exists for QR code (without joining)", "tags": [ "Tabs" ], "description": "Checks if an active tab exists for a QR code WITHOUT joining the user to it. This is useful for instant-pay flows that want to show a \"Join Tab\" option but should not auto-join. Returns hasActiveTab: true/false with the tabId if one exists.\n\n**Permissions:** 🔵 `tabs.read`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Restaurant location ID" }, "qrCodeId": { "type": "string", "format": "uuid", "description": "QR code UUID for the table" } }, "required": [ "locationId", "qrCodeId" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "hasActiveTab": { "type": "boolean", "description": "True if an active tab exists for this QR code" }, "tabId": { "type": "string", "format": "uuid", "nullable": true, "description": "Tab UUID if exists, null otherwise" }, "tabMemberId": { "type": "string", "format": "uuid", "nullable": true, "description": "Always null since this endpoint does not join the tab" }, "isNewMember": { "type": "boolean", "description": "Always false since this endpoint does not join the tab" } }, "required": [ "hasActiveTab", "tabId", "tabMemberId", "isNewMember" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/debug/recent": { "get": { "summary": "Debug: recent tabs", "tags": [ "Tabs" ], "description": "Debug endpoint that returns recent tabs with balance verification, item allocations, and purchase breakdowns. Useful for diagnosing tab balance discrepancies.\n\n**Permissions:** 🔵 `tabs.read`", "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 20, "default": 5 }, "in": "query", "name": "limit", "required": false, "description": "Number of recent tabs to return (max 20)" }, { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" } ], "responses": { "200": { "description": "Debug info for recent tabs", "content": { "application/json": { "schema": { "description": "Debug info for recent tabs", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "query": { "type": "object", "additionalProperties": true } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/join-if-existing": { "post": { "summary": "Join existing tab for QR code", "tags": [ "Tabs" ], "description": "Returns all active joinable tabs (≤7 days old) for the QR code. When exactly one tab exists, auto-joins the user. When multiple tabs exist, returns the list for user selection without joining (pass tabId in a second request to join a specific tab). Returns hasActiveTab:false if no active tabs exist.\n\n**Permissions:** 🔵 `tabs.read`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Restaurant location ID" }, "qrCodeId": { "type": "string", "format": "uuid", "description": "QR code UUID for the table" }, "tabMember": { "type": "object", "description": "User identification using priority system", "properties": { "id": { "type": "number", "description": "User ID (authenticated users, priority 1)" }, "email": { "type": "string", "format": "email", "description": "Email address (priority 2)" }, "phone": { "type": "string", "description": "Phone number (priority 3)" }, "identifier": { "type": "string", "description": "Device identifier (priority 4)" } } }, "tabId": { "type": "string", "format": "uuid", "description": "Specific tab UUID to join (when user selects from multiple joinable tabs). Omit to auto-join or get the list." } }, "required": [ "locationId", "qrCodeId", "tabMember" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "hasActiveTab": { "type": "boolean", "description": "True if one or more active tabs exist at this QR code, false otherwise" }, "tabId": { "type": "string", "format": "uuid", "nullable": true, "description": "Tab UUID the user was joined to (null when multiple tabs exist and user must choose)" }, "tabMemberId": { "type": "string", "format": "uuid", "nullable": true, "description": "Tab member UUID (null when user has not yet been joined to a specific tab)" }, "isNewMember": { "type": "boolean", "description": "True if user was just added as member, false if already member or no tab exists" }, "joinableTabs": { "type": "array", "items": { "type": "object", "properties": { "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "description": "open_tab or pay_upfront" }, "tableName": { "type": "string", "nullable": true, "description": "Table/QR code display name" }, "memberCount": { "type": "number", "description": "Number of members currently in this tab" }, "totalAmountCents": { "type": "number", "description": "Current total of the tab in cents" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the tab was created" }, "members": { "type": "array", "description": "Tab members with display names (for avatar display in join UI)", "items": { "type": "object", "properties": { "userName": { "type": "string", "nullable": true, "description": "Member display name" } }, "required": [ "userName" ] } } }, "required": [ "tabId", "selectedPaymentFlow", "tableName", "memberCount", "totalAmountCents", "createdAt", "members" ] }, "description": "All active joinable tabs at this QR code (empty when none). Frontend shows selection drawer when length > 1." } }, "required": [ "hasActiveTab", "tabId", "tabMemberId", "isNewMember", "joinableTabs" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/mine": { "get": { "summary": "List the authenticated guest's active tabs", "tags": [ "Tabs" ], "description": "Returns all non-terminal tabs (latest_state NOT IN closed/settled/aborted) where the Bearer-authenticated guest user is a tab_member. Includes members and a minimal location stub. Identity resolves via the same JWT path as buyer endpoints (HS256 mobile or OIDC RS256 storefront).", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabs": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "latestState": { "type": "string", "enum": [ "initiated", "started", "instant", "closed", "settled", "aborted", "action_required" ], "description": "Current tab state" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "enum": [ "open_tab", "pay_upfront" ], "description": "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" }, "paymentSplit": { "type": "number", "nullable": true, "minimum": 2, "maximum": 10, "description": "Number of splits when in AMOUNT mode (2-10), null when in ITEM mode" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance to be paid in cents" }, "storefrontQrCodeId": { "type": "string", "nullable": true, "description": "Table/QR code UUID if applicable" }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation." }, "bookingConfirmationCode": { "type": "string", "nullable": true, "description": "Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page." }, "tabMembers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "storefrontSessionId": { "type": "string", "nullable": true, "description": "Storefront session ID" }, "initiator": { "type": "boolean", "description": "Whether this member initiated the tab" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retail user ID if applicable" }, "clientId": { "type": "string", "nullable": true, "description": "Client identifier (user UUID for identification)" }, "userEmail": { "type": "string", "nullable": true, "description": "User email (canonical, never overridden per-location)" }, "userName": { "type": "string", "nullable": true, "description": "Override-merged display name (falls back through retailer.name → ulo.display_name → users.name)" }, "isEnrolledInLoyalty": { "type": "boolean", "description": "Whether user is enrolled in location loyalty program" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "initiator", "memberType", "isEnrolledInLoyalty", "createdAt", "updatedAt" ] }, "description": "Tab members" }, "memberCount": { "type": "number", "description": "Number of guest tab_members (party size; excludes staff)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "latestState": { "type": "string", "description": "Current state of the dispatch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch item UUID" }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "itemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "tabMemberId": { "type": "string", "nullable": true, "description": "Tab member UUID who ordered this" }, "parentKitchenDispatchItemId": { "type": "string", "nullable": true, "description": "Parent kitchen dispatch item UUID (for nested items)" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications in cents" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "quantity": { "type": "number", "description": "Quantity ordered" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (for fractional items)" }, "splitOfKdi": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of original item if this is a split item (for grouping)" }, "tabSettlementId": { "type": "string", "nullable": true, "description": "Settlement UUID if paid" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state (payment_in_progress, settled)" }, "status": { "type": "string", "nullable": true, "description": "Item status" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "paidAmount": { "type": "number", "nullable": true, "description": "Amount paid for this item in cents" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "itemTitle": { "type": "string", "nullable": true, "description": "Item title from inventory" }, "itemTitlePrep": { "type": "string", "nullable": true, "description": "Item prep name from inventory" }, "itemDescription": { "type": "string", "nullable": true, "description": "Item description from inventory" }, "itemImageUrl": { "type": "string", "nullable": true, "description": "Item image URL from inventory" }, "tabMember": { "type": "object", "nullable": true, "description": "Guest/user information for the person who ordered this item", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" }, "phone": { "type": "string", "description": "Member phone number" }, "imageUrl": { "type": "string", "description": "Member profile image URL" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated user" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retailer user ID if staff member" } } }, "comments": { "type": "array", "description": "Comments on this item", "items": { "type": "object", "properties": { "comment": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "tabMemberUUID": { "type": "string", "nullable": true }, "uuid": { "type": "string", "format": "uuid" } } } }, "variants": { "type": "array", "description": "Variants/modifications on this item", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number", "description": "Price in cents (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } } } } }, "required": [ "uuid", "kitchenDispatchId", "price", "basePrice", "quantity", "createdAt", "updatedAt" ] }, "description": "Items in this dispatch" } }, "required": [ "uuid", "tabId", "locationId", "latestState", "createdAt", "updatedAt", "kitchenDispatchItems" ] }, "description": "Kitchen dispatches with items" }, "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "tab_vouchers.id (use with DELETE /vouchers/applied/:id)" }, "discountId": { "type": "number", "description": "discounts.id" }, "discountCode": { "type": "string", "description": "Voucher code as entered" }, "appliedAt": { "type": "string", "format": "date-time" }, "voucherName": { "type": "string", "nullable": true, "description": "discounts.name (internal name)" }, "voucherType": { "type": "string", "nullable": true }, "typeSpecification": { "type": "object", "nullable": true, "additionalProperties": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "hasUsesLeft": { "type": "boolean", "description": "Computed: maxUses null/0 OR timesUsed < maxUses" }, "remainingBalanceCents": { "type": "number", "nullable": true, "description": "For gift cards" }, "displayTitle": { "type": "string", "nullable": true, "description": "Guest-facing title" }, "displayDescription": { "type": "string", "nullable": true, "description": "Guest-facing description" }, "displayImageUrl": { "type": "string", "nullable": true, "description": "Thumbnail URL" } }, "required": [ "id", "discountId", "discountCode", "appliedAt", "timesUsed", "hasUsesLeft" ] }, "description": "Vouchers attached to this tab (from POS or storefront)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "description": "Entity type (tab, user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order (0 = first/top)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] }, "description": "Notes attached to this tab" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "location": { "type": "object", "properties": { "id": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Guest-facing location name (e.g. \"Café Saturnus\")" }, "logoImageUrl": { "type": "string", "nullable": true, "description": "Location logo URL for guest UI" }, "currency": { "type": "string", "nullable": true, "description": "ISO 4217 currency code (e.g. SEK)" }, "timezone": { "type": "string", "nullable": true, "description": "IANA timezone (e.g. Europe/Stockholm)" }, "slug": { "type": "string", "nullable": true, "description": "Location URL slug for storefront deep links" } }, "required": [ "id", "name", "logoImageUrl", "currency", "timezone" ] } }, "required": [ "uuid", "locationId", "latestState", "paymentMode", "totalAmountCents", "paidAmountCents", "remainingBalanceCents", "tabMembers", "location", "createdAt", "updatedAt" ] } } }, "required": [ "tabs" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/mine/{id}": { "get": { "summary": "Get a single tab the authenticated guest is a member of", "tags": [ "Tabs" ], "description": "Returns the same tab shape as GET /tabs/:id (members + items + location stub) but gated on tab_members.user_id matching the Bearer-authenticated guest. Returns 404 when the user is not a member of the tab.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true, "description": "Tab UUID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "latestState": { "type": "string", "enum": [ "initiated", "started", "instant", "closed", "settled", "aborted", "action_required" ], "description": "Current tab state" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "enum": [ "open_tab", "pay_upfront" ], "description": "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" }, "paymentSplit": { "type": "number", "nullable": true, "minimum": 2, "maximum": 10, "description": "Number of splits when in AMOUNT mode (2-10), null when in ITEM mode" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance to be paid in cents" }, "storefrontQrCodeId": { "type": "string", "nullable": true, "description": "Table/QR code UUID if applicable" }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation." }, "bookingConfirmationCode": { "type": "string", "nullable": true, "description": "Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page." }, "tabMembers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "storefrontSessionId": { "type": "string", "nullable": true, "description": "Storefront session ID" }, "initiator": { "type": "boolean", "description": "Whether this member initiated the tab" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retail user ID if applicable" }, "clientId": { "type": "string", "nullable": true, "description": "Client identifier (user UUID for identification)" }, "userEmail": { "type": "string", "nullable": true, "description": "User email (canonical, never overridden per-location)" }, "userName": { "type": "string", "nullable": true, "description": "Override-merged display name (falls back through retailer.name → ulo.display_name → users.name)" }, "isEnrolledInLoyalty": { "type": "boolean", "description": "Whether user is enrolled in location loyalty program" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "initiator", "memberType", "isEnrolledInLoyalty", "createdAt", "updatedAt" ] }, "description": "Tab members" }, "memberCount": { "type": "number", "description": "Number of guest tab_members (party size; excludes staff)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "latestState": { "type": "string", "description": "Current state of the dispatch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch item UUID" }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "itemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "tabMemberId": { "type": "string", "nullable": true, "description": "Tab member UUID who ordered this" }, "parentKitchenDispatchItemId": { "type": "string", "nullable": true, "description": "Parent kitchen dispatch item UUID (for nested items)" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications in cents" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "quantity": { "type": "number", "description": "Quantity ordered" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (for fractional items)" }, "splitOfKdi": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of original item if this is a split item (for grouping)" }, "tabSettlementId": { "type": "string", "nullable": true, "description": "Settlement UUID if paid" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state (payment_in_progress, settled)" }, "status": { "type": "string", "nullable": true, "description": "Item status" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "paidAmount": { "type": "number", "nullable": true, "description": "Amount paid for this item in cents" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "itemTitle": { "type": "string", "nullable": true, "description": "Item title from inventory" }, "itemTitlePrep": { "type": "string", "nullable": true, "description": "Item prep name from inventory" }, "itemDescription": { "type": "string", "nullable": true, "description": "Item description from inventory" }, "itemImageUrl": { "type": "string", "nullable": true, "description": "Item image URL from inventory" }, "tabMember": { "type": "object", "nullable": true, "description": "Guest/user information for the person who ordered this item", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" }, "phone": { "type": "string", "description": "Member phone number" }, "imageUrl": { "type": "string", "description": "Member profile image URL" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated user" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retailer user ID if staff member" } } }, "comments": { "type": "array", "description": "Comments on this item", "items": { "type": "object", "properties": { "comment": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "tabMemberUUID": { "type": "string", "nullable": true }, "uuid": { "type": "string", "format": "uuid" } } } }, "variants": { "type": "array", "description": "Variants/modifications on this item", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number", "description": "Price in cents (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } } } } }, "required": [ "uuid", "kitchenDispatchId", "price", "basePrice", "quantity", "createdAt", "updatedAt" ] }, "description": "Items in this dispatch" } }, "required": [ "uuid", "tabId", "locationId", "latestState", "createdAt", "updatedAt", "kitchenDispatchItems" ] }, "description": "Kitchen dispatches with items" }, "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "tab_vouchers.id (use with DELETE /vouchers/applied/:id)" }, "discountId": { "type": "number", "description": "discounts.id" }, "discountCode": { "type": "string", "description": "Voucher code as entered" }, "appliedAt": { "type": "string", "format": "date-time" }, "voucherName": { "type": "string", "nullable": true, "description": "discounts.name (internal name)" }, "voucherType": { "type": "string", "nullable": true }, "typeSpecification": { "type": "object", "nullable": true, "additionalProperties": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "hasUsesLeft": { "type": "boolean", "description": "Computed: maxUses null/0 OR timesUsed < maxUses" }, "remainingBalanceCents": { "type": "number", "nullable": true, "description": "For gift cards" }, "displayTitle": { "type": "string", "nullable": true, "description": "Guest-facing title" }, "displayDescription": { "type": "string", "nullable": true, "description": "Guest-facing description" }, "displayImageUrl": { "type": "string", "nullable": true, "description": "Thumbnail URL" } }, "required": [ "id", "discountId", "discountCode", "appliedAt", "timesUsed", "hasUsesLeft" ] }, "description": "Vouchers attached to this tab (from POS or storefront)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "description": "Entity type (tab, user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order (0 = first/top)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] }, "description": "Notes attached to this tab" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "location": { "type": "object", "properties": { "id": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "description": "Guest-facing location name (e.g. \"Café Saturnus\")" }, "logoImageUrl": { "type": "string", "nullable": true, "description": "Location logo URL for guest UI" }, "currency": { "type": "string", "nullable": true, "description": "ISO 4217 currency code (e.g. SEK)" }, "timezone": { "type": "string", "nullable": true, "description": "IANA timezone (e.g. Europe/Stockholm)" }, "slug": { "type": "string", "nullable": true, "description": "Location URL slug for storefront deep links" } }, "required": [ "id", "name", "logoImageUrl", "currency", "timezone" ] }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch item UUID" }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "itemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "tabMemberId": { "type": "string", "nullable": true, "description": "Tab member UUID who ordered this" }, "parentKitchenDispatchItemId": { "type": "string", "nullable": true, "description": "Parent kitchen dispatch item UUID (for nested items)" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications in cents" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "quantity": { "type": "number", "description": "Quantity ordered" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (for fractional items)" }, "splitOfKdi": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of original item if this is a split item (for grouping)" }, "tabSettlementId": { "type": "string", "nullable": true, "description": "Settlement UUID if paid" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state (payment_in_progress, settled)" }, "status": { "type": "string", "nullable": true, "description": "Item status" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "paidAmount": { "type": "number", "nullable": true, "description": "Amount paid for this item in cents" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "itemTitle": { "type": "string", "nullable": true, "description": "Item title from inventory" }, "itemTitlePrep": { "type": "string", "nullable": true, "description": "Item prep name from inventory" }, "itemDescription": { "type": "string", "nullable": true, "description": "Item description from inventory" }, "itemImageUrl": { "type": "string", "nullable": true, "description": "Item image URL from inventory" }, "tabMember": { "type": "object", "nullable": true, "description": "Guest/user information for the person who ordered this item", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" }, "phone": { "type": "string", "description": "Member phone number" }, "imageUrl": { "type": "string", "description": "Member profile image URL" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated user" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retailer user ID if staff member" } } }, "comments": { "type": "array", "description": "Comments on this item", "items": { "type": "object", "properties": { "comment": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "tabMemberUUID": { "type": "string", "nullable": true }, "uuid": { "type": "string", "format": "uuid" } } } }, "variants": { "type": "array", "description": "Variants/modifications on this item", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number", "description": "Price in cents (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } } } } }, "required": [ "uuid", "kitchenDispatchId", "price", "basePrice", "quantity", "createdAt", "updatedAt" ] }, "description": "Items currently on the tab." } }, "required": [ "uuid", "locationId", "latestState", "paymentMode", "totalAmountCents", "paidAmountCents", "remainingBalanceCents", "tabMembers", "location", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/reconnect-payment": { "post": { "summary": "Reconnect orphaned Adyen payment", "tags": [ "Tabs" ], "description": "Reconnect a payment that was authorized in Adyen but not recorded in Karma (due to terminal timeout). Creates a new purchase using the existing Adyen PSP reference. Karmeleon-only.\n\n**Permissions:** 🟠 `tabs.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "tab_id", "psp_reference" ], "properties": { "tab_id": { "type": "string", "format": "uuid", "description": "UUID of the tab to reconnect payment for" }, "psp_reference": { "type": "string", "description": "Adyen PSP reference from the orphaned authorization" }, "terminal_id": { "type": "string", "format": "uuid", "description": "Terminal ID (optional, for audit trail)" }, "amount_cents": { "type": "number", "minimum": 1, "description": "Amount in cents (optional, defaults to remaining balance)" } } } } }, "required": true }, "responses": { "200": { "description": "Payment reconnected successfully", "content": { "application/json": { "schema": { "description": "Payment reconnected successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "purchase_intent_id": { "type": "string", "format": "uuid" }, "tab_settlement_id": { "type": "string", "format": "uuid" }, "tab_id": { "type": "string", "format": "uuid" }, "psp_reference": { "type": "string" }, "amount_cents": { "type": "number" }, "reconnected": { "type": "boolean" } } }, "meta": { "type": "object" } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tabs/resolve": { "post": { "summary": "Resolve tab for user", "tags": [ "Tabs" ], "description": "Find existing tab or create new tab for a user. Handles QR code tables, user resolution with priority system (id > email > phone > identifier), tab member management, and order channel routing. Perfect for storefront integration before item commits.\n\n**Permissions:** 🟢 `tabs.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID for the tab" }, "qrCodeId": { "type": "string", "nullable": true, "description": "QR code UUID (for table orders)" }, "tabType": { "type": "string", "enum": [ "table", "takeaway", "over_the_counter" ], "description": "Type of tab to create" }, "paymentFlow": { "type": "string", "enum": [ "open_tab", "pay_upfront" ], "description": "Payment timing (open_tab = pay later, pay_upfront = pay now)" }, "orderChannel": { "type": "string", "enum": [ "ONLINE", "QR", "KIOSK", "POS" ], "description": "Order channel (ONLINE = web interface, QR = QR code scan, KIOSK = self-service, POS = point of sale)" }, "tabMember": { "type": "object", "properties": { "id": { "type": "number", "description": "User ID (Priority 1 - existing user)" }, "email": { "type": "string", "format": "email", "description": "Email address (Priority 2 - finds or creates user)" }, "phone": { "type": "string", "description": "Phone number (Priority 3 - finds or creates user)" }, "identifier": { "type": "string", "description": "Device identifier (Priority 4 - creates anonymous user)" }, "language": { "type": "string", "description": "BCP-47 locale code detected from the guest's browser (e.g. en, sv, fr)" } }, "additionalProperties": false, "description": "User identification with priority-based resolution: id > email > phone > identifier" } }, "required": [ "locationId", "qrCodeId", "tabType", "paymentFlow", "orderChannel", "tabMember" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "tabId": { "type": "string", "format": "uuid", "description": "Resolved tab UUID" }, "tabMemberId": { "type": "string", "format": "uuid", "description": "Tab member UUID for this user" }, "isNewTab": { "type": "boolean", "description": "True if tab was newly created" }, "isNewTabMember": { "type": "boolean", "description": "True if tab member was newly created" }, "tab": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "latestState": { "type": "string", "enum": [ "initiated", "started", "instant", "closed", "settled", "aborted", "action_required" ], "description": "Current tab state" }, "selectedPaymentFlow": { "type": "string", "nullable": true, "enum": [ "open_tab", "pay_upfront" ], "description": "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" }, "paymentMode": { "type": "string", "enum": [ "ITEM", "AMOUNT" ], "description": "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" }, "paymentSplit": { "type": "number", "nullable": true, "minimum": 2, "maximum": 10, "description": "Number of splits when in AMOUNT mode (2-10), null when in ITEM mode" }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents" }, "paidAmountCents": { "type": "number", "description": "Total paid amount in cents" }, "remainingBalanceCents": { "type": "number", "description": "Remaining balance to be paid in cents" }, "storefrontQrCodeId": { "type": "string", "nullable": true, "description": "Table/QR code UUID if applicable" }, "bookingId": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation." }, "bookingConfirmationCode": { "type": "string", "nullable": true, "description": "Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page." }, "tabMembers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "storefrontSessionId": { "type": "string", "nullable": true, "description": "Storefront session ID" }, "initiator": { "type": "boolean", "description": "Whether this member initiated the tab" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retail user ID if applicable" }, "clientId": { "type": "string", "nullable": true, "description": "Client identifier (user UUID for identification)" }, "userEmail": { "type": "string", "nullable": true, "description": "User email (canonical, never overridden per-location)" }, "userName": { "type": "string", "nullable": true, "description": "Override-merged display name (falls back through retailer.name → ulo.display_name → users.name)" }, "isEnrolledInLoyalty": { "type": "boolean", "description": "Whether user is enrolled in location loyalty program" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "initiator", "memberType", "isEnrolledInLoyalty", "createdAt", "updatedAt" ] }, "description": "Tab members" }, "memberCount": { "type": "number", "description": "Number of guest tab_members (party size; excludes staff)" }, "kitchenDispatches": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "tabId": { "type": "string", "format": "uuid", "description": "Tab UUID" }, "locationId": { "type": "number", "description": "Location ID" }, "dailyOrderNumber": { "type": "number", "nullable": true, "description": "Daily order number" }, "latestState": { "type": "string", "description": "Current state of the dispatch" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "kitchenDispatchItems": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Kitchen dispatch item UUID" }, "kitchenDispatchId": { "type": "string", "format": "uuid", "description": "Kitchen dispatch UUID" }, "saleItemId": { "type": "number", "nullable": true, "description": "Sale item ID" }, "itemId": { "type": "number", "nullable": true, "description": "Inventory item ID" }, "tabMemberId": { "type": "string", "nullable": true, "description": "Tab member UUID who ordered this" }, "parentKitchenDispatchItemId": { "type": "string", "nullable": true, "description": "Parent kitchen dispatch item UUID (for nested items)" }, "price": { "type": "number", "description": "Item price in cents" }, "basePrice": { "type": "number", "description": "Base price before modifications in cents" }, "discount": { "type": "number", "nullable": true, "description": "Discount amount in cents" }, "quantity": { "type": "number", "description": "Quantity ordered" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (for fractional items)" }, "splitOfKdi": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID of original item if this is a split item (for grouping)" }, "tabSettlementId": { "type": "string", "nullable": true, "description": "Settlement UUID if paid" }, "settlementState": { "type": "string", "nullable": true, "description": "Settlement state (payment_in_progress, settled)" }, "status": { "type": "string", "nullable": true, "description": "Item status" }, "itemState": { "type": "string", "nullable": true, "description": "Kitchen-side item state ('aborted' = voided)" }, "voidedQuantityCents": { "type": "number", "nullable": true, "description": "Voided slice in cents (read from platform_events) — null when not aborted" }, "paidAmount": { "type": "number", "nullable": true, "description": "Amount paid for this item in cents" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "itemTitle": { "type": "string", "nullable": true, "description": "Item title from inventory" }, "itemTitlePrep": { "type": "string", "nullable": true, "description": "Item prep name from inventory" }, "itemDescription": { "type": "string", "nullable": true, "description": "Item description from inventory" }, "itemImageUrl": { "type": "string", "nullable": true, "description": "Item image URL from inventory" }, "tabMember": { "type": "object", "nullable": true, "description": "Guest/user information for the person who ordered this item", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "name": { "type": "string", "description": "Member name" }, "email": { "type": "string", "description": "Member email" }, "phone": { "type": "string", "description": "Member phone number" }, "imageUrl": { "type": "string", "description": "Member profile image URL" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated user" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retailer user ID if staff member" } } }, "comments": { "type": "array", "description": "Comments on this item", "items": { "type": "object", "properties": { "comment": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "tabMemberUUID": { "type": "string", "nullable": true }, "uuid": { "type": "string", "format": "uuid" } } } }, "variants": { "type": "array", "description": "Variants/modifications on this item", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "price": { "type": "number", "description": "Price in cents (positive or negative)" }, "quantityCents": { "type": "number", "nullable": true, "description": "Quantity in cents (100 = 1.0). NULL = default 1.0" }, "priceCents": { "type": "number", "nullable": true, "description": "Price at time of order in cents. NULL = look up from variants table" } } } } }, "required": [ "uuid", "kitchenDispatchId", "price", "basePrice", "quantity", "createdAt", "updatedAt" ] }, "description": "Items in this dispatch" } }, "required": [ "uuid", "tabId", "locationId", "latestState", "createdAt", "updatedAt", "kitchenDispatchItems" ] }, "description": "Kitchen dispatches with items" }, "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "tab_vouchers.id (use with DELETE /vouchers/applied/:id)" }, "discountId": { "type": "number", "description": "discounts.id" }, "discountCode": { "type": "string", "description": "Voucher code as entered" }, "appliedAt": { "type": "string", "format": "date-time" }, "voucherName": { "type": "string", "nullable": true, "description": "discounts.name (internal name)" }, "voucherType": { "type": "string", "nullable": true }, "typeSpecification": { "type": "object", "nullable": true, "additionalProperties": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "hasUsesLeft": { "type": "boolean", "description": "Computed: maxUses null/0 OR timesUsed < maxUses" }, "remainingBalanceCents": { "type": "number", "nullable": true, "description": "For gift cards" }, "displayTitle": { "type": "string", "nullable": true, "description": "Guest-facing title" }, "displayDescription": { "type": "string", "nullable": true, "description": "Guest-facing description" }, "displayImageUrl": { "type": "string", "nullable": true, "description": "Thumbnail URL" } }, "required": [ "id", "discountId", "discountCode", "appliedAt", "timesUsed", "hasUsesLeft" ] }, "description": "Vouchers attached to this tab (from POS or storefront)" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Note UUID" }, "entityType": { "type": "string", "description": "Entity type (tab, user)" }, "entityId": { "type": "string", "description": "Entity ID (tab UUID or user ID)" }, "note": { "type": "string", "description": "Note content" }, "locationId": { "type": "number", "description": "Location ID" }, "sortOrder": { "type": "number", "description": "Sort order (0 = first/top)" }, "createdByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who created the note" }, "createdByName": { "type": "string", "nullable": true, "description": "Name of user who created the note" }, "updatedByRetailerUserId": { "type": "number", "nullable": true, "description": "Retailer user who last updated the note" }, "updatedByName": { "type": "string", "nullable": true, "description": "Name of user who last updated the note" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "entityType", "entityId", "note", "locationId", "sortOrder", "createdAt", "updatedAt" ] }, "description": "Notes attached to this tab" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "locationId", "latestState", "paymentMode", "totalAmountCents", "paidAmountCents", "remainingBalanceCents", "tabMembers", "createdAt", "updatedAt" ] }, "tabMembers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Tab member UUID" }, "storefrontSessionId": { "type": "string", "nullable": true, "description": "Storefront session ID" }, "initiator": { "type": "boolean", "description": "Whether this member initiated the tab" }, "memberType": { "type": "string", "description": "Member type (guest, user, etc.)" }, "userId": { "type": "number", "nullable": true, "description": "User ID if authenticated" }, "retailUserId": { "type": "number", "nullable": true, "description": "Retail user ID if applicable" }, "clientId": { "type": "string", "nullable": true, "description": "Client identifier (user UUID for identification)" }, "userEmail": { "type": "string", "nullable": true, "description": "User email (canonical, never overridden per-location)" }, "userName": { "type": "string", "nullable": true, "description": "Override-merged display name (falls back through retailer.name → ulo.display_name → users.name)" }, "isEnrolledInLoyalty": { "type": "boolean", "description": "Whether user is enrolled in location loyalty program" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "uuid", "initiator", "memberType", "isEnrolledInLoyalty", "createdAt", "updatedAt" ] }, "description": "All current tab members" } }, "required": [ "tabId", "tabMemberId", "isNewTab", "isNewTabMember", "tab", "tabMembers" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/terminals": { "get": { "summary": "List payment terminals", "tags": [ "Terminals" ], "description": "Get all payment terminals for a location\n\n**Permissions:** 🔵 `terminals.read`", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID to fetch terminals for" } ], "responses": { "200": { "description": "Terminals fetched successfully", "content": { "application/json": { "schema": { "description": "Terminals fetched successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Terminal UUID" }, "externalId": { "type": "string", "description": "External terminal ID from payment provider" }, "locationId": { "type": "integer", "description": "Location ID this terminal belongs to" }, "createdAt": { "type": "string", "format": "date-time", "description": "Terminal creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Terminal last update timestamp" }, "title": { "type": "string", "description": "Terminal display name" }, "type": { "oneOf": [ { "type": "string", "enum": [ "p400plus", "s1f2", "s1u2", "s1e2l", "v400cplus", "v400m", "any" ], "description": "Terminal hardware type" }, { "type": "null" } ], "description": "Terminal hardware type (null if not specified)" } }, "required": [ "id", "externalId", "locationId", "createdAt", "updatedAt", "title", "type" ] }, "description": "Array of terminals" }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/terminals/statuses": { "get": { "summary": "Get terminal statuses", "tags": [ "Terminals" ], "description": "Get real-time connection status for all terminals at a location\n\n**Permissions:** 🔵 `terminals.read`", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID to fetch terminal statuses for" } ], "responses": { "200": { "description": "Terminal statuses fetched successfully", "content": { "application/json": { "schema": { "description": "Terminal statuses fetched successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "terminals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Terminal UUID" }, "externalId": { "type": "string", "description": "External terminal ID from payment provider" }, "locationId": { "type": "integer", "description": "Location ID this terminal belongs to" }, "createdAt": { "type": "string", "format": "date-time", "description": "Terminal creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Terminal last update timestamp" }, "title": { "type": "string", "description": "Terminal display name" }, "type": { "oneOf": [ { "type": "string", "enum": [ "p400plus", "s1f2", "s1u2", "s1e2l", "v400cplus", "v400m", "any" ], "description": "Terminal hardware type" }, { "type": "null" } ], "description": "Terminal hardware type (null if not specified)" } }, "required": [ "id", "externalId", "locationId", "createdAt", "updatedAt", "title", "type" ] }, "description": "Array of terminals" }, "message": { "type": "string", "description": "Information about status updates" } }, "required": [ "terminals", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/locations/{locationId}/time-slots/{date}": { "get": { "summary": "Get time slots for a location on a specific date", "tags": [ "Time Slots" ], "description": "\nGenerates available time slots for pickup/ordering at a location on a specific date.\n\nTime slots are generated based on:\n- The location's opening hours from the schedules system\n- The location's configured time slot duration (e.g., 10 or 15 minutes)\n- Any exceptions (holidays, special closures)\n\nIf the location is closed on the requested date (either by regular hours or exception),\nan empty time slots array is returned.\n\n**Note:** This endpoint requires API key authentication.\n", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "path", "name": "date", "required": true, "description": "Date in YYYY-MM-DD format" } ], "responses": { "200": { "description": "Time slots retrieved successfully", "content": { "application/json": { "schema": { "description": "Time slots retrieved successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "timeSlots": { "type": "array", "items": { "type": "object", "properties": { "startsAt": { "type": "string", "format": "date-time", "description": "Slot start time (ISO 8601)" }, "endsAt": { "type": "string", "format": "date-time", "description": "Slot end time (ISO 8601)" }, "capacities": { "type": "object", "nullable": true, "properties": { "orders": { "type": "object", "nullable": true, "properties": { "capacity": { "type": "number", "description": "Maximum allowed capacity" }, "count": { "type": "number", "description": "Current count" } }, "required": [ "capacity", "count" ] }, "items": { "type": "object", "nullable": true, "properties": { "capacity": { "type": "number", "description": "Maximum allowed capacity" }, "count": { "type": "number", "description": "Current count" } }, "required": [ "capacity", "count" ] } }, "required": [ "orders", "items" ] } }, "required": [ "startsAt", "endsAt" ] }, "description": "List of available time slots" } }, "required": [ "timeSlots" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tokens/balance": { "get": { "tags": [ "Tokens" ], "description": "Get token balance and limits for a location", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID to get token balance for" } ], "x-internal": true, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "locationId": { "type": "number" }, "balance": { "type": "number", "description": "Current token balance" }, "monthlyLimit": { "type": "number", "nullable": true, "description": "Monthly token limit (null = unlimited)" }, "dailyLimit": { "type": "number", "nullable": true, "description": "Daily token limit (null = unlimited)" }, "totalUsed": { "type": "number", "description": "Total tokens used (lifetime)" }, "usageToday": { "type": "number", "description": "Tokens used today" }, "usageThisMonth": { "type": "number", "description": "Tokens used this month" }, "lastResetAt": { "type": "string", "format": "date-time", "nullable": true } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/tokens/usage": { "get": { "tags": [ "Tokens" ], "description": "Get token usage history with filtering and pagination", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID to get usage for" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Filter from this date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "Filter to this date (ISO 8601)" }, { "schema": { "type": "string", "enum": [ "llm_input", "llm_output", "bigquery", "image_gen", "content_gen" ] }, "in": "query", "name": "transactionType", "required": false, "description": "Filter by transaction type" }, { "schema": { "type": "number", "default": 1, "minimum": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "default": 50, "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false, "description": "Items per page (max 1000)" } ], "x-internal": true, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "transactionType": { "type": "string" }, "tokensUsed": { "type": "number" }, "costCents": { "type": "number", "nullable": true }, "serviceName": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "object", "nullable": true, "properties": { "id": { "type": "number" }, "name": { "type": "string" } } } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "number" }, "limit": { "type": "number" }, "totalItems": { "type": "number" }, "totalPages": { "type": "number" } } }, "summary": { "type": "object", "properties": { "totalTokens": { "type": "number" }, "totalCostCents": { "type": "number" }, "byType": { "type": "object", "additionalProperties": { "type": "number" } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/translations/inventory": { "get": { "tags": [ "Translations" ], "description": "Get translated inventory items by location and locale with ID-keyed response for simple client merging", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": true, "description": "Location ID" }, { "schema": { "type": "string", "enum": [ "en", "sv", "no", "fi", "es", "de", "fr", "ar", "pl", "ru", "zh", "ja" ] }, "in": "query", "name": "locale", "required": true, "description": "Target language code" }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "includeVariants", "required": false, "description": "Include variant group translations" }, { "schema": { "type": "number", "default": 1, "minimum": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number for pagination" }, { "schema": { "type": "number", "default": 100, "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false, "description": "Items per page (max 1000)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "inventory": { "type": "object", "description": "ID-keyed inventory translations (item ID → translations)", "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "description": "Translated item title" }, "description": { "type": "string", "description": "Translated item description" }, "ingredients": { "type": "string", "description": "Translated item ingredients" } }, "required": [ "title" ] } }, "variants": { "type": "object", "description": "ID-keyed variant group translations (variant group ID → translations)", "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "description": "Translated variant group title" }, "choices": { "type": "object", "description": "ID-keyed choice translations (choice ID → translations)", "additionalProperties": { "type": "object", "properties": { "title": { "type": "string", "description": "Translated choice title" } }, "required": [ "title" ] } } }, "required": [ "title", "choices" ] } }, "metadata": { "type": "object", "properties": { "totalItems": { "type": "number", "description": "Total number of items translated" }, "uniqueStrings": { "type": "number", "description": "Number of unique strings (after deduplication)" }, "cacheHits": { "type": "number", "description": "Number of translations served from cache" }, "cacheMisses": { "type": "number", "description": "Number of translations fetched from Google Translate" }, "executionTimeMs": { "type": "number", "description": "Total execution time in milliseconds" } }, "required": [ "totalItems", "uniqueStrings", "cacheHits", "cacheMisses", "executionTimeMs" ] } }, "required": [ "inventory", "variants", "metadata" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "description": "Bad Request - Invalid parameters", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "description": "Forbidden - Insufficient permissions", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "description": "Internal Server Error", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/variant-groups": { "get": { "summary": "List variant groups", "tags": [ "Variant Groups" ], "description": "List variant groups with optional filtering\n\n**Permissions:** 🔵 `variant_groups.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "locationId", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "string", "enum": [ "EXTRA", "VARIANT" ] }, "in": "query", "name": "type", "required": false, "description": "Filter by group type" }, { "schema": { "type": "boolean", "default": true }, "in": "query", "name": "includeVariants", "required": false, "description": "Include variants in response" }, { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "variantGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique variant group ID" }, "locationId": { "type": "number", "description": "Location ID this group belongs to" }, "name": { "type": "string", "description": "Variant group name" }, "type": { "type": "string", "enum": [ "EXTRA", "VARIANT" ], "description": "Group type (EXTRA: add-ons, VARIANT: alternatives)" }, "description": { "type": "string", "nullable": true, "description": "Group description" }, "min": { "type": "number", "minimum": 0, "description": "Minimum number of variants that must be selected (0 = optional)" }, "max": { "type": "number", "nullable": true, "description": "Maximum number of variants that can be selected (null = unlimited)" }, "isVisible": { "type": "boolean", "description": "Whether the variant group is visible in UI" }, "useChildCoursing": { "type": "boolean", "description": "When true, item-based variant children commit with their own coursing_order instead of inheriting the parent item's" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique variant ID" }, "variantGroupId": { "type": "number", "description": "Variant group ID this belongs to" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "nullable": true, "description": "Price modifier in cents (null for item-based variants)" }, "defaultSelection": { "type": "boolean", "description": "Whether this is selected by default" }, "description": { "type": "string", "nullable": true, "description": "Variant description" }, "rank": { "type": "number", "nullable": true, "description": "Display order rank" }, "itemId": { "type": "number", "nullable": true, "description": "Reference to inventory item (for item-based variants)" }, "quantity": { "type": "number", "description": "Legacy: default quantity as integer (use quantityCents instead)" }, "allowQuantityChange": { "type": "boolean", "description": "Whether guests can change the quantity" }, "minQuantity": { "type": "number", "nullable": true, "description": "Legacy: minimum quantity as integer (use minQuantityCents instead)" }, "maxQuantity": { "type": "number", "nullable": true, "description": "Legacy: maximum quantity as integer (use maxQuantityCents instead)" }, "quantityCents": { "type": "number", "description": "Default quantity in cents (100 = 1.0, 50 = 0.5)" }, "minQuantityCents": { "type": "number", "nullable": true, "description": "Minimum quantity in cents (only applies if allowQuantityChange is true)" }, "maxQuantityCents": { "type": "number", "nullable": true, "description": "Maximum quantity in cents (only applies if allowQuantityChange is true)" } }, "required": [ "id", "variantGroupId", "name", "defaultSelection", "quantity", "allowQuantityChange", "quantityCents" ] }, "description": "Variants in this group" } }, "required": [ "id", "locationId", "name", "type", "min", "isVisible", "useChildCoursing", "variants" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "variantGroups", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create variant group", "tags": [ "Variant Groups" ], "description": "Create a new variant group with variants\n\n**Permissions:** 🟢 `variant_groups.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "number", "description": "Location ID" }, "name": { "type": "string", "minLength": 1, "description": "Group name" }, "type": { "type": "string", "enum": [ "EXTRA", "VARIANT" ] }, "description": { "type": "string", "nullable": true }, "min": { "type": "number", "minimum": 0, "default": 0 }, "max": { "type": "number", "nullable": true, "minimum": 1 }, "isVisible": { "type": "boolean", "default": true }, "useChildCoursing": { "type": "boolean", "default": false, "description": "When true, item-based variant children commit with their own coursing_order" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Variant name" }, "price": { "type": "number", "nullable": true, "description": "Price modifier in cents" }, "defaultSelection": { "type": "boolean", "default": false }, "description": { "type": "string", "nullable": true }, "rank": { "type": "number", "nullable": true }, "itemId": { "type": "number", "nullable": true, "description": "Reference to inventory item" }, "quantity": { "type": "number", "default": 1, "minimum": 1, "description": "Legacy: default quantity as integer" }, "allowQuantityChange": { "type": "boolean", "default": false }, "quantityCents": { "type": "number", "default": 100, "minimum": 1, "description": "Default quantity in cents (100 = 1.0, 50 = 0.5). Takes precedence over quantity." }, "minQuantityCents": { "type": "number", "nullable": true, "description": "Minimum quantity in cents" }, "maxQuantityCents": { "type": "number", "nullable": true, "description": "Maximum quantity in cents" } }, "required": [ "name" ] }, "description": "Initial variants for this group" } }, "required": [ "locationId", "name", "type", "variants" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique variant group ID" }, "locationId": { "type": "number", "description": "Location ID this group belongs to" }, "name": { "type": "string", "description": "Variant group name" }, "type": { "type": "string", "enum": [ "EXTRA", "VARIANT" ], "description": "Group type (EXTRA: add-ons, VARIANT: alternatives)" }, "description": { "type": "string", "nullable": true, "description": "Group description" }, "min": { "type": "number", "minimum": 0, "description": "Minimum number of variants that must be selected (0 = optional)" }, "max": { "type": "number", "nullable": true, "description": "Maximum number of variants that can be selected (null = unlimited)" }, "isVisible": { "type": "boolean", "description": "Whether the variant group is visible in UI" }, "useChildCoursing": { "type": "boolean", "description": "When true, item-based variant children commit with their own coursing_order instead of inheriting the parent item's" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique variant ID" }, "variantGroupId": { "type": "number", "description": "Variant group ID this belongs to" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "nullable": true, "description": "Price modifier in cents (null for item-based variants)" }, "defaultSelection": { "type": "boolean", "description": "Whether this is selected by default" }, "description": { "type": "string", "nullable": true, "description": "Variant description" }, "rank": { "type": "number", "nullable": true, "description": "Display order rank" }, "itemId": { "type": "number", "nullable": true, "description": "Reference to inventory item (for item-based variants)" }, "quantity": { "type": "number", "description": "Legacy: default quantity as integer (use quantityCents instead)" }, "allowQuantityChange": { "type": "boolean", "description": "Whether guests can change the quantity" }, "minQuantity": { "type": "number", "nullable": true, "description": "Legacy: minimum quantity as integer (use minQuantityCents instead)" }, "maxQuantity": { "type": "number", "nullable": true, "description": "Legacy: maximum quantity as integer (use maxQuantityCents instead)" }, "quantityCents": { "type": "number", "description": "Default quantity in cents (100 = 1.0, 50 = 0.5)" }, "minQuantityCents": { "type": "number", "nullable": true, "description": "Minimum quantity in cents (only applies if allowQuantityChange is true)" }, "maxQuantityCents": { "type": "number", "nullable": true, "description": "Maximum quantity in cents (only applies if allowQuantityChange is true)" } }, "required": [ "id", "variantGroupId", "name", "defaultSelection", "quantity", "allowQuantityChange", "quantityCents" ] }, "description": "Variants in this group" } }, "required": [ "id", "locationId", "name", "type", "min", "isVisible", "useChildCoursing", "variants" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/variant-groups/{id}": { "get": { "summary": "Get variant group", "tags": [ "Variant Groups" ], "description": "Get a single variant group by ID with its variants\n\n**Permissions:** 🔵 `variant_groups.read`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Variant group ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique variant group ID" }, "locationId": { "type": "number", "description": "Location ID this group belongs to" }, "name": { "type": "string", "description": "Variant group name" }, "type": { "type": "string", "enum": [ "EXTRA", "VARIANT" ], "description": "Group type (EXTRA: add-ons, VARIANT: alternatives)" }, "description": { "type": "string", "nullable": true, "description": "Group description" }, "min": { "type": "number", "minimum": 0, "description": "Minimum number of variants that must be selected (0 = optional)" }, "max": { "type": "number", "nullable": true, "description": "Maximum number of variants that can be selected (null = unlimited)" }, "isVisible": { "type": "boolean", "description": "Whether the variant group is visible in UI" }, "useChildCoursing": { "type": "boolean", "description": "When true, item-based variant children commit with their own coursing_order instead of inheriting the parent item's" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique variant ID" }, "variantGroupId": { "type": "number", "description": "Variant group ID this belongs to" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "nullable": true, "description": "Price modifier in cents (null for item-based variants)" }, "defaultSelection": { "type": "boolean", "description": "Whether this is selected by default" }, "description": { "type": "string", "nullable": true, "description": "Variant description" }, "rank": { "type": "number", "nullable": true, "description": "Display order rank" }, "itemId": { "type": "number", "nullable": true, "description": "Reference to inventory item (for item-based variants)" }, "quantity": { "type": "number", "description": "Legacy: default quantity as integer (use quantityCents instead)" }, "allowQuantityChange": { "type": "boolean", "description": "Whether guests can change the quantity" }, "minQuantity": { "type": "number", "nullable": true, "description": "Legacy: minimum quantity as integer (use minQuantityCents instead)" }, "maxQuantity": { "type": "number", "nullable": true, "description": "Legacy: maximum quantity as integer (use maxQuantityCents instead)" }, "quantityCents": { "type": "number", "description": "Default quantity in cents (100 = 1.0, 50 = 0.5)" }, "minQuantityCents": { "type": "number", "nullable": true, "description": "Minimum quantity in cents (only applies if allowQuantityChange is true)" }, "maxQuantityCents": { "type": "number", "nullable": true, "description": "Maximum quantity in cents (only applies if allowQuantityChange is true)" } }, "required": [ "id", "variantGroupId", "name", "defaultSelection", "quantity", "allowQuantityChange", "quantityCents" ] }, "description": "Variants in this group" } }, "required": [ "id", "locationId", "name", "type", "min", "isVisible", "useChildCoursing", "variants" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update variant group", "tags": [ "Variant Groups" ], "description": "Update an existing variant group\n\n**Permissions:** 🟠 `variant_groups.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "nullable": true }, "min": { "type": "number", "minimum": 0 }, "max": { "type": "number", "nullable": true, "minimum": 1 }, "isVisible": { "type": "boolean" }, "useChildCoursing": { "type": "boolean", "description": "When true, item-based variant children commit with their own coursing_order" } } } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Variant group ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique variant group ID" }, "locationId": { "type": "number", "description": "Location ID this group belongs to" }, "name": { "type": "string", "description": "Variant group name" }, "type": { "type": "string", "enum": [ "EXTRA", "VARIANT" ], "description": "Group type (EXTRA: add-ons, VARIANT: alternatives)" }, "description": { "type": "string", "nullable": true, "description": "Group description" }, "min": { "type": "number", "minimum": 0, "description": "Minimum number of variants that must be selected (0 = optional)" }, "max": { "type": "number", "nullable": true, "description": "Maximum number of variants that can be selected (null = unlimited)" }, "isVisible": { "type": "boolean", "description": "Whether the variant group is visible in UI" }, "useChildCoursing": { "type": "boolean", "description": "When true, item-based variant children commit with their own coursing_order instead of inheriting the parent item's" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique variant ID" }, "variantGroupId": { "type": "number", "description": "Variant group ID this belongs to" }, "name": { "type": "string", "description": "Variant name" }, "price": { "type": "number", "nullable": true, "description": "Price modifier in cents (null for item-based variants)" }, "defaultSelection": { "type": "boolean", "description": "Whether this is selected by default" }, "description": { "type": "string", "nullable": true, "description": "Variant description" }, "rank": { "type": "number", "nullable": true, "description": "Display order rank" }, "itemId": { "type": "number", "nullable": true, "description": "Reference to inventory item (for item-based variants)" }, "quantity": { "type": "number", "description": "Legacy: default quantity as integer (use quantityCents instead)" }, "allowQuantityChange": { "type": "boolean", "description": "Whether guests can change the quantity" }, "minQuantity": { "type": "number", "nullable": true, "description": "Legacy: minimum quantity as integer (use minQuantityCents instead)" }, "maxQuantity": { "type": "number", "nullable": true, "description": "Legacy: maximum quantity as integer (use maxQuantityCents instead)" }, "quantityCents": { "type": "number", "description": "Default quantity in cents (100 = 1.0, 50 = 0.5)" }, "minQuantityCents": { "type": "number", "nullable": true, "description": "Minimum quantity in cents (only applies if allowQuantityChange is true)" }, "maxQuantityCents": { "type": "number", "nullable": true, "description": "Maximum quantity in cents (only applies if allowQuantityChange is true)" } }, "required": [ "id", "variantGroupId", "name", "defaultSelection", "quantity", "allowQuantityChange", "quantityCents" ] }, "description": "Variants in this group" } }, "required": [ "id", "locationId", "name", "type", "min", "isVisible", "useChildCoursing", "variants" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete variant group", "tags": [ "Variant Groups" ], "description": "Delete a variant group and its variants\n\n**Permissions:** 🔴 `variant_groups.delete`", "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "in": "path", "name": "id", "required": true, "description": "Variant group ID" } ], "responses": { "200": { "description": "Variant group successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/vouchers": { "get": { "summary": "List vouchers", "tags": [ "Vouchers" ], "description": "List all vouchers with optional filters and pagination\n\n**Permissions:** 🔵 `vouchers.read`", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "location_id", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "number" }, "in": "query", "name": "company_id", "required": false, "description": "Filter by company ID" }, { "schema": { "type": "string", "enum": [ "DISCOUNT_CODE", "GIFT_CARD", "PROMOTION", "LOYALTY_REWARD", "CAMPAIGN", "REFERRAL" ] }, "in": "query", "name": "voucher_type", "required": false, "description": "Filter by voucher type" }, { "schema": { "type": "boolean" }, "in": "query", "name": "enabled", "required": false, "description": "Filter by enabled status" }, { "schema": { "type": "boolean" }, "in": "query", "name": "is_template", "required": false, "description": "Filter by template status" }, { "schema": { "type": "string" }, "in": "query", "name": "code", "required": false, "description": "Exact code match" }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Search in name or code" }, { "schema": { "type": "boolean" }, "in": "query", "name": "include_restrictions", "required": false, "description": "Include restrictions in response" }, { "schema": { "type": "number", "default": 1, "minimum": 1 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "number", "default": 50, "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "default": "created_at" }, "in": "query", "name": "sort", "required": false }, { "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" }, "in": "query", "name": "order", "required": false } ], "responses": { "200": { "description": "List of vouchers", "content": { "application/json": { "schema": { "description": "List of vouchers", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number", "nullable": true }, "companyId": { "type": "number", "nullable": true }, "name": { "type": "string" }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "voucherType": { "type": "string", "enum": [ "DISCOUNT_CODE", "GIFT_CARD", "PROMOTION", "LOYALTY_REWARD", "CAMPAIGN", "REFERRAL" ] }, "balanceMode": { "type": "string", "enum": [ "NONE", "DECREMENTAL" ] }, "typeSpecification": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "balance", "free_item", "fixed_price", "formula" ] }, "amountInBasisPoints": { "type": "number", "description": "For percentage discounts (10000 = 100%)" }, "amountInCents": { "type": "number", "description": "For fixed amount discounts" }, "freeItemIds": { "type": "array", "items": { "type": "number" }, "description": "Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line." }, "freeItemQuantity": { "type": "number", "description": "Per-line cap for free items (defaults to 1)" }, "freeItemId": { "type": "number", "description": "DEPRECATED — use freeItemIds. Retained for legacy vouchers." }, "targetItemIds": { "type": "array", "items": { "type": "number" }, "description": "For fixed_price action: items repriced down to fixedPriceCents." }, "fixedPriceCents": { "type": "number", "description": "For fixed_price action: target per-unit base price in cents." }, "formula": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "buy_x_get_y", "tiered", "spend_threshold", "bundle", "combo_groups" ] }, "rules": { "type": "object", "description": "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." } } } }, "required": [ "type" ] }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "perUserUses": { "type": "number", "nullable": true }, "minOrderAmountCents": { "type": "number", "nullable": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "initialBalanceCents": { "type": "number", "nullable": true }, "remainingBalanceCents": { "type": "number", "nullable": true }, "canCombine": { "type": "boolean" }, "autoApply": { "type": "boolean" }, "validFrom": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time", "nullable": true }, "displayTitle": { "type": "string", "nullable": true }, "displayDescription": { "type": "string", "nullable": true }, "displayImageUrl": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "restrictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "discountId": { "type": "number" }, "restrictionType": { "type": "string", "enum": [ "INCLUDE_ITEM", "EXCLUDE_ITEM", "INCLUDE_TAG", "EXCLUDE_TAG", "INCLUDE_LAYOUT", "EXCLUDE_LAYOUT", "INCLUDE_VARIANT", "EXCLUDE_VARIANT", "REQUIRE_ITEM", "REQUIRE_ITEM_WITH_VARIANTS", "REQUIRE_TAG", "MIN_ITEM_COUNT" ] }, "entityId": { "type": "number" }, "quantity": { "type": "number", "nullable": true }, "variantIds": { "type": "array", "items": { "type": "number" }, "nullable": true, "description": "Required variant ids on the same line for REQUIRE_ITEM_WITH_VARIANTS rows." }, "createdAt": { "type": "string", "format": "date-time" } } } }, "userRestrictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "discountId": { "type": "number" }, "restrictionType": { "type": "string", "enum": [ "EMAIL", "PHONE", "USER_ID", "SEGMENT_ID" ] }, "value": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "number" }, "limit": { "type": "number" }, "total": { "type": "number" }, "totalPages": { "type": "number" } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } }, "post": { "summary": "Create voucher", "tags": [ "Vouchers" ], "description": "Create a new voucher with optional restrictions\n\n**Permissions:** 🟢 `vouchers.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "code", "voucherType", "typeSpecification" ], "properties": { "locationId": { "type": "number", "description": "Location ID (required if companyId not set)" }, "companyId": { "type": "number", "description": "Company ID (required if locationId not set)" }, "name": { "type": "string", "description": "Internal voucher name" }, "code": { "type": "string", "description": "Voucher code (will be uppercased)" }, "enabled": { "type": "boolean", "default": true }, "voucherType": { "type": "string", "enum": [ "DISCOUNT_CODE", "GIFT_CARD", "PROMOTION", "LOYALTY_REWARD", "CAMPAIGN", "REFERRAL" ] }, "balanceMode": { "type": "string", "enum": [ "NONE", "DECREMENTAL" ], "default": "NONE" }, "typeSpecification": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "balance", "free_item", "fixed_price", "formula" ] }, "amountInBasisPoints": { "type": "number", "description": "For percentage discounts (10000 = 100%)" }, "amountInCents": { "type": "number", "description": "For fixed amount discounts" }, "freeItemIds": { "type": "array", "items": { "type": "number" }, "description": "Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line." }, "freeItemQuantity": { "type": "number", "description": "Per-line cap for free items (defaults to 1)" }, "freeItemId": { "type": "number", "description": "DEPRECATED — use freeItemIds. Retained for legacy vouchers." }, "targetItemIds": { "type": "array", "items": { "type": "number" }, "description": "For fixed_price action: items repriced down to fixedPriceCents." }, "fixedPriceCents": { "type": "number", "description": "For fixed_price action: target per-unit base price in cents." }, "formula": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "buy_x_get_y", "tiered", "spend_threshold", "bundle", "combo_groups" ] }, "rules": { "type": "object", "description": "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." } } } }, "required": [ "type" ] }, "maxUses": { "type": "number", "description": "Total usage limit" }, "perUserUses": { "type": "number", "description": "Per-user usage limit" }, "minOrderAmountCents": { "type": "number", "description": "Minimum order amount in cents" }, "maxDiscountAmountCents": { "type": "number", "description": "Maximum discount cap in cents" }, "initialBalanceCents": { "type": "number", "description": "Initial balance for gift cards" }, "canCombine": { "type": "boolean", "default": false }, "autoApply": { "type": "boolean", "default": false }, "validFrom": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time" }, "displayTitle": { "type": "string", "description": "Guest-facing title" }, "displayDescription": { "type": "string", "description": "Guest-facing description" }, "displayImageUrl": { "type": "string", "description": "Gift card image URL" }, "alwaysVisible": { "type": "boolean", "default": false, "description": "Show promotion even when requirements not met" }, "isTemplate": { "type": "boolean", "default": false, "description": "Whether this is a template voucher" }, "templateVoucherId": { "type": "number", "description": "Parent template voucher ID" }, "restrictions": { "type": "array", "items": { "type": "object", "properties": { "restrictionType": { "type": "string", "enum": [ "INCLUDE_ITEM", "EXCLUDE_ITEM", "INCLUDE_TAG", "EXCLUDE_TAG", "INCLUDE_LAYOUT", "EXCLUDE_LAYOUT", "INCLUDE_VARIANT", "EXCLUDE_VARIANT", "REQUIRE_ITEM", "REQUIRE_ITEM_WITH_VARIANTS", "REQUIRE_TAG", "MIN_ITEM_COUNT" ] }, "entityId": { "type": "number", "description": "Item/tag/layout ID (0 for MIN_ITEM_COUNT)" }, "quantity": { "type": "number", "description": "Required quantity for REQUIRE_ITEM / REQUIRE_ITEM_WITH_VARIANTS / MIN_ITEM_COUNT" }, "variantIds": { "type": "array", "items": { "type": "number" }, "description": "For REQUIRE_ITEM_WITH_VARIANTS: variant ids that must ALL be selected on the same cart line as the item." } }, "required": [ "restrictionType", "entityId" ] } }, "userRestrictions": { "type": "array", "items": { "type": "object", "properties": { "restrictionType": { "type": "string", "enum": [ "EMAIL", "PHONE", "USER_ID", "SEGMENT_ID" ] }, "value": { "type": "string", "description": "Email/phone/user_id/segment_id" } }, "required": [ "restrictionType", "value" ] } } } } } }, "required": true }, "responses": { "201": { "description": "Voucher created successfully", "content": { "application/json": { "schema": { "description": "Voucher created successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number", "nullable": true }, "companyId": { "type": "number", "nullable": true }, "name": { "type": "string" }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "voucherType": { "type": "string", "enum": [ "DISCOUNT_CODE", "GIFT_CARD", "PROMOTION", "LOYALTY_REWARD", "CAMPAIGN", "REFERRAL" ] }, "balanceMode": { "type": "string", "enum": [ "NONE", "DECREMENTAL" ] }, "typeSpecification": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "balance", "free_item", "fixed_price", "formula" ] }, "amountInBasisPoints": { "type": "number", "description": "For percentage discounts (10000 = 100%)" }, "amountInCents": { "type": "number", "description": "For fixed amount discounts" }, "freeItemIds": { "type": "array", "items": { "type": "number" }, "description": "Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line." }, "freeItemQuantity": { "type": "number", "description": "Per-line cap for free items (defaults to 1)" }, "freeItemId": { "type": "number", "description": "DEPRECATED — use freeItemIds. Retained for legacy vouchers." }, "targetItemIds": { "type": "array", "items": { "type": "number" }, "description": "For fixed_price action: items repriced down to fixedPriceCents." }, "fixedPriceCents": { "type": "number", "description": "For fixed_price action: target per-unit base price in cents." }, "formula": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "buy_x_get_y", "tiered", "spend_threshold", "bundle", "combo_groups" ] }, "rules": { "type": "object", "description": "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." } } } }, "required": [ "type" ] }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "perUserUses": { "type": "number", "nullable": true }, "minOrderAmountCents": { "type": "number", "nullable": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "initialBalanceCents": { "type": "number", "nullable": true }, "remainingBalanceCents": { "type": "number", "nullable": true }, "canCombine": { "type": "boolean" }, "autoApply": { "type": "boolean" }, "validFrom": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time", "nullable": true }, "displayTitle": { "type": "string", "nullable": true }, "displayDescription": { "type": "string", "nullable": true }, "displayImageUrl": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "restrictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "discountId": { "type": "number" }, "restrictionType": { "type": "string", "enum": [ "INCLUDE_ITEM", "EXCLUDE_ITEM", "INCLUDE_TAG", "EXCLUDE_TAG", "INCLUDE_LAYOUT", "EXCLUDE_LAYOUT", "INCLUDE_VARIANT", "EXCLUDE_VARIANT", "REQUIRE_ITEM", "REQUIRE_ITEM_WITH_VARIANTS", "REQUIRE_TAG", "MIN_ITEM_COUNT" ] }, "entityId": { "type": "number" }, "quantity": { "type": "number", "nullable": true }, "variantIds": { "type": "array", "items": { "type": "number" }, "nullable": true, "description": "Required variant ids on the same line for REQUIRE_ITEM_WITH_VARIANTS rows." }, "createdAt": { "type": "string", "format": "date-time" } } } }, "userRestrictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "discountId": { "type": "number" }, "restrictionType": { "type": "string", "enum": [ "EMAIL", "PHONE", "USER_ID", "SEGMENT_ID" ] }, "value": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "409": { "description": "Conflict - Duplicate voucher code", "content": { "application/json": { "schema": { "description": "Conflict - Duplicate voucher code", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } } }, "/api/v1/vouchers/{id}": { "get": { "summary": "Get voucher", "tags": [ "Vouchers" ], "description": "Get single voucher with full details including restrictions and usage statistics\n\n**Permissions:** 🔵 `vouchers.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Voucher ID" } ], "responses": { "200": { "description": "Voucher details", "content": { "application/json": { "schema": { "description": "Voucher details", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number", "nullable": true }, "companyId": { "type": "number", "nullable": true }, "name": { "type": "string" }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "voucherType": { "type": "string", "enum": [ "DISCOUNT_CODE", "GIFT_CARD", "PROMOTION", "LOYALTY_REWARD", "CAMPAIGN", "REFERRAL" ] }, "balanceMode": { "type": "string", "enum": [ "NONE", "DECREMENTAL" ] }, "typeSpecification": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "balance", "free_item", "fixed_price", "formula" ] }, "amountInBasisPoints": { "type": "number", "description": "For percentage discounts (10000 = 100%)" }, "amountInCents": { "type": "number", "description": "For fixed amount discounts" }, "freeItemIds": { "type": "array", "items": { "type": "number" }, "description": "Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line." }, "freeItemQuantity": { "type": "number", "description": "Per-line cap for free items (defaults to 1)" }, "freeItemId": { "type": "number", "description": "DEPRECATED — use freeItemIds. Retained for legacy vouchers." }, "targetItemIds": { "type": "array", "items": { "type": "number" }, "description": "For fixed_price action: items repriced down to fixedPriceCents." }, "fixedPriceCents": { "type": "number", "description": "For fixed_price action: target per-unit base price in cents." }, "formula": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "buy_x_get_y", "tiered", "spend_threshold", "bundle", "combo_groups" ] }, "rules": { "type": "object", "description": "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." } } } }, "required": [ "type" ] }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "perUserUses": { "type": "number", "nullable": true }, "minOrderAmountCents": { "type": "number", "nullable": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "initialBalanceCents": { "type": "number", "nullable": true }, "remainingBalanceCents": { "type": "number", "nullable": true }, "canCombine": { "type": "boolean" }, "autoApply": { "type": "boolean" }, "validFrom": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time", "nullable": true }, "displayTitle": { "type": "string", "nullable": true }, "displayDescription": { "type": "string", "nullable": true }, "displayImageUrl": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "restrictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "discountId": { "type": "number" }, "restrictionType": { "type": "string", "enum": [ "INCLUDE_ITEM", "EXCLUDE_ITEM", "INCLUDE_TAG", "EXCLUDE_TAG", "INCLUDE_LAYOUT", "EXCLUDE_LAYOUT", "INCLUDE_VARIANT", "EXCLUDE_VARIANT", "REQUIRE_ITEM", "REQUIRE_ITEM_WITH_VARIANTS", "REQUIRE_TAG", "MIN_ITEM_COUNT" ] }, "entityId": { "type": "number" }, "quantity": { "type": "number", "nullable": true }, "variantIds": { "type": "array", "items": { "type": "number" }, "nullable": true, "description": "Required variant ids on the same line for REQUIRE_ITEM_WITH_VARIANTS rows." }, "createdAt": { "type": "string", "format": "date-time" } } } }, "userRestrictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "discountId": { "type": "number" }, "restrictionType": { "type": "string", "enum": [ "EMAIL", "PHONE", "USER_ID", "SEGMENT_ID" ] }, "value": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "usageStats": { "type": "object", "properties": { "totalUses": { "type": "number" }, "uniqueUsers": { "type": "number" }, "totalDiscountedCents": { "type": "number" }, "averageDiscountCents": { "type": "number" } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } }, "put": { "summary": "Update voucher", "tags": [ "Vouchers" ], "description": "Update an existing voucher\n\n**Permissions:** 🟠 `vouchers.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "voucherType": { "type": "string", "enum": [ "DISCOUNT_CODE", "GIFT_CARD", "PROMOTION", "LOYALTY_REWARD", "CAMPAIGN", "REFERRAL" ] }, "typeSpecification": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "balance", "free_item", "fixed_price", "formula" ] }, "amountInBasisPoints": { "type": "number", "description": "For percentage discounts (10000 = 100%)" }, "amountInCents": { "type": "number", "description": "For fixed amount discounts" }, "freeItemIds": { "type": "array", "items": { "type": "number" }, "description": "Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line." }, "freeItemQuantity": { "type": "number", "description": "Per-line cap for free items (defaults to 1)" }, "freeItemId": { "type": "number", "description": "DEPRECATED — use freeItemIds. Retained for legacy vouchers." }, "targetItemIds": { "type": "array", "items": { "type": "number" }, "description": "For fixed_price action: items repriced down to fixedPriceCents." }, "fixedPriceCents": { "type": "number", "description": "For fixed_price action: target per-unit base price in cents." }, "formula": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "buy_x_get_y", "tiered", "spend_threshold", "bundle", "combo_groups" ] }, "rules": { "type": "object", "description": "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." } } } }, "required": [ "type" ] }, "maxUses": { "type": "number" }, "perUserUses": { "type": "number" }, "minOrderAmountCents": { "type": "number" }, "maxDiscountAmountCents": { "type": "number" }, "canCombine": { "type": "boolean" }, "autoApply": { "type": "boolean" }, "displayTitle": { "type": "string" }, "displayDescription": { "type": "string" }, "displayImageUrl": { "type": "string" }, "alwaysVisible": { "type": "boolean" }, "isTemplate": { "type": "boolean" }, "templateVoucherId": { "type": "number" }, "initialBalanceCents": { "type": "number" }, "remainingBalanceCents": { "type": "number" }, "balanceMode": { "type": "string", "enum": [ "NONE", "DECREMENTAL" ] }, "validFrom": { "type": "string" }, "validUntil": { "type": "string" }, "restrictions": { "type": "array", "items": { "type": "object", "properties": { "restrictionType": { "type": "string", "enum": [ "INCLUDE_ITEM", "EXCLUDE_ITEM", "INCLUDE_TAG", "EXCLUDE_TAG", "INCLUDE_LAYOUT", "EXCLUDE_LAYOUT", "INCLUDE_VARIANT", "EXCLUDE_VARIANT", "REQUIRE_ITEM", "REQUIRE_ITEM_WITH_VARIANTS", "REQUIRE_TAG", "MIN_ITEM_COUNT" ] }, "entityId": { "type": "number" }, "quantity": { "type": "number", "description": "Required quantity for REQUIRE_ITEM / REQUIRE_ITEM_WITH_VARIANTS / MIN_ITEM_COUNT" }, "variantIds": { "type": "array", "items": { "type": "number" }, "description": "For REQUIRE_ITEM_WITH_VARIANTS: variant ids that must ALL be selected on the same cart line." } } } }, "userRestrictions": { "type": "array", "items": { "type": "object", "properties": { "restrictionType": { "type": "string", "enum": [ "EMAIL", "PHONE", "USER_ID", "SEGMENT_ID" ] }, "value": { "type": "string" } } } } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Voucher ID" } ], "responses": { "200": { "description": "Voucher updated successfully", "content": { "application/json": { "schema": { "description": "Voucher updated successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number", "nullable": true }, "companyId": { "type": "number", "nullable": true }, "name": { "type": "string" }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "voucherType": { "type": "string", "enum": [ "DISCOUNT_CODE", "GIFT_CARD", "PROMOTION", "LOYALTY_REWARD", "CAMPAIGN", "REFERRAL" ] }, "balanceMode": { "type": "string", "enum": [ "NONE", "DECREMENTAL" ] }, "typeSpecification": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "balance", "free_item", "fixed_price", "formula" ] }, "amountInBasisPoints": { "type": "number", "description": "For percentage discounts (10000 = 100%)" }, "amountInCents": { "type": "number", "description": "For fixed amount discounts" }, "freeItemIds": { "type": "array", "items": { "type": "number" }, "description": "Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line." }, "freeItemQuantity": { "type": "number", "description": "Per-line cap for free items (defaults to 1)" }, "freeItemId": { "type": "number", "description": "DEPRECATED — use freeItemIds. Retained for legacy vouchers." }, "targetItemIds": { "type": "array", "items": { "type": "number" }, "description": "For fixed_price action: items repriced down to fixedPriceCents." }, "fixedPriceCents": { "type": "number", "description": "For fixed_price action: target per-unit base price in cents." }, "formula": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "buy_x_get_y", "tiered", "spend_threshold", "bundle", "combo_groups" ] }, "rules": { "type": "object", "description": "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." } } } }, "required": [ "type" ] }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "perUserUses": { "type": "number", "nullable": true }, "minOrderAmountCents": { "type": "number", "nullable": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "initialBalanceCents": { "type": "number", "nullable": true }, "remainingBalanceCents": { "type": "number", "nullable": true }, "canCombine": { "type": "boolean" }, "autoApply": { "type": "boolean" }, "validFrom": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time", "nullable": true }, "displayTitle": { "type": "string", "nullable": true }, "displayDescription": { "type": "string", "nullable": true }, "displayImageUrl": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "restrictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "discountId": { "type": "number" }, "restrictionType": { "type": "string", "enum": [ "INCLUDE_ITEM", "EXCLUDE_ITEM", "INCLUDE_TAG", "EXCLUDE_TAG", "INCLUDE_LAYOUT", "EXCLUDE_LAYOUT", "INCLUDE_VARIANT", "EXCLUDE_VARIANT", "REQUIRE_ITEM", "REQUIRE_ITEM_WITH_VARIANTS", "REQUIRE_TAG", "MIN_ITEM_COUNT" ] }, "entityId": { "type": "number" }, "quantity": { "type": "number", "nullable": true }, "variantIds": { "type": "array", "items": { "type": "number" }, "nullable": true, "description": "Required variant ids on the same line for REQUIRE_ITEM_WITH_VARIANTS rows." }, "createdAt": { "type": "string", "format": "date-time" } } } }, "userRestrictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "discountId": { "type": "number" }, "restrictionType": { "type": "string", "enum": [ "EMAIL", "PHONE", "USER_ID", "SEGMENT_ID" ] }, "value": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } }, "delete": { "summary": "Delete voucher", "tags": [ "Vouchers" ], "description": "Soft delete (disable) a voucher\n\n**Permissions:** 🔴 `vouchers.delete`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Voucher ID" } ], "responses": { "200": { "description": "Voucher deleted successfully", "content": { "application/json": { "schema": { "description": "Voucher deleted successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "id": { "type": "number" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } } }, "/api/v1/vouchers/{id}/send-email": { "post": { "summary": "Send voucher email", "tags": [ "Vouchers" ], "description": "Send voucher code and QR code via email to a recipient\n\n**Permissions:** 🟠 `vouchers.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Recipient email address" }, "personal_message": { "type": "string", "description": "Optional personal message (for gift cards)" } } } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Voucher ID" } ], "responses": { "200": { "description": "Email sent successfully", "content": { "application/json": { "schema": { "description": "Email sent successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } } }, "/api/v1/vouchers/applied/{id}": { "delete": { "summary": "Remove applied voucher", "tags": [ "Vouchers" ], "description": "Remove an uncommitted applied voucher from a tab", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Applied voucher (tab_voucher) ID" } ], "responses": { "200": { "description": "Voucher removed successfully", "content": { "application/json": { "schema": { "description": "Voucher removed successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "id": { "type": "string" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } } }, "/api/v1/vouchers/apply": { "post": { "summary": "Apply voucher", "tags": [ "Vouchers" ], "description": "Apply a validated voucher to a tab", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "codes", "locationId" ], "properties": { "codes": { "type": "array", "items": { "type": "string" }, "description": "Voucher codes to apply" }, "locationId": { "type": "number", "description": "Location ID" }, "tabId": { "type": "string", "description": "Tab UUID" }, "kitchenDispatchId": { "type": "string", "description": "Kitchen dispatch UUID" }, "items": { "type": "array", "items": { "type": "object", "properties": { "inventoryItemId": { "type": "number" }, "quantity": { "type": "number" }, "priceCents": { "type": "number" }, "variantIds": { "type": "array", "items": { "type": "number" } }, "tagIds": { "type": "array", "items": { "type": "number" } } } }, "description": "Items to validate against" }, "userId": { "type": "number", "description": "User ID for tracking" }, "email": { "type": "string", "description": "Email for tracking" }, "phone": { "type": "string", "description": "Phone for tracking" } } } } }, "required": true }, "responses": { "200": { "description": "Voucher applied successfully", "content": { "application/json": { "schema": { "description": "Voucher applied successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "applied": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "success": { "type": "boolean" }, "reservationId": { "type": "string" }, "tabVoucherId": { "type": "number", "description": "tab_vouchers.id (only present for tab-scoped applies; pair with DELETE /vouchers/applied/:id to remove)" }, "voucherId": { "type": "number" }, "discountAmountCents": { "type": "number" } } } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "string" }, "message": { "type": "string" } } } }, "summary": { "type": "object", "properties": { "totalRequested": { "type": "number" }, "successCount": { "type": "number" }, "failureCount": { "type": "number" } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } }, "501": { "description": "Not Implemented - Feature under development", "content": { "application/json": { "schema": { "description": "Not Implemented - Feature under development", "type": "object" } } } } } } }, "/api/v1/vouchers/consume": { "post": { "summary": "Consume vouchers", "tags": [ "Vouchers" ], "description": "Consume (commit) previously reserved voucher reservations", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reservationIds": { "type": "array", "items": { "type": "string" }, "description": "Reservation IDs to consume" }, "tabId": { "type": "string", "description": "Tab UUID" } } } } } }, "responses": { "200": { "description": "Vouchers consumed successfully", "content": { "application/json": { "schema": { "description": "Vouchers consumed successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } } }, "/api/v1/vouchers/eligible": { "post": { "summary": "Get eligible vouchers", "tags": [ "Vouchers" ], "description": "Get vouchers eligible for a location/tab. Returns promotions and user-restricted vouchers.\n\n**Permissions:** 🔵 `vouchers.read`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "locationId" ], "properties": { "locationId": { "type": "number", "description": "Location ID (required)" }, "tabId": { "type": "string", "description": "Tab UUID - will fetch user IDs from tab members" }, "userIds": { "type": "array", "items": { "type": "number" }, "description": "Direct user IDs to check for user-restricted vouchers" }, "items": { "type": "array", "description": "Cart items. When provided, vouchers are filtered against item/tag/variant/layout restrictions, required items, and minimum order amount — only vouchers that would pass at reservation time are returned.", "items": { "type": "object", "required": [ "item_id", "quantity", "price_cents" ], "properties": { "item_id": { "type": "number", "description": "Inventory item ID" }, "quantity": { "type": "number", "description": "Quantity" }, "price_cents": { "type": "number", "description": "Total price per unit in cents (including modifiers/variants)" }, "base_price_cents": { "type": "number", "description": "Base price per unit in cents (excluding modifiers/variants). Used for bundle deals." }, "tags": { "type": "array", "items": { "type": "number" }, "description": "Tag IDs" }, "variant_ids": { "type": "array", "items": { "type": "number" }, "description": "Variant IDs applied to this line (for variant-based restrictions)" }, "layout_id": { "type": "number", "description": "Layout ID this item was added from" } } } }, "totalAmountCents": { "type": "number", "description": "Total order amount in cents. Used for min order validation when items array is empty (e.g. tab-level checks)." }, "layoutId": { "type": "string", "description": "Current browsing layout UUID. Used for INCLUDE_LAYOUT/EXCLUDE_LAYOUT restriction filtering at SQL level." } } } } }, "required": true }, "responses": { "200": { "description": "List of eligible vouchers", "content": { "application/json": { "schema": { "description": "List of eligible vouchers", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "code": { "type": "string" }, "name": { "type": "string" }, "voucherType": { "type": "string", "enum": [ "DISCOUNT_CODE", "GIFT_CARD", "PROMOTION", "LOYALTY_REWARD", "CAMPAIGN", "REFERRAL" ] }, "isPromotion": { "type": "boolean", "description": "True if voucher_type = PROMOTION" }, "isUserVoucher": { "type": "boolean", "description": "True if voucher has USER_ID restriction matching provided users" }, "isLoyaltyRestricted": { "type": "boolean", "description": "True if voucher has a discount_loyalty_restrictions row (tier or enrollment required)" }, "alwaysVisible": { "type": "boolean", "description": "Show even when requirements not met" }, "autoApply": { "type": "boolean", "description": "Apply automatically when conditions are met (vs. requiring manual selection)" }, "typeSpecification": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "balance", "free_item", "fixed_price", "formula" ] }, "amountInBasisPoints": { "type": "number", "description": "For percentage discounts (10000 = 100%)" }, "amountInCents": { "type": "number", "description": "For fixed amount discounts" }, "freeItemIds": { "type": "array", "items": { "type": "number" }, "description": "Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line." }, "freeItemQuantity": { "type": "number", "description": "Per-line cap for free items (defaults to 1)" }, "freeItemId": { "type": "number", "description": "DEPRECATED — use freeItemIds. Retained for legacy vouchers." }, "targetItemIds": { "type": "array", "items": { "type": "number" }, "description": "For fixed_price action: items repriced down to fixedPriceCents." }, "fixedPriceCents": { "type": "number", "description": "For fixed_price action: target per-unit base price in cents." }, "formula": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "buy_x_get_y", "tiered", "spend_threshold", "bundle", "combo_groups" ] }, "rules": { "type": "object", "description": "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." } } } }, "required": [ "type" ], "nullable": true }, "displayTitle": { "type": "string", "nullable": true }, "displayDescription": { "type": "string", "nullable": true }, "displayImageUrl": { "type": "string", "nullable": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "remainingBalanceCents": { "type": "number", "nullable": true }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "hasUsesLeft": { "type": "boolean", "description": "True if maxUses is null OR timesUsed < maxUses" }, "restrictions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "INCLUDE_ITEM", "EXCLUDE_ITEM", "INCLUDE_TAG", "EXCLUDE_TAG", "INCLUDE_LAYOUT", "EXCLUDE_LAYOUT", "INCLUDE_VARIANT", "EXCLUDE_VARIANT", "REQUIRE_ITEM", "REQUIRE_ITEM_WITH_VARIANTS", "REQUIRE_TAG", "MIN_ITEM_COUNT" ], "description": "Restriction kind. INCLUDE/EXCLUDE_ITEM gates which items receive the discount; REQUIRE_ITEM/REQUIRE_TAG gates whether the voucher applies at all; INCLUDE/EXCLUDE_LAYOUT scopes by POS layout." }, "entityId": { "type": "string", "description": "Numeric id (as string) for ITEM/TAG types, UUID for LAYOUT types." }, "quantity": { "type": "number", "nullable": true, "description": "Required quantity for REQUIRE_ITEM / REQUIRE_TAG. Null for INCLUDE/EXCLUDE rules." } } }, "description": "Item/tag/layout restrictions for this voucher. Frontend resolves entity ids → titles via the inventory cache to surface \"what to buy to unlock this promo\" without a follow-up call." } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } } }, "/api/v1/vouchers/release": { "post": { "summary": "Release vouchers", "tags": [ "Vouchers" ], "description": "Release (cancel) previously reserved voucher reservations", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reservationIds": { "type": "array", "items": { "type": "string" }, "description": "Reservation IDs to release" }, "tabId": { "type": "string", "description": "Tab UUID" } } } } } }, "responses": { "200": { "description": "Vouchers released successfully", "content": { "application/json": { "schema": { "description": "Vouchers released successfully", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } } }, "/api/v1/vouchers/reservations": { "get": { "summary": "Get voucher reservations", "tags": [ "Vouchers" ], "description": "Get active voucher reservations for a tab or kitchen dispatch", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "tabId", "required": false, "description": "Tab UUID" }, { "schema": { "type": "string" }, "in": "query", "name": "kitchenDispatchId", "required": false, "description": "Kitchen dispatch UUID" } ], "responses": { "200": { "description": "List of reservations", "content": { "application/json": { "schema": { "description": "List of reservations", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "reservations": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } } }, "/api/v1/vouchers/search": { "get": { "summary": "Search vouchers", "tags": [ "Vouchers" ], "description": "Search vouchers by code or name for POS lookup", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "q", "required": true, "description": "Search query (code or name)" }, { "schema": { "type": "number" }, "in": "query", "name": "location_id", "required": false, "description": "Filter by location ID" }, { "schema": { "type": "number", "default": 10, "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "Max results to return" } ], "responses": { "200": { "description": "Matching vouchers", "content": { "application/json": { "schema": { "description": "Matching vouchers", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number", "nullable": true }, "companyId": { "type": "number", "nullable": true }, "name": { "type": "string" }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "voucherType": { "type": "string", "enum": [ "DISCOUNT_CODE", "GIFT_CARD", "PROMOTION", "LOYALTY_REWARD", "CAMPAIGN", "REFERRAL" ] }, "balanceMode": { "type": "string", "enum": [ "NONE", "DECREMENTAL" ] }, "typeSpecification": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "balance", "free_item", "fixed_price", "formula" ] }, "amountInBasisPoints": { "type": "number", "description": "For percentage discounts (10000 = 100%)" }, "amountInCents": { "type": "number", "description": "For fixed amount discounts" }, "freeItemIds": { "type": "array", "items": { "type": "number" }, "description": "Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line." }, "freeItemQuantity": { "type": "number", "description": "Per-line cap for free items (defaults to 1)" }, "freeItemId": { "type": "number", "description": "DEPRECATED — use freeItemIds. Retained for legacy vouchers." }, "targetItemIds": { "type": "array", "items": { "type": "number" }, "description": "For fixed_price action: items repriced down to fixedPriceCents." }, "fixedPriceCents": { "type": "number", "description": "For fixed_price action: target per-unit base price in cents." }, "formula": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "buy_x_get_y", "tiered", "spend_threshold", "bundle", "combo_groups" ] }, "rules": { "type": "object", "description": "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." } } } }, "required": [ "type" ] }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "perUserUses": { "type": "number", "nullable": true }, "minOrderAmountCents": { "type": "number", "nullable": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "initialBalanceCents": { "type": "number", "nullable": true }, "remainingBalanceCents": { "type": "number", "nullable": true }, "canCombine": { "type": "boolean" }, "autoApply": { "type": "boolean" }, "validFrom": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time", "nullable": true }, "displayTitle": { "type": "string", "nullable": true }, "displayDescription": { "type": "string", "nullable": true }, "displayImageUrl": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } } }, "/api/v1/vouchers/validate": { "post": { "summary": "Validate voucher(s)", "tags": [ "Vouchers" ], "description": "Validate one or more voucher codes against a tab or specific kitchen dispatch items.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "codes", "locationId" ], "properties": { "codes": { "type": "array", "description": "Array of voucher codes to validate", "items": { "type": "string" } }, "locationId": { "type": "number", "description": "Location ID" }, "includePromotions": { "type": "boolean", "description": "Include auto-apply promotions for this location" }, "context": { "type": "object", "description": "Validation context", "properties": { "tabId": { "type": "string", "description": "Tab UUID" }, "kitchenDispatchItems": { "type": "array", "description": "Kitchen dispatch item UUIDs for split payments", "items": { "type": "string" } }, "totalAmountCents": { "type": "number", "description": "Total amount in cents for discount calculation" }, "items": { "type": "array", "description": "Uncommitted items to validate against", "items": { "type": "object", "required": [ "inventoryItemId", "quantity", "priceCents" ], "properties": { "inventoryItemId": { "type": "number", "description": "Inventory item ID" }, "quantity": { "type": "number", "description": "Item quantity" }, "priceCents": { "type": "number", "description": "Item price in cents" }, "variantIds": { "type": "array", "items": { "type": "number" }, "description": "Variant IDs" }, "tagIds": { "type": "array", "items": { "type": "number" }, "description": "Tag IDs" } } } } } } } } } }, "required": true }, "responses": { "200": { "description": "Validation results for all voucher codes", "content": { "application/json": { "schema": { "description": "Validation results for all voucher codes", "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "validations": { "type": "array", "description": "Validation results for each voucher code (in order)", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The voucher code" }, "valid": { "type": "boolean", "description": "Whether this voucher is valid" }, "error": { "type": "string", "nullable": true, "description": "Error code if invalid (NOT_FOUND, INTERNAL_ERROR, etc.)" }, "message": { "type": "string", "nullable": true, "description": "Human-readable error/status message" }, "voucher": { "type": "object", "properties": { "id": { "type": "number" }, "locationId": { "type": "number", "nullable": true }, "companyId": { "type": "number", "nullable": true }, "name": { "type": "string" }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "voucherType": { "type": "string", "enum": [ "DISCOUNT_CODE", "GIFT_CARD", "PROMOTION", "LOYALTY_REWARD", "CAMPAIGN", "REFERRAL" ] }, "balanceMode": { "type": "string", "enum": [ "NONE", "DECREMENTAL" ] }, "typeSpecification": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed", "balance", "free_item", "fixed_price", "formula" ] }, "amountInBasisPoints": { "type": "number", "description": "For percentage discounts (10000 = 100%)" }, "amountInCents": { "type": "number", "description": "For fixed amount discounts" }, "freeItemIds": { "type": "array", "items": { "type": "number" }, "description": "Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line." }, "freeItemQuantity": { "type": "number", "description": "Per-line cap for free items (defaults to 1)" }, "freeItemId": { "type": "number", "description": "DEPRECATED — use freeItemIds. Retained for legacy vouchers." }, "targetItemIds": { "type": "array", "items": { "type": "number" }, "description": "For fixed_price action: items repriced down to fixedPriceCents." }, "fixedPriceCents": { "type": "number", "description": "For fixed_price action: target per-unit base price in cents." }, "formula": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "buy_x_get_y", "tiered", "spend_threshold", "bundle", "combo_groups" ] }, "rules": { "type": "object", "description": "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." } } } }, "required": [ "type" ] }, "maxUses": { "type": "number", "nullable": true }, "timesUsed": { "type": "number" }, "perUserUses": { "type": "number", "nullable": true }, "minOrderAmountCents": { "type": "number", "nullable": true }, "maxDiscountAmountCents": { "type": "number", "nullable": true }, "initialBalanceCents": { "type": "number", "nullable": true }, "remainingBalanceCents": { "type": "number", "nullable": true }, "canCombine": { "type": "boolean" }, "autoApply": { "type": "boolean" }, "validFrom": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time", "nullable": true }, "displayTitle": { "type": "string", "nullable": true }, "displayDescription": { "type": "string", "nullable": true }, "displayImageUrl": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "nullable": true, "description": "Voucher details (if found)" }, "discount": { "type": "object", "nullable": true, "description": "Discount calculation details", "properties": { "estimatedDiscountCents": { "type": "number", "description": "Estimated discount in cents" }, "discountType": { "type": "string", "description": "Type of discount (percentage, fixed, free_item, etc.)" } } }, "newTotalCents": { "type": "number", "nullable": true, "description": "New running total after this voucher (for sequential validation)" }, "orderIndex": { "type": "number", "description": "Index position in the validation order (0-indexed)" } } } } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input", "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid API key", "type": "object" } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions", "type": "object" } } } }, "404": { "description": "Not Found - Resource not found", "content": { "application/json": { "schema": { "description": "Not Found - Resource not found", "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "type": "object" } } } } } } }, "/api/v1/webhooks/logs": { "get": { "summary": "List webhook logs", "tags": [ "Webhooks" ], "description": "List webhook delivery logs with optional filtering", "parameters": [ { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" }, { "schema": { "type": "string" }, "in": "query", "name": "subscriptionId", "required": false, "description": "Filter by subscription ID" }, { "schema": { "type": "string" }, "in": "query", "name": "event", "required": false, "description": "Filter by event type" }, { "schema": { "type": "string", "enum": [ "pending", "success", "failed", "retrying" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by delivery status" }, { "schema": { "type": "string" }, "in": "query", "name": "resourceId", "required": false, "description": "Filter by resource ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique log ID" }, "subscriptionId": { "type": "string", "description": "Subscription ID" }, "event": { "type": "string", "description": "Event type that triggered webhook" }, "resourceId": { "type": "string", "description": "ID of the resource that changed" }, "status": { "type": "string", "enum": [ "pending", "success", "failed", "retrying" ], "description": "Delivery status" }, "attempts": { "type": "number", "description": "Number of delivery attempts" }, "responseCode": { "type": "number", "nullable": true, "description": "HTTP response code from webhook endpoint" }, "errorMessage": { "type": "string", "nullable": true, "description": "Error message if delivery failed" }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Successful delivery timestamp" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "id", "subscriptionId", "event", "resourceId", "status", "attempts", "createdAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "logs", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/webhooks/subscriptions": { "get": { "summary": "List webhook subscriptions", "tags": [ "Webhooks" ], "description": "List webhook subscriptions with optional filtering\n\n**Permissions:** 🔵 `webhooks.read`", "parameters": [ { "schema": { "type": "number", "minimum": 1, "default": 1 }, "in": "query", "name": "page", "required": false, "description": "Page number" }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false, "description": "Items per page" }, { "schema": { "type": "boolean" }, "in": "query", "name": "active", "required": false, "description": "Filter by active status" }, { "schema": { "type": "string" }, "in": "query", "name": "event", "required": false, "description": "Filter by event type" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique subscription ID" }, "url": { "type": "string", "format": "uri", "description": "Webhook URL endpoint" }, "events": { "type": "array", "items": { "type": "string" }, "description": "List of event types to subscribe to (e.g., \"inventory.created\", \"order.completed\")" }, "secret": { "type": "string", "description": "Webhook secret for signature verification" }, "active": { "type": "boolean", "description": "Whether subscription is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "url", "events", "active", "createdAt", "updatedAt" ] } }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "total": { "type": "number", "minimum": 0 }, "totalPages": { "type": "number", "minimum": 0 } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "subscriptions", "pagination" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "post": { "summary": "Create webhook subscription", "tags": [ "Webhooks" ], "description": "Create a new webhook subscription\n\n**Permissions:** 🟢 `webhooks.create`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Webhook URL (must be HTTPS)" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "List of event types to subscribe to" }, "secret": { "type": "string", "minLength": 16, "description": "Webhook secret for signature verification (min 16 characters)" }, "active": { "type": "boolean", "default": true, "description": "Whether subscription is active" } }, "required": [ "url", "events", "secret" ] } } }, "required": true }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique subscription ID" }, "url": { "type": "string", "format": "uri", "description": "Webhook URL endpoint" }, "events": { "type": "array", "items": { "type": "string" }, "description": "List of event types to subscribe to (e.g., \"inventory.created\", \"order.completed\")" }, "secret": { "type": "string", "description": "Webhook secret for signature verification" }, "active": { "type": "boolean", "description": "Whether subscription is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "url", "events", "active", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/webhooks/subscriptions/{id}": { "get": { "summary": "Get webhook subscription", "tags": [ "Webhooks" ], "description": "Get a single webhook subscription by ID\n\n**Permissions:** 🔵 `webhooks.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook subscription ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique subscription ID" }, "url": { "type": "string", "format": "uri", "description": "Webhook URL endpoint" }, "events": { "type": "array", "items": { "type": "string" }, "description": "List of event types to subscribe to (e.g., \"inventory.created\", \"order.completed\")" }, "secret": { "type": "string", "description": "Webhook secret for signature verification" }, "active": { "type": "boolean", "description": "Whether subscription is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "url", "events", "active", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "put": { "summary": "Update webhook subscription", "tags": [ "Webhooks" ], "description": "Update an existing webhook subscription\n\n**Permissions:** 🟠 `webhooks.update`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "secret": { "type": "string", "minLength": 16 }, "active": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook subscription ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique subscription ID" }, "url": { "type": "string", "format": "uri", "description": "Webhook URL endpoint" }, "events": { "type": "array", "items": { "type": "string" }, "description": "List of event types to subscribe to (e.g., \"inventory.created\", \"order.completed\")" }, "secret": { "type": "string", "description": "Webhook secret for signature verification" }, "active": { "type": "boolean", "description": "Whether subscription is active" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "url", "events", "active", "createdAt", "updatedAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } }, "delete": { "summary": "Delete webhook subscription", "tags": [ "Webhooks" ], "description": "Delete a webhook subscription\n\n**Permissions:** 🔴 `webhooks.delete`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook subscription ID" } ], "responses": { "200": { "description": "Subscription successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } } } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } }, "/api/v1/webhooks/subscriptions/{id}/stats": { "get": { "summary": "Get webhook subscription stats", "tags": [ "Webhooks" ], "description": "Get delivery statistics for a webhook subscription\n\n**Permissions:** 🔵 `webhooks.read`", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook subscription ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "totalDeliveries": { "type": "number", "description": "Total number of deliveries" }, "successCount": { "type": "number", "description": "Number of successful deliveries" }, "failedCount": { "type": "number", "description": "Number of failed deliveries" }, "retryingCount": { "type": "number", "description": "Number of deliveries currently retrying" }, "successRate": { "type": "number", "description": "Success rate percentage" }, "dailyStats": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Date (YYYY-MM-DD)" }, "success": { "type": "number", "description": "Successful deliveries on this date" }, "failed": { "type": "number", "description": "Failed deliveries on this date" } }, "required": [ "date", "success", "failed" ] }, "description": "Daily delivery stats for the last 30 days" }, "lastDeliveredAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Last successful delivery timestamp" } }, "required": [ "totalDeliveries", "successCount", "failedCount", "retryingCount", "successRate", "dailyStats", "lastDeliveredAt" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_INPUT", "message": "Invalid request parameters" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 5 } } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INVALID_API_KEY", "message": "Invalid API key provided" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 3 } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You do not have permission to access this resource" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 4 } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested resource was not found" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 2 } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Please try again later." }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 1 } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "executionTimeMs": { "type": "number" } }, "required": [ "requestId", "timestamp", "executionTimeMs" ] } }, "required": [ "status", "error", "meta" ] }, "example": { "status": "error", "error": { "code": "INTERNAL_SERVER_ERROR", "message": "An unexpected error occurred" }, "meta": { "requestId": "req_123456", "timestamp": "2025-01-15T10:30:00.000Z", "executionTimeMs": 10 } } } } } } } } }, "servers": [ { "url": "https://common-api.karma.life", "description": "Production" }, { "url": "https://common-api.beta.karma.life", "description": "Beta" }, { "url": "https://common-api.development.karma.life", "description": "Development" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Alerts", "description": "System notifications and warnings" }, { "name": "Analytics", "description": "Enterprise real-time analytics with BigQuery" }, { "name": "Automations", "description": "Drip campaign automations with visual flow editor" }, { "name": "Bookings", "description": "Table reservations and booking management" }, { "name": "Bookings - Optimization", "description": "AI-powered booking table optimization" }, { "name": "Bookings - Settings", "description": "Location booking settings and configuration" }, { "name": "Bookings - Users", "description": "Guest user search and creation for bookings" }, { "name": "Bookings - Waitlist", "description": "Booking waitlist management" }, { "name": "Capacity Settings", "description": "Time slot capacity configuration and limits" }, { "name": "Channels", "description": "Sales channels (dine-in, takeaway, delivery)" }, { "name": "Coursings", "description": "Multi-course meal sequencing" }, { "name": "Custom Tags", "description": "Labels and categorization" }, { "name": "Customers", "description": "Location-scoped guest user records, overrides, and editing" }, { "name": "CWI", "description": "Company-Wide Items (CWI) management via EAN" }, { "name": "Data Streaming", "description": "Real-time data streaming and sync" }, { "name": "Extended Waiting Time", "description": "Extended waiting times during busy periods" }, { "name": "Inventory", "description": "Menu items, products, and modifiers" }, { "name": "Invoices", "description": "Invoice management, recipients, and location settings" }, { "name": "Location Maps", "description": "Floor plans and seating layouts" }, { "name": "Locations", "description": "Location management and creation" }, { "name": "Loyalty Programs", "description": "Customer loyalty programs, points, tiers, and rewards" }, { "name": "Menu Layouts", "description": "Menu structure and organization" }, { "name": "Notes", "description": "Notes attached to tabs and orders" }, { "name": "Orders", "description": "Customer orders and order management" }, { "name": "Payment Methods", "description": "User payment methods management" }, { "name": "Permissions", "description": "Permission registry and management" }, { "name": "Print Templates", "description": "Print template management for receipts and tickets" }, { "name": "Printers", "description": "Receipt and ticket printer management with CloudPRNT URLs" }, { "name": "Public", "description": "Simplified endpoints for external integrations — place orders without complex setup" }, { "name": "Purchases", "description": "Purchase history and transaction details" }, { "name": "Reporting", "description": "Purchase summary reports and financial reporting" }, { "name": "Retailer Users", "description": "Retailer user management and invitations" }, { "name": "Reviews", "description": "Customer reviews and feedback for purchases" }, { "name": "Roles", "description": "Role management with permission assignment" }, { "name": "Schedules", "description": "Operating hours and special schedules" }, { "name": "Settlements", "description": "Tab settlements and payment groupings" }, { "name": "Statistics", "description": "Sales statistics, time series, and aggregated data" }, { "name": "Table Groups", "description": "Table grouping and floor plans" }, { "name": "Tables", "description": "Restaurant table management" }, { "name": "Tabs", "description": "Customer tabs and running bills" }, { "name": "Terminals", "description": "Payment terminal management" }, { "name": "Time Slots", "description": "Available time slots for orders and bookings" }, { "name": "Translations", "description": "Multi-language translations for inventory and menus" }, { "name": "Users", "description": "End user management and lookup" }, { "name": "Variant Groups", "description": "Product options and modifiers" }, { "name": "Vouchers", "description": "Discount vouchers and promotions" }, { "name": "Webhooks", "description": "Webhook subscriptions and event notifications" } ] }