{ "openapi": "3.1.0", "info": { "title": "Alayn AI Hospitality & Restaurant API", "version": "1.0.0", "description": "Enterprise REST API for Alayn AI restaurant operating system, point of sale (POS), kitchen display systems (KDS), smart FEFO inventory, and workforce scheduling.", "contact": { "name": "Alayn AI Developer Platform", "email": "info@alaynai.com", "url": "https://alaynai.com/api-docs" }, "license": { "name": "Proprietary", "url": "https://alaynai.com/legal/terms" }, "x-cli": { "package": "@alayn/cli", "registry": "https://www.npmjs.com/package/@alayn/cli", "command": "alayn", "install": "npm install -g @alayn/cli", "docs": "https://alaynai.com/api-docs#cli", "repository": "https://github.com/Akshi1277/alayn" }, "x-deprecation-policy": { "sunsetWindowMonths": 12, "headerConventions": [ "Deprecation", "Sunset", "Link" ], "policyUrl": "https://alaynai.com/api-docs#deprecation-policy" }, "x-sunset-policy": { "noticePeriod": "12 months", "documentation": "https://alaynai.com/api-docs#deprecation-policy" } }, "servers": [ { "url": "https://api.alaynai.com/v1", "description": "Production API Server (v1)" } ], "tags": [ { "name": "Orders", "description": "Counter, table dining, QR self-order, and KDS ticket dispatch" }, { "name": "Inventory", "description": "FEFO/FIFO batch tracking, recipe ingredient deductions, and supplier POs" }, { "name": "Workforce", "description": "Employee matrix rosters, shifts, and tablet clock-in terminal" }, { "name": "Analytics", "description": "Real-time revenue, P&L, and food waste telemetry" } ], "paths": { "/orders": { "get": { "operationId": "listOrders", "summary": "List active and historical restaurant orders", "description": "Retrieve a paginated list of dining, counter, and delivery orders for the specified outlet with live status filtering.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/OutletIdHeader" }, { "name": "status", "in": "query", "required": false, "description": "Filter orders by operational status", "schema": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "IN_PREPARATION", "READY", "DELIVERED", "COMPLETED", "CANCELLED" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number (1-indexed)", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of records per page", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Successful retrieval of orders list", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" } } } }, "400": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error (RFC 9457)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "deprecated": false }, "post": { "operationId": "createOrder", "summary": "Submit a new dining or counter order", "description": "Create an order, deduct initial recipe stock batches, and dispatch live Kitchen Order Tickets (KOT) to assigned prep stations.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/OutletIdHeader" } ], "requestBody": { "required": true, "description": "Order creation payload including table number, items, and billing details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "201": { "description": "Order successfully created and dispatched to KDS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error (RFC 9457)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "deprecated": false } }, "/orders/{orderId}": { "get": { "operationId": "getOrderById", "summary": "Get specific order details by ID", "description": "Retrieve comprehensive details for an order including items, modifiers, status history, and payment ledger.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/OutletIdHeader" }, { "name": "orderId", "in": "path", "required": true, "description": "Unique identifier of the order", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Order details successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error (RFC 9457)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "deprecated": false } }, "/inventory/items": { "get": { "operationId": "listInventoryItems", "summary": "Query inventory stock levels and FEFO batches", "description": "Fetch real-time stock balances, unit measurements, minimum safety thresholds, and active manufacturing/expiry batches.", "tags": [ "Inventory" ], "parameters": [ { "$ref": "#/components/parameters/OutletIdHeader" }, { "name": "lowStockOnly", "in": "query", "required": false, "description": "Filter items currently at or below minimum safety threshold", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Inventory items and batch stock successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryItemListResponse" } } } }, "400": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error (RFC 9457)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "deprecated": false } }, "/inventory/purchase-orders": { "post": { "operationId": "createPurchaseOrder", "summary": "Generate and dispatch a supplier purchase order", "description": "Create an automated or manual PO to restock depleted raw ingredients with supplier lead time tracking.", "tags": [ "Inventory" ], "parameters": [ { "$ref": "#/components/parameters/OutletIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePurchaseOrderRequest" } } } }, "responses": { "201": { "description": "Purchase order created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOrderResponse" } } } }, "400": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error (RFC 9457)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "deprecated": false } }, "/workforce/roster": { "get": { "operationId": "getWorkforceRoster", "summary": "Retrieve employee shift matrix roster", "description": "Fetch scheduled shifts mapped by employee and date grid for the specified outlet.", "tags": [ "Workforce" ], "parameters": [ { "$ref": "#/components/parameters/OutletIdHeader" }, { "name": "startDate", "in": "query", "required": true, "description": "Start date for roster query (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "required": true, "description": "End date for roster query (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Roster matrix returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RosterMatrixResponse" } } } }, "400": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error (RFC 9457)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "deprecated": false } }, "/workforce/attendance": { "post": { "operationId": "recordAttendanceClockIn", "summary": "Record employee PIN attendance clock-in or clock-out", "description": "Log attendance from tablet terminal kiosks (/attendance-terminal) with PIN authentication and timestamp verification.", "tags": [ "Workforce" ], "parameters": [ { "$ref": "#/components/parameters/OutletIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceClockRequest" } } } }, "responses": { "201": { "description": "Attendance event recorded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceResponse" } } } }, "400": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error (RFC 9457)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "deprecated": false } }, "/analytics/summary": { "get": { "operationId": "getAnalyticsSummary", "summary": "Retrieve live revenue, P&L, and food cost telemetry", "description": "Fetch consolidated outlet performance metrics including gross sales, COGS, labor cost percentage, and table turnover velocity.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/OutletIdHeader" }, { "name": "period", "in": "query", "required": false, "description": "Time range for analytics calculation", "schema": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "THIS_WEEK", "THIS_MONTH", "LAST_MONTH" ], "default": "TODAY" } } ], "responses": { "200": { "description": "Analytics summary metrics returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsSummaryResponse" } } } }, "400": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate Limit Exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "RFC 9457 Problem Details Error Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error (RFC 9457)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "deprecated": false } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Authenticate requests using standard JWT Bearer token." } }, "headers": { "RateLimit-Limit": { "schema": { "type": "integer", "example": 100 }, "description": "The maximum number of requests allowed in the current time window." }, "RateLimit-Remaining": { "schema": { "type": "integer", "example": 99 }, "description": "The number of remaining requests in the current time window." }, "RateLimit-Reset": { "schema": { "type": "integer", "example": 60 }, "description": "The number of seconds remaining until the rate limit window resets." } }, "parameters": { "OutletIdHeader": { "name": "x-outlet-id", "in": "header", "required": true, "description": "Unique UUID scoping the request to a specific restaurant outlet/branch.", "schema": { "type": "string", "format": "uuid", "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" } } }, "responses": { "BadRequestError": { "description": "Invalid input parameters (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnauthorizedError": { "description": "Missing or invalid authentication credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ForbiddenError": { "description": "Authenticated user lacks permission for this outlet or resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundError": { "description": "The requested resource was not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Payload failed schema validation (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "RateLimitError": { "description": "Rate limit exceeded. Client must self-throttle.", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 }, "description": "Seconds to wait before retrying request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "An unexpected server error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "description": "Standard RFC 9457 Problem Details for HTTP APIs", "required": [ "type", "title", "status", "detail", "code" ], "properties": { "type": { "type": "string", "format": "uri", "example": "https://alaynai.com/errors/invalid-request" }, "title": { "type": "string", "example": "Invalid Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "The request body failed validation." }, "instance": { "type": "string", "example": "/orders" }, "code": { "type": "string", "example": "ERR_INVALID_OUTLET_SCOPE" } } }, "ValidationErrorResponse": { "type": "object", "description": "Standard RFC 9457 Validation Problem Details", "required": [ "type", "title", "status", "detail", "code", "invalidParams" ], "properties": { "type": { "type": "string", "example": "https://alaynai.com/errors/validation" }, "title": { "type": "string", "example": "Validation Failed" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "One or more fields in the request body are invalid." }, "code": { "type": "string", "example": "ERR_PAYLOAD_VALIDATION" }, "invalidParams": { "type": "array", "items": { "type": "object", "required": [ "name", "reason" ], "properties": { "name": { "type": "string", "example": "items[0].quantity" }, "reason": { "type": "string", "example": "Quantity must be greater than zero." } } } } } }, "CreateOrderRequest": { "type": "object", "required": [ "orderType", "items" ], "properties": { "tableNumber": { "type": "string", "example": "T-14" }, "orderType": { "type": "string", "enum": [ "DINE_IN", "TAKEAWAY", "DELIVERY", "COUNTER" ], "example": "DINE_IN" }, "customerName": { "type": "string", "example": "Akshat" }, "customerPhone": { "type": "string", "example": "+919876543210" }, "notes": { "type": "string", "example": "Extra spicy, dressing on the side" }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "menuItemId", "quantity", "unitPriceCents" ], "properties": { "menuItemId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Artisan Cappuccino" }, "quantity": { "type": "integer", "minimum": 1, "example": 2 }, "unitPriceCents": { "type": "integer", "description": "Price in sub-unit cents/paise", "example": 24000 }, "modifiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Oat Milk" }, "priceCents": { "type": "integer", "example": 4000 } } } } } } } } }, "OrderResponse": { "type": "object", "required": [ "id", "orderNumber", "status", "orderType", "totalAmountCents", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "outletId": { "type": "string", "format": "uuid" }, "orderNumber": { "type": "string", "example": "ORD-1082" }, "tableNumber": { "type": "string", "example": "T-14" }, "orderType": { "type": "string", "example": "DINE_IN" }, "status": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "IN_PREPARATION", "READY", "DELIVERED", "COMPLETED", "CANCELLED" ] }, "subtotalCents": { "type": "integer", "example": 48000 }, "taxCents": { "type": "integer", "example": 2400 }, "totalAmountCents": { "type": "integer", "example": 50400 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OrderListResponse": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderResponse" } }, "pagination": { "type": "object", "required": [ "total", "page", "limit", "totalPages" ], "properties": { "total": { "type": "integer", "example": 128 }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "totalPages": { "type": "integer", "example": 7 } } } } }, "InventoryItem": { "type": "object", "required": [ "id", "name", "category", "unit", "currentStock", "minStockThreshold" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Organic Whole Milk" }, "category": { "type": "string", "example": "Dairy" }, "unit": { "type": "string", "example": "L" }, "currentStock": { "type": "number", "example": 14.5 }, "minStockThreshold": { "type": "number", "example": 20.0 }, "isLowStock": { "type": "boolean", "example": true }, "activeBatches": { "type": "array", "items": { "type": "object", "properties": { "batchNumber": { "type": "string", "example": "B-202608-01" }, "quantity": { "type": "number", "example": 14.5 }, "expiryDate": { "type": "string", "format": "date", "example": "2026-09-02" } } } } } }, "InventoryItemListResponse": { "type": "object", "required": [ "items", "totalCount", "lowStockCount" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryItem" } }, "totalCount": { "type": "integer", "example": 84 }, "lowStockCount": { "type": "integer", "example": 3 } } }, "CreatePurchaseOrderRequest": { "type": "object", "required": [ "supplierId", "items" ], "properties": { "supplierId": { "type": "string", "format": "uuid" }, "expectedDeliveryDate": { "type": "string", "format": "date", "example": "2026-08-31" }, "items": { "type": "array", "items": { "type": "object", "required": [ "inventoryItemId", "quantityOrdered" ], "properties": { "inventoryItemId": { "type": "string", "format": "uuid" }, "quantityOrdered": { "type": "number", "example": 50 } } } } } }, "PurchaseOrderResponse": { "type": "object", "required": [ "id", "poNumber", "status", "supplierId", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "poNumber": { "type": "string", "example": "PO-2026-041" }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "PARTIALLY_RECEIVED", "RECEIVED", "CLOSED" ] }, "supplierId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" } } }, "RosterMatrixResponse": { "type": "object", "required": [ "outletId", "startDate", "endDate", "matrix" ], "properties": { "outletId": { "type": "string", "format": "uuid" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "matrix": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string", "format": "uuid" }, "employeeName": { "type": "string", "example": "Priya Sharma" }, "role": { "type": "string", "example": "Head Barista" }, "shifts": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "shiftType": { "type": "string", "enum": [ "MORNING", "EVENING", "NIGHT", "OFF" ] }, "startTime": { "type": "string", "example": "07:00" }, "endTime": { "type": "string", "example": "15:30" } } } } } } } } }, "AttendanceClockRequest": { "type": "object", "required": [ "employeePin", "eventType" ], "properties": { "employeePin": { "type": "string", "example": "4819" }, "eventType": { "type": "string", "enum": [ "CLOCK_IN", "CLOCK_OUT", "BREAK_START", "BREAK_END" ] } } }, "AttendanceResponse": { "type": "object", "required": [ "id", "employeeName", "eventType", "timestamp", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "employeeName": { "type": "string", "example": "Rajesh Kumar" }, "eventType": { "type": "string", "example": "CLOCK_IN" }, "timestamp": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "ON_TIME", "LATE", "EARLY" ] } } }, "AnalyticsSummaryResponse": { "type": "object", "required": [ "period", "grossRevenueCents", "ordersCount", "cogsPercentage", "foodWasteCents" ], "properties": { "period": { "type": "string", "example": "TODAY" }, "grossRevenueCents": { "type": "integer", "example": 1428000 }, "ordersCount": { "type": "integer", "example": 142 }, "averageTicketCents": { "type": "integer", "example": 10056 }, "cogsPercentage": { "type": "number", "example": 28.4 }, "foodWasteCents": { "type": "integer", "example": 34000 } } }, "ProblemDetails": { "type": "object", "description": "Standard RFC 9457 Problem Details for HTTP APIs", "required": [ "type", "title", "status", "detail", "code" ], "properties": { "type": { "type": "string", "format": "uri", "example": "https://alaynai.com/errors/invalid-request" }, "title": { "type": "string", "example": "Invalid Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "The request body failed validation." }, "instance": { "type": "string", "example": "/orders" }, "code": { "type": "string", "example": "ERR_INVALID_OUTLET_SCOPE" } } }, "Error": { "type": "object", "description": "Standard RFC 9457 Problem Details for HTTP APIs", "required": [ "type", "title", "status", "detail", "code" ], "properties": { "type": { "type": "string", "format": "uri", "example": "https://alaynai.com/errors/invalid-request" }, "title": { "type": "string", "example": "Invalid Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "The request body failed validation." }, "instance": { "type": "string", "example": "/orders" }, "code": { "type": "string", "example": "ERR_INVALID_OUTLET_SCOPE" } } } } }, "externalDocs": { "description": "Official API Deprecation & Sunset Policy", "url": "https://alaynai.com/deprecation" } }