{ "openapi": "3.1.0", "info": { "title": "TechTur POS API", "version": "1.0.0", "description": "Versioned REST API for TechTur POS. Money is a decimal string in ZAR unless stated. Every business-scoped route lives under `/api/v1/businesses/{businessId}`. Authenticate with an OAuth 2.0 access token (`Authorization: Bearer …`); dashboard routes also accept the browser session cookie. See https://pos.techtursolutions.com/developers.", "contact": { "name": "TechTur Solutions", "url": "https://pos.techtursolutions.com/developers" } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "OAuth 2.0 access token or business API key" }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "tps_session" } }, "schemas": {} }, "paths": { "/api/v1/health": { "get": { "summary": "Liveness", "tags": [ "Health" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/health/ready": { "get": { "summary": "Readiness: database and worker heartbeat", "tags": [ "Health" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/register": { "post": { "summary": "Create an account (email verification required)", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 10, "maxLength": 200 } }, "required": [ "name", "email", "password" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/verify-email": { "post": { "summary": "Confirm an email address and sign in", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 10 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/login": { "post": { "summary": "Sign in with email and password", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/resend-verification": { "post": { "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/me": { "get": { "summary": "The signed-in user, their businesses and MFA state", "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/switch-business": { "post": { "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "businessId": { "type": "string" } }, "required": [ "businessId" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/password/forgot": { "post": { "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/password/reset": { "post": { "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 10 }, "password": { "type": "string", "minLength": 10, "maxLength": 200 } }, "required": [ "token", "password" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/mfa/setup": { "post": { "summary": "Start TOTP enrolment", "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/mfa/enable": { "post": { "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 8 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/mfa/verify": { "post": { "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 8 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/sessions": { "get": { "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/sessions/revoke-others": { "post": { "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/invitations/{token}": { "get": { "tags": [ "Staff" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "token", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/invitations/accept": { "post": { "tags": [ "Staff" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "password": { "type": "string", "minLength": 10, "maxLength": 200 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses": { "post": { "summary": "Create a business (you become its owner)", "tags": [ "Businesses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "type": "string", "enum": [ "RETAIL", "FOOD", "SERVICES", "MIXED" ] }, "vatRegistered": { "default": false, "type": "boolean" }, "vatNumber": { "type": "string", "pattern": "^4\\d{9}$" }, "pricesIncludeTax": { "default": true, "type": "boolean" }, "city": { "type": "string", "maxLength": 80 } }, "required": [ "name", "type" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}": { "get": { "summary": "Business profile", "tags": [ "Businesses" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "tags": [ "Businesses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "legalName": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "RETAIL", "FOOD", "SERVICES", "MIXED" ] }, "registrationNumber": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "vatRegistered": { "type": "boolean" }, "vatNumber": { "anyOf": [ { "type": "string", "pattern": "^4\\d{9}$" }, { "type": "null" } ] }, "pricesIncludeTax": { "type": "boolean" }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "addressLine1": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "addressLine2": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string", "maxLength": 10 }, { "type": "null" } ] }, "receiptHeader": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "receiptFooter": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "logoUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "fiscalYearStartMonth": { "type": "integer", "minimum": 1, "maximum": 12 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/onboarding": { "post": { "summary": "Record onboarding progress", "tags": [ "Businesses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "step": { "type": "string", "enum": [ "profile", "tax", "store", "register", "staff", "products", "payments", "hardware", "receipts", "stock", "float", "review", "done" ] }, "completed": { "type": "array", "items": { "type": "string", "enum": [ "profile", "tax", "store", "register", "staff", "products", "payments", "hardware", "receipts", "stock", "float", "review", "done" ] } } }, "required": [ "step" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/readiness": { "get": { "tags": [ "Businesses" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/locations": { "get": { "tags": [ "Locations" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "type": { "default": "STORE", "type": "string", "enum": [ "STORE", "WAREHOUSE" ] }, "addressLine1": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "isActive": { "default": true, "type": "boolean" } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/locations/{id}": { "patch": { "tags": [ "Locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "type": { "default": "STORE", "type": "string", "enum": [ "STORE", "WAREHOUSE" ] }, "addressLine1": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "isActive": { "default": true, "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/registers": { "get": { "tags": [ "Registers" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Registers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "mode": { "default": "RETAIL", "type": "string", "enum": [ "RETAIL", "FOOD" ] }, "isActive": { "default": true, "type": "boolean" } }, "required": [ "name", "locationId" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/registers/{id}": { "patch": { "tags": [ "Registers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "mode": { "default": "RETAIL", "type": "string", "enum": [ "RETAIL", "FOOD" ] }, "isActive": { "default": true, "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/staff": { "get": { "tags": [ "Staff" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/invitations": { "post": { "tags": [ "Staff" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "roleId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "email", "roleId" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/invitations/{id}": { "delete": { "tags": [ "Staff" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/staff/{id}": { "patch": { "summary": "Change a member's role or suspend them", "tags": [ "Staff" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roleId": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "ACTIVE", "SUSPENDED" ] }, "pin": { "anyOf": [ { "type": "string", "pattern": "^\\d{4,6}$" }, { "type": "null" } ] } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/roles": { "get": { "tags": [ "Staff" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create a custom role", "tags": [ "Staff" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": { "type": "string", "maxLength": 200 }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": [ "name", "permissions" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/roles/{id}": { "patch": { "tags": [ "Staff" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": { "type": "string", "maxLength": 200 }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "string" } } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/audit": { "get": { "tags": [ "Audit" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "action", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "entityId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/plans": { "get": { "summary": "Public pricing plans", "tags": [ "Businesses" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/categories": { "get": { "tags": [ "Catalogue" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "sortOrder": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/categories/{id}": { "patch": { "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "sortOrder": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "archived": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/products": { "get": { "summary": "List products with variants and barcodes", "tags": [ "Catalogue" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "q", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "categoryId", "required": false }, { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "includeArchived", "required": false }, { "schema": {}, "in": "query", "name": "updatedSince", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create a product", "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "brand": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "type": { "default": "STANDARD", "type": "string", "enum": [ "STANDARD", "SERVICE", "NON_STOCK", "BUNDLE", "COMPOSITE" ] }, "taxClass": { "default": "STANDARD", "type": "string", "enum": [ "STANDARD", "ZERO_RATED", "EXEMPT" ] }, "unit": { "default": "each", "type": "string", "maxLength": 20 }, "trackStock": { "default": true, "type": "boolean" }, "isActive": { "default": true, "type": "boolean" }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 1000, "format": "uri" }, { "type": "null" } ] }, "prepNotes": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "kitchenStation": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "variants": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "default": "Default", "type": "string", "minLength": 1, "maxLength": 120 }, "sku": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "attributes": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "price": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "costPrice": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, { "type": "null" } ] }, "wholesalePrice": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, { "type": "null" } ] }, "barcodes": { "default": [], "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 64 } }, "isDefault": { "type": "boolean" }, "components": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "variantId", "quantity" ] } }, "reorderLevel": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "price" ] } }, "modifierGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "minSelect": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maxSelect": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "modifiers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "priceDelta": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "consumesVariantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "consumesQuantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "isDefault": { "type": "boolean" } }, "required": [ "name" ] } } }, "required": [ "name", "modifiers" ] } } }, "required": [ "name", "variants" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/products/{id}": { "get": { "tags": [ "Catalogue" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "put": { "summary": "Replace a product and its variants", "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "brand": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "type": { "default": "STANDARD", "type": "string", "enum": [ "STANDARD", "SERVICE", "NON_STOCK", "BUNDLE", "COMPOSITE" ] }, "taxClass": { "default": "STANDARD", "type": "string", "enum": [ "STANDARD", "ZERO_RATED", "EXEMPT" ] }, "unit": { "default": "each", "type": "string", "maxLength": 20 }, "trackStock": { "default": true, "type": "boolean" }, "isActive": { "default": true, "type": "boolean" }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 1000, "format": "uri" }, { "type": "null" } ] }, "prepNotes": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "kitchenStation": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "variants": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "default": "Default", "type": "string", "minLength": 1, "maxLength": 120 }, "sku": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "attributes": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "price": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "costPrice": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, { "type": "null" } ] }, "wholesalePrice": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, { "type": "null" } ] }, "barcodes": { "default": [], "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 64 } }, "isDefault": { "type": "boolean" }, "components": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "variantId", "quantity" ] } }, "reorderLevel": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "price" ] } }, "modifierGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "minSelect": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maxSelect": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "modifiers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "priceDelta": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "consumesVariantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "consumesQuantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "isDefault": { "type": "boolean" } }, "required": [ "name" ] } } }, "required": [ "name", "modifiers" ] } } }, "required": [ "name", "variants" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Archive a product (history is kept)", "tags": [ "Catalogue" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/products/{id}/availability": { "patch": { "summary": "Mark sold out / available (food mode)", "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "soldOut": { "type": "boolean" }, "isActive": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/barcodes/{code}": { "get": { "summary": "Look up a scanned barcode or SKU", "tags": [ "Catalogue" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "maxLength": 64 }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/registers/{id}/catalogue": { "get": { "summary": "Offline catalogue snapshot for a register", "tags": [ "Registers" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/promotions": { "get": { "tags": [ "Catalogue" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "code": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "minSpend": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ {}, { "type": "null" } ] }, "endsAt": { "anyOf": [ {}, { "type": "null" } ] }, "maxUses": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "isActive": { "default": true, "type": "boolean" } }, "required": [ "name", "kind", "value" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/promotions/{id}": { "patch": { "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "code": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "minSpend": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ {}, { "type": "null" } ] }, "endsAt": { "anyOf": [ {}, { "type": "null" } ] }, "maxUses": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "isActive": { "default": true, "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/sync/products": { "put": { "summary": "Upsert products from a connected platform (by external ID)", "tags": [ "Integrations" ], "description": "Idempotent bulk upsert. External IDs are mapped to POS IDs; unchanged items are skipped; fields POS owns are never overwritten and differing values are recorded as conflicts. Requires an application token with products:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "object", "properties": { "externalId": { "type": "string", "maxLength": 128 }, "name": { "type": "string", "maxLength": 120 } }, "required": [ "externalId", "name" ] }, { "type": "null" } ] }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 1000, "format": "uri" }, { "type": "null" } ] }, "taxClass": { "type": "string", "enum": [ "STANDARD", "ZERO_RATED", "EXEMPT" ] }, "type": { "type": "string", "enum": [ "STANDARD", "SERVICE", "NON_STOCK" ] }, "trackStock": { "type": "boolean" }, "isActive": { "default": true, "type": "boolean" }, "variants": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "default": "Default", "type": "string", "minLength": 1, "maxLength": 120 }, "sku": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "attributes": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "price": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "barcodes": { "default": [], "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 64 } } }, "required": [ "externalId", "price" ] } }, "modifierGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "minSelect": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maxSelect": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "modifiers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "priceDelta": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "consumesVariantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "consumesQuantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "isDefault": { "type": "boolean" } }, "required": [ "name" ] } } }, "required": [ "name", "modifiers" ] } } }, "required": [ "externalId", "name", "variants" ] } } }, "required": [ "products" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/mappings": { "get": { "summary": "External ID mappings for the calling application", "tags": [ "Integrations" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "entityType", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "externalId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/stock": { "get": { "summary": "Stock levels (on hand, reserved, available)", "tags": [ "Inventory" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "locationId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "variantId", "required": false }, { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "lowOnly", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "q", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/stock/{id}": { "patch": { "summary": "Set reorder level and quantity", "tags": [ "Inventory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reorderLevel": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, { "type": "null" } ] }, "reorderQty": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, { "type": "null" } ] } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/stock/adjustments": { "post": { "summary": "Adjust stock: opening stock, corrections, damage", "tags": [ "Inventory" ], "description": "Positive quantities add stock (OPENING requires unitCost). The value change posts to the ledger: opening stock against opening balance equity, corrections and damage against stock adjustments.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "OPENING", "ADJUSTMENT", "DAMAGE" ] }, "note": { "type": "string", "maxLength": 300 }, "lines": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "unitCost": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "lotNumber": { "type": "string", "maxLength": 60 }, "expiryDate": {}, "serialNumber": { "type": "string", "maxLength": 80 } }, "required": [ "variantId", "quantity" ] } } }, "required": [ "locationId", "type", "lines" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/stock/movements": { "get": { "summary": "The stock ledger", "tags": [ "Inventory" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "variantId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "locationId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "type", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/stock/transfers": { "post": { "summary": "Move stock between locations at cost", "tags": [ "Inventory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromLocationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "toLocationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "note": { "type": "string", "maxLength": 300 }, "lines": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "variantId", "quantity" ] } } }, "required": [ "fromLocationId", "toLocationId", "lines" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/stock/counts": { "get": { "tags": [ "Inventory" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Start a full or cycle count (snapshots expected quantities)", "tags": [ "Inventory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "variantIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "categoryId": { "type": "string", "minLength": 1, "maxLength": 64 }, "note": { "type": "string", "maxLength": 300 } }, "required": [ "locationId" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/stock/counts/{id}": { "get": { "tags": [ "Inventory" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "summary": "Record counted quantities", "tags": [ "Inventory" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "counts": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "counted": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "variantId", "counted" ] } } }, "required": [ "counts" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/stock/counts/{id}/complete": { "post": { "summary": "Finalise a count: post variances as adjustments", "tags": [ "Inventory" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/suppliers": { "get": { "tags": [ "Purchasing" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "q", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Purchasing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "contactName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "vatNumber": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "addressLine1": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "paymentTermsDays": { "default": 30, "type": "integer", "minimum": 0, "maximum": 365 }, "notes": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/suppliers/{id}": { "get": { "tags": [ "Purchasing" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "tags": [ "Purchasing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "contactName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "vatNumber": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "addressLine1": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "paymentTermsDays": { "default": 30, "type": "integer", "minimum": 0, "maximum": 365 }, "notes": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "archived": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/purchase-orders": { "get": { "tags": [ "Purchasing" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Purchasing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplierId": { "type": "string", "minLength": 1, "maxLength": 64 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "expectedAt": {}, "notes": { "type": "string", "maxLength": 1000 }, "lines": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "unitCost": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "taxClass": { "default": "STANDARD", "type": "string", "enum": [ "STANDARD", "ZERO_RATED", "EXEMPT" ] } }, "required": [ "variantId", "quantity", "unitCost" ] } } }, "required": [ "supplierId", "locationId", "lines" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/purchase-orders/{id}": { "get": { "tags": [ "Purchasing" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/purchase-orders/{id}/status": { "post": { "tags": [ "Purchasing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "SENT", "CANCELLED" ] } }, "required": [ "status" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/purchase-orders/{id}/receive": { "post": { "summary": "Receive goods (full or partial)", "tags": [ "Purchasing" ], "description": "Adds stock at the ordered cost and posts Dr Inventory / Cr Goods received not invoiced.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string", "minLength": 1, "maxLength": 64 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "unitCost": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "lotNumber": { "type": "string", "maxLength": 60 }, "expiryDate": {} }, "required": [ "lineId", "quantity" ] } } }, "required": [ "lines" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/purchase-orders/{id}/return": { "post": { "summary": "Return received goods to the supplier", "tags": [ "Purchasing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 300 }, "lines": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "string", "minLength": 1, "maxLength": 64 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "lineId", "quantity" ] } } }, "required": [ "reason", "lines" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/bills": { "get": { "tags": [ "Purchasing" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "supplierId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Capture a supplier invoice", "tags": [ "Purchasing" ], "description": "Against a purchase order the net clears goods-received-not-invoiced; otherwise give an expense account. VAT is claimable input tax only when the business is VAT registered.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplierId": { "type": "string", "minLength": 1, "maxLength": 64 }, "purchaseOrderId": { "type": "string", "minLength": 1, "maxLength": 64 }, "reference": { "type": "string", "minLength": 1, "maxLength": 60 }, "issueDate": {}, "dueDate": {}, "netAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "taxAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "expenseAccountId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "supplierId", "reference", "issueDate", "netAmount" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/bills/{id}/payments": { "post": { "summary": "Pay a supplier invoice", "tags": [ "Purchasing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "paidFrom": { "default": "BANK", "type": "string", "enum": [ "BANK", "CASH" ] }, "date": {}, "reference": { "type": "string", "maxLength": 60 } }, "required": [ "amount" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/customers": { "get": { "tags": [ "Customers" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "q", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false }, { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "withBalance", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "vatNumber": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "addressLine1": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "group": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "marketingConsent": { "default": false, "type": "boolean" } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/customers/{id}": { "get": { "summary": "Customer profile with purchase history", "tags": [ "Customers" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "vatNumber": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "addressLine1": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "group": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "marketingConsent": { "default": false, "type": "boolean" }, "archived": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/customers/{id}/payments": { "post": { "summary": "Receive a payment against a customer's account balance", "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "method": { "type": "string", "enum": [ "CASH", "CARD", "EFT" ] }, "reference": { "type": "string", "maxLength": 60 } }, "required": [ "amount", "method" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/customers/{id}/statement": { "get": { "summary": "Account statement", "tags": [ "Customers" ], "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/sales/price": { "post": { "summary": "Price a basket without saving it", "tags": [ "Sales" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "registerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "lines": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "maxLength": 200 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "unitPrice": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "taxClass": { "type": "string", "enum": [ "STANDARD", "ZERO_RATED", "EXEMPT" ] }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "modifierIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "note": { "type": "string", "maxLength": 300 } }, "required": [ "quantity" ] } }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "promotionCode": { "type": "string", "maxLength": 40 }, "note": { "type": "string", "maxLength": 500 }, "clientCreatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "locationId", "lines" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/sales": { "post": { "summary": "Ring up a sale: complete, park, or save as a quotation", "tags": [ "Sales" ], "description": "Idempotent with `idempotencyKey` (or the Idempotency-Key header): a replay returns the original sale with `replayed: true`. Card and EFT payments must be confirmed (`confirmed: true`) unless an integrated provider reports the result; an unconfirmed payment never completes a sale.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "registerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "lines": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "maxLength": 200 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "unitPrice": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "taxClass": { "type": "string", "enum": [ "STANDARD", "ZERO_RATED", "EXEMPT" ] }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "modifierIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "note": { "type": "string", "maxLength": 300 } }, "required": [ "quantity" ] } }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "promotionCode": { "type": "string", "maxLength": 40 }, "note": { "type": "string", "maxLength": 500 }, "clientCreatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "action": { "default": "complete", "type": "string", "enum": [ "complete", "park", "quote" ] }, "payments": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "CASH", "CARD", "EFT", "STORE_CREDIT", "ACCOUNT", "OTHER" ] }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "tendered": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "provider": { "type": "string", "maxLength": 60 }, "providerRef": { "type": "string", "maxLength": 120 }, "cardSummary": { "type": "string", "maxLength": 40, "pattern": "^[^0-9]*(\\d{0,4})$" }, "confirmed": { "type": "boolean" }, "fee": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "method", "amount" ] } }, "allowBalanceDue": { "default": false, "type": "boolean" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 100 } }, "required": [ "locationId", "lines" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "get": { "summary": "List sales and orders", "tags": [ "Sales" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "channel", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "registerId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "customerId", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "maxLength": 60 }, "in": "query", "name": "q", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/sales/batch": { "post": { "summary": "Upload sales captured offline", "tags": [ "Sales" ], "description": "Each sale must carry an idempotencyKey. Results are per sale, so one rejected sale does not block the rest.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sales": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "registerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "lines": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "maxLength": 200 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "unitPrice": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "taxClass": { "type": "string", "enum": [ "STANDARD", "ZERO_RATED", "EXEMPT" ] }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "modifierIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "note": { "type": "string", "maxLength": 300 } }, "required": [ "quantity" ] } }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "promotionCode": { "type": "string", "maxLength": 40 }, "note": { "type": "string", "maxLength": 500 }, "clientCreatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "action": { "default": "complete", "type": "string", "enum": [ "complete", "park", "quote" ] }, "payments": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "CASH", "CARD", "EFT", "STORE_CREDIT", "ACCOUNT", "OTHER" ] }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "tendered": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "provider": { "type": "string", "maxLength": 60 }, "providerRef": { "type": "string", "maxLength": 120 }, "cardSummary": { "type": "string", "maxLength": 40, "pattern": "^[^0-9]*(\\d{0,4})$" }, "confirmed": { "type": "boolean" }, "fee": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "method", "amount" ] } }, "allowBalanceDue": { "default": false, "type": "boolean" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 100 } }, "required": [ "locationId", "lines", "idempotencyKey" ] } } }, "required": [ "sales" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/sales/{id}": { "get": { "tags": [ "Sales" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "put": { "summary": "Update a parked sale or quotation", "tags": [ "Sales" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "registerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "lines": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "maxLength": 200 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "unitPrice": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "taxClass": { "type": "string", "enum": [ "STANDARD", "ZERO_RATED", "EXEMPT" ] }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "modifierIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "note": { "type": "string", "maxLength": 300 } }, "required": [ "quantity" ] } }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "promotionCode": { "type": "string", "maxLength": 40 }, "note": { "type": "string", "maxLength": 500 }, "clientCreatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "action": { "default": "park", "type": "string", "enum": [ "park", "quote" ] } }, "required": [ "locationId", "lines" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/sales/{id}/receipt": { "get": { "summary": "Receipt / tax invoice document", "tags": [ "Sales" ], "parameters": [ { "schema": { "default": "json", "type": "string", "enum": [ "json", "text" ] }, "in": "query", "name": "format", "required": false }, { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "reprint", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/sales/{id}/complete": { "post": { "summary": "Resume a parked sale or convert a quotation, and take payment", "tags": [ "Sales" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "registerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "lines": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "maxLength": 200 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "unitPrice": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "taxClass": { "type": "string", "enum": [ "STANDARD", "ZERO_RATED", "EXEMPT" ] }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "modifierIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "note": { "type": "string", "maxLength": 300 } }, "required": [ "quantity" ] } }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "promotionCode": { "type": "string", "maxLength": 40 }, "note": { "type": "string", "maxLength": 500 }, "clientCreatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "payments": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "CASH", "CARD", "EFT", "STORE_CREDIT", "ACCOUNT", "OTHER" ] }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "tendered": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "provider": { "type": "string", "maxLength": 60 }, "providerRef": { "type": "string", "maxLength": 120 }, "cardSummary": { "type": "string", "maxLength": 40, "pattern": "^[^0-9]*(\\d{0,4})$" }, "confirmed": { "type": "boolean" }, "fee": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "method", "amount" ] } }, "allowBalanceDue": { "default": false, "type": "boolean" } }, "required": [ "locationId", "lines", "payments" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/sales/{id}/void": { "post": { "tags": [ "Sales" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 300 } }, "required": [ "reason" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/sales/{id}/refunds": { "post": { "summary": "Refund some or all of a completed sale", "tags": [ "Sales" ], "description": "Restocks at the original cost when `restock` is true. Card/EFT refunds must be confirmed as processed. Posts reversing ledger entries; the original sale is never edited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "saleLineId": { "type": "string", "minLength": 1, "maxLength": 64 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "saleLineId", "quantity" ] } }, "reason": { "type": "string", "minLength": 3, "maxLength": 300 }, "restock": { "default": true, "type": "boolean" }, "method": { "type": "string", "enum": [ "CASH", "CARD", "EFT", "STORE_CREDIT", "ACCOUNT", "OTHER" ] }, "registerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "providerRef": { "type": "string", "maxLength": 120 }, "confirmed": { "type": "boolean" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 100 } }, "required": [ "lines", "reason", "method" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/orders": { "post": { "summary": "Submit an online or platform order", "tags": [ "Orders" ], "description": "Idempotent on `externalRef` per application: resubmitting returns the existing order. A paid order (with `payment`) completes immediately and deducts stock once; an unpaid order reserves stock until it is marked paid or cancelled. POS is the authority for physical stock, so the platform must not also decrement its own count.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalRef": { "type": "string", "minLength": 1, "maxLength": 128 }, "locationId": { "type": "string", "minLength": 1, "maxLength": 64 }, "customer": { "type": "object", "properties": { "externalId": { "type": "string", "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "maxLength": 30 } }, "required": [ "name" ] }, "lines": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "externalVariantId": { "type": "string", "maxLength": 128 }, "quantity": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "unitPrice": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "modifierIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "note": { "type": "string", "maxLength": 300 } }, "required": [ "quantity" ] } }, "payment": { "type": "object", "properties": { "method": { "default": "OTHER", "type": "string", "enum": [ "CARD", "EFT", "OTHER" ] }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "provider": { "type": "string", "maxLength": 60 }, "reference": { "type": "string", "maxLength": 120 } }, "required": [ "amount", "provider", "reference" ] }, "discount": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PERCENT", "FIXED" ] }, "value": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "kind", "value" ] }, "fulfilment": { "default": "pickup", "type": "string", "enum": [ "pickup", "delivery", "dine_in" ] }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "externalRef", "lines" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/orders/{id}": { "get": { "summary": "Get an order by POS id or by your externalRef (prefix `ext:`)", "tags": [ "Orders" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "summary": "Mark paid, cancel, or move fulfilment status", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "pay", "cancel", "fulfil" ] }, "payment": { "type": "object", "properties": { "method": { "default": "OTHER", "type": "string", "enum": [ "CARD", "EFT", "OTHER" ] }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "provider": { "type": "string", "maxLength": 60 }, "reference": { "type": "string", "maxLength": 120 } }, "required": [ "amount", "provider", "reference" ] }, "fulfilmentStatus": { "type": "string", "enum": [ "received", "accepted", "preparing", "ready", "out_for_delivery", "delivered", "collected" ] }, "reason": { "type": "string", "maxLength": 300 } }, "required": [ "action" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/shifts": { "post": { "summary": "Open a register shift with a cash float", "tags": [ "Shifts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "registerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "openingFloat": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "registerId", "openingFloat" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "get": { "tags": [ "Shifts" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "registerId", "required": false }, { "schema": { "type": "string", "enum": [ "OPEN", "CLOSED" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/shifts/{id}": { "get": { "summary": "Shift summary (X report while open, Z report once closed)", "tags": [ "Shifts" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/shifts/{id}/cash": { "post": { "summary": "Cash in, cash out, or open the drawer without a sale", "tags": [ "Shifts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CASH_IN", "CASH_OUT", "DRAWER_OPEN" ] }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "reason": { "type": "string", "minLength": 2, "maxLength": 200 }, "accountId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "type", "reason" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/shifts/{id}/close": { "post": { "summary": "Cash-up: count the drawer and close the shift", "tags": [ "Shifts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countedCash": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "denominations": { "type": "object", "propertyNames": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "countedCash" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/accounts": { "get": { "summary": "Chart of accounts", "tags": [ "Accounting" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Accounting" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{3,6}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "type": { "type": "string", "enum": [ "ASSET", "LIABILITY", "EQUITY", "INCOME", "EXPENSE" ] } }, "required": [ "code", "name", "type" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/accounts/{id}": { "patch": { "tags": [ "Accounting" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "isActive": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/journals": { "get": { "tags": [ "Accounting" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "sourceType", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Post a manual journal", "tags": [ "Accounting" ], "description": "Must balance. Use for opening balances, accruals and corrections. Posted entries are never edited; reverse them instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": {}, "description": { "type": "string", "minLength": 3, "maxLength": 300 }, "kind": { "default": "MANUAL", "type": "string", "enum": [ "MANUAL", "OPENING_BALANCE" ] }, "lines": { "minItems": 2, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 64 }, "debit": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "credit": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "accountId" ] } } }, "required": [ "date", "description", "lines" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/journals/{id}/reverse": { "post": { "summary": "Reverse a posted entry", "tags": [ "Accounting" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 300 }, "date": {} }, "required": [ "reason" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reports/trial-balance": { "get": { "tags": [ "Accounting" ], "parameters": [ { "schema": {}, "in": "query", "name": "asOf", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reports/profit-and-loss": { "get": { "tags": [ "Accounting" ], "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": true }, { "schema": {}, "in": "query", "name": "to", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reports/balance-sheet": { "get": { "tags": [ "Accounting" ], "parameters": [ { "schema": {}, "in": "query", "name": "asOf", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reports/cash-flow": { "get": { "tags": [ "Accounting" ], "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": true }, { "schema": {}, "in": "query", "name": "to", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reports/vat": { "get": { "summary": "VAT summary for VAT201 preparation", "tags": [ "Accounting" ], "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": true }, { "schema": {}, "in": "query", "name": "to", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/accounts/{id}/ledger": { "get": { "summary": "General ledger for one account", "tags": [ "Accounting" ], "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": true }, { "schema": {}, "in": "query", "name": "to", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/expenses": { "get": { "tags": [ "Accounting" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Record an expense", "tags": [ "Accounting" ], "description": "Give the total; VAT is extracted at the standard rate when `includesVat` and the business is VAT registered.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": {}, "accountId": { "type": "string", "minLength": 1, "maxLength": 64 }, "paidFromAccountId": { "type": "string", "minLength": 1, "maxLength": 64 }, "supplierId": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "minLength": 2, "maxLength": 300 }, "total": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] }, "includesVat": { "default": true, "type": "boolean" }, "reference": { "type": "string", "maxLength": 60 } }, "required": [ "date", "accountId", "paidFromAccountId", "description", "total" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/periods": { "get": { "tags": [ "Accounting" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/periods/close": { "post": { "summary": "Close a period: nothing can post into it afterwards", "tags": [ "Accounting" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "startDate": {}, "endDate": {} }, "required": [ "startDate", "endDate" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/periods/{id}/reopen": { "post": { "tags": [ "Accounting" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 5, "maxLength": 300 } }, "required": [ "reason" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reconciliation/imports": { "post": { "summary": "Import a bank or provider statement (CSV)", "tags": [ "Reconciliation" ], "description": "CSV with a header row containing date, description, amount (positive = money in), and optionally reference. Returns row-level errors; nothing is saved if any row is invalid.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1, "maxLength": 64 }, "fileName": { "type": "string", "maxLength": 200 }, "csv": { "type": "string", "minLength": 1, "maxLength": 5000000 }, "source": { "default": "csv", "type": "string", "maxLength": 40 } }, "required": [ "accountId", "fileName", "csv" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reconciliation/lines": { "get": { "tags": [ "Reconciliation" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "enum": [ "UNMATCHED", "MATCHED", "IGNORED" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "importId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reconciliation/lines/{id}/settle": { "post": { "summary": "Record a card/EFT settlement into the bank, net of provider fees", "tags": [ "Reconciliation" ], "description": "Posts Dr Bank (the statement amount), Dr Payment provider fees, Cr the clearing account (gross).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clearing": { "type": "string", "enum": [ "CARD_CLEARING", "EFT_CLEARING", "OTHER_CLEARING" ] }, "feeAmount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "number" } ] } }, "required": [ "clearing" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reconciliation/lines/{id}/match": { "post": { "summary": "Match a statement line to an existing journal entry, or ignore it", "tags": [ "Reconciliation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "journalEntryId": { "type": "string", "minLength": 1, "maxLength": 64 }, "ignore": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reports/overview": { "get": { "summary": "Business dashboard figures", "tags": [ "Reports" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reports/sales": { "get": { "summary": "Sales over time", "tags": [ "Reports" ], "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": true }, { "schema": {}, "in": "query", "name": "to", "required": true }, { "schema": { "default": "day", "type": "string", "enum": [ "day", "week", "month" ] }, "in": "query", "name": "groupBy", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "locationId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "channel", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reports/sales-by": { "get": { "summary": "Sales broken down by product, category, payment method, cashier, register, channel or location", "tags": [ "Reports" ], "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": true }, { "schema": {}, "in": "query", "name": "to", "required": true }, { "schema": { "type": "string", "enum": [ "product", "category", "payment_method", "cashier", "register", "channel", "location" ] }, "in": "query", "name": "dimension", "required": true }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reports/inventory": { "get": { "summary": "Valuation, low stock, slow movers, dead stock and reorder suggestions", "tags": [ "Reports" ], "parameters": [ { "schema": { "type": "string", "enum": [ "valuation", "low_stock", "slow_moving", "dead_stock", "reorder", "turnover" ] }, "in": "query", "name": "kind", "required": true }, { "schema": { "default": 30, "type": "integer", "minimum": 7, "maximum": 365 }, "in": "query", "name": "days", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "locationId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/reports/customers": { "get": { "summary": "Retention and repeat purchasing", "tags": [ "Reports" ], "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": true }, { "schema": {}, "in": "query", "name": "to", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/catalogue": { "get": { "summary": "Scopes and webhook events you can use", "tags": [ "Developer" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/applications": { "get": { "tags": [ "Developer" ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Register an application (the secret is shown once)", "tags": [ "Developer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "description": { "type": "string", "maxLength": 1000 }, "websiteUrl": { "type": "string", "maxLength": 300, "format": "uri" }, "redirectUris": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 500, "format": "uri" } }, "requestedScopes": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "environment": { "default": "SANDBOX", "type": "string", "enum": [ "SANDBOX", "LIVE" ] } }, "required": [ "name", "requestedScopes" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/applications/{id}": { "get": { "tags": [ "Developer" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "tags": [ "Developer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "description": { "type": "string", "maxLength": 1000 }, "websiteUrl": { "type": "string", "maxLength": 300, "format": "uri" }, "redirectUris": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 500, "format": "uri" } }, "requestedScopes": { "minItems": 1, "type": "array", "items": { "type": "string" } } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "summary": "Revoke the application and every token it holds", "tags": [ "Developer" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/applications/{id}/rotate-secret": { "post": { "summary": "Issue a new client secret (the old one stops working)", "tags": [ "Developer" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/applications/{id}/manifest": { "post": { "summary": "Validate and attach a techtur-pos.connector.json manifest", "tags": [ "Developer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "manifest": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "manifest" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/applications/{id}/webhooks": { "post": { "summary": "Add a webhook endpoint (signing secret shown once)", "tags": [ "Developer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "format": "uri" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url", "events" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/applications/{id}/webhooks/{webhookId}": { "patch": { "tags": [ "Developer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "format": "uri" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "maxLength": 200 }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "Developer" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/applications/{id}/webhooks/{webhookId}/test": { "post": { "summary": "Send a signed webhook.test event now", "tags": [ "Developer" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/applications/{id}/deliveries": { "get": { "tags": [ "Developer" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "DEAD" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/deliveries/{id}/retry": { "post": { "summary": "Redeliver an event now", "tags": [ "Developer" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/applications/{id}/requests": { "get": { "summary": "API request log", "tags": [ "Developer" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "errorsOnly", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/sandbox": { "post": { "summary": "Create a sandbox business with test data", "tags": [ "Developer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "default": "Sandbox Store", "type": "string", "minLength": 2, "maxLength": 80 }, "type": { "default": "RETAIL", "type": "string", "enum": [ "RETAIL", "FOOD" ] } } } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/developer/applications/{id}/sandbox-token": { "post": { "summary": "Connect a sandbox app to your sandbox business and mint a 24h test token", "tags": [ "Developer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "businessId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "businessId" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/connections": { "get": { "summary": "Applications this business has connected", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/connections/{id}": { "delete": { "summary": "Disconnect an application (revokes its tokens for this business)", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/sync-conflicts/{id}/resolve": { "post": { "tags": [ "Integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resolution": { "type": "string", "enum": [ "KEEP_LOCAL", "ACCEPT_REMOTE" ] } }, "required": [ "resolution" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/api-keys": { "get": { "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Create a business API key (shown once)", "tags": [ "Integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 60 }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 730 } }, "required": [ "name", "scopes" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/api-keys/{id}": { "delete": { "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/webhooks": { "get": { "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "format": "uri" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url", "events" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/webhooks/{id}": { "delete": { "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/platform/me": { "get": { "summary": "Who this connector token belongs to", "tags": [ "Platform" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/platform/launch-tickets": { "post": { "summary": "Mint a one-time launch link for a signed-in platform user", "tags": [ "Platform" ], "description": "Called server-to-server by a TechTur platform. Returns a single-use code valid for five minutes; redirect the user's browser to `launchUrl`. Never put access tokens in URLs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalUserId": { "type": "string", "minLength": 1, "maxLength": 128 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "displayName": { "type": "string", "maxLength": 120 }, "externalBusinessId": { "type": "string", "maxLength": 128 }, "businessName": { "type": "string", "maxLength": 120 }, "businessRole": { "type": "string", "enum": [ "owner", "manager", "staff" ] }, "returnUrl": { "type": "string", "format": "uri" } }, "required": [ "externalUserId" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/platform/launch/exchange": { "post": { "summary": "Browser: redeem a launch code", "tags": [ "Platform" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 20 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/platform/launch/link": { "post": { "summary": "Signed in: link this platform identity to your existing account", "tags": [ "Platform" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 20 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/platform/launch/consent": { "post": { "summary": "Owner consents to creating and linking a POS business for their platform business", "tags": [ "Platform" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 20 }, "type": { "default": "RETAIL", "type": "string", "enum": [ "RETAIL", "FOOD", "SERVICES", "MIXED" ] } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/platform/businesses": { "get": { "summary": "Businesses linked to this platform", "tags": [ "Platform" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/platform/businesses/{externalBusinessId}": { "get": { "summary": "Resolve one platform business to its POS business", "tags": [ "Platform" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "externalBusinessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/platform/metrics": { "post": { "summary": "Report platform metrics for the Control Centre", "tags": [ "Platform" ], "description": "Idempotent per (key, periodStart, periodEnd). Only reported metrics are shown; nothing is estimated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metrics": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_.]{1,60}$" }, "value": { "anyOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" } ] }, "unit": { "type": "string", "maxLength": 20 }, "periodStart": {}, "periodEnd": {}, "dimensions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "key", "value", "periodStart", "periodEnd" ] } } }, "required": [ "metrics" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/overview": { "get": { "summary": "Ecosystem overview", "tags": [ "Control Centre" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/finance": { "get": { "summary": "TechTur revenue vs merchant GMV", "tags": [ "Control Centre" ], "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/platforms": { "get": { "tags": [ "Control Centre" ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Control Centre" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9-]{2,40}$" }, "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "kind": { "default": "TECHTUR", "type": "string", "enum": [ "TECHTUR", "THIRD_PARTY" ] }, "status": { "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "PLANNED", "SUSPENDED" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "websiteUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "adminUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "healthUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "capabilities": { "default": [], "type": "array", "items": { "type": "string", "maxLength": 40 } } }, "required": [ "slug", "name" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/platforms/{id}": { "patch": { "tags": [ "Control Centre" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9-]{2,40}$" }, "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "kind": { "default": "TECHTUR", "type": "string", "enum": [ "TECHTUR", "THIRD_PARTY" ] }, "status": { "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "PLANNED", "SUSPENDED" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "websiteUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "adminUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "healthUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "capabilities": { "default": [], "type": "array", "items": { "type": "string", "maxLength": 40 } } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "get": { "summary": "Platform management view", "tags": [ "Control Centre" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/businesses": { "get": { "tags": [ "Control Centre" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "q", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "platformId", "required": false }, { "schema": { "default": "LIVE", "type": "string", "enum": [ "LIVE", "SANDBOX" ] }, "in": "query", "name": "environment", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/businesses/{id}": { "get": { "summary": "One business, aggregated (support access is audited)", "tags": [ "Control Centre" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/businesses/{id}/status": { "post": { "tags": [ "Control Centre" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "SUSPENDED" ] }, "reason": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "status", "reason" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/applications": { "get": { "tags": [ "Control Centre" ], "parameters": [ { "schema": { "type": "string", "enum": [ "PENDING_REVIEW", "ACTIVE", "SUSPENDED", "REVOKED" ] }, "in": "query", "name": "status", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/applications/{id}/review": { "post": { "summary": "Approve or suspend an application and set its scopes", "tags": [ "Control Centre" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "suspend" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "platformId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "decision" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/integrations/health": { "get": { "summary": "Integration diagnostics across the ecosystem", "tags": [ "Control Centre" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/audit": { "get": { "tags": [ "Control Centre" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "action", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "businessId", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/users/{id}/platform-role": { "post": { "tags": [ "Control Centre" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "anyOf": [ { "type": "string", "enum": [ "SUPER_ADMIN", "PLATFORM_ADMIN", "SUPPORT_ADMIN", "FINANCE_ADMIN", "OPERATIONS_ADMIN", "INTEGRATION_ADMIN" ] }, { "type": "null" } ] } }, "required": [ "role" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/admin/users": { "get": { "tags": [ "Control Centre" ], "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "q", "required": false }, { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "platformOnly", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/devices": { "get": { "tags": [ "Hardware" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Register a device. A bridge gets a one-time pairing code.", "tags": [ "Hardware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "BRIDGE", "RECEIPT_PRINTER", "KITCHEN_PRINTER", "LABEL_PRINTER", "CASH_DRAWER", "SCANNER", "CARD_TERMINAL", "CUSTOMER_DISPLAY", "SCALE" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "registerId": { "type": "string", "minLength": 1, "maxLength": 64 }, "bridgeId": { "type": "string", "minLength": 1, "maxLength": 64 }, "config": { "default": {}, "type": "object", "properties": { "transport": { "type": "string", "enum": [ "network", "usb", "bluetooth", "browser", "keyboard" ] }, "host": { "type": "string", "maxLength": 255 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "devicePath": { "type": "string", "maxLength": 255 }, "paperWidth": { "type": "string", "enum": [ "58", "80" ] }, "codepage": { "type": "string", "maxLength": 20 }, "drawerPin": { "type": "string", "enum": [ "2", "5" ] }, "provider": { "type": "string", "maxLength": 40 } }, "additionalProperties": {} } }, "required": [ "kind", "name" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/devices/{id}": { "patch": { "tags": [ "Hardware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "registerId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "bridgeId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "config": { "type": "object", "properties": { "transport": { "type": "string", "enum": [ "network", "usb", "bluetooth", "browser", "keyboard" ] }, "host": { "type": "string", "maxLength": 255 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "devicePath": { "type": "string", "maxLength": 255 }, "paperWidth": { "type": "string", "enum": [ "58", "80" ] }, "codepage": { "type": "string", "maxLength": 20 }, "drawerPin": { "type": "string", "enum": [ "2", "5" ] }, "provider": { "type": "string", "maxLength": 40 } }, "additionalProperties": {} }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/devices/{id}/print": { "post": { "summary": "Queue a receipt, kitchen ticket or test page for a printer behind a bridge", "tags": [ "Hardware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "receipt", "kitchen", "test", "drawer" ] }, "saleId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "kind" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/devices/pair": { "post": { "summary": "Bridge: exchange a pairing code for a device token", "tags": [ "Hardware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pairingCode": { "type": "string", "minLength": 6, "maxLength": 40 }, "agentVersion": { "type": "string", "maxLength": 40 }, "hostname": { "type": "string", "maxLength": 120 } }, "required": [ "pairingCode" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/devices/heartbeat": { "post": { "summary": "Bridge: report status and collect print jobs", "tags": [ "Hardware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "default": [], "type": "array", "items": { "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1, "maxLength": 64 }, "ok": { "type": "boolean" }, "error": { "type": "string", "maxLength": 300 } }, "required": [ "deviceId", "ok" ] } } } } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/devices/jobs/{id}/result": { "post": { "tags": [ "Hardware" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PRINTED", "FAILED" ] }, "error": { "type": "string", "maxLength": 300 } }, "required": [ "status" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/notifications": { "get": { "tags": [ "Notifications" ], "parameters": [ { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "unreadOnly", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/notifications/read": { "post": { "tags": [ "Notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "all": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/imports/{kind}/template": { "get": { "tags": [ "Data" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "enum": [ "products", "customers", "suppliers", "stock" ] }, "in": "path", "name": "kind", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/imports/{kind}/preview": { "post": { "summary": "Validate an import and show what it would change", "tags": [ "Data" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "minLength": 1, "maxLength": 5000000 } }, "required": [ "csv" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "enum": [ "products", "customers", "suppliers", "stock" ] }, "in": "path", "name": "kind", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/imports/{kind}/commit": { "post": { "summary": "Apply a validated import (all or nothing)", "tags": [ "Data" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "minLength": 1, "maxLength": 5000000 }, "locationId": { "type": "string" } }, "required": [ "csv" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "enum": [ "products", "customers", "suppliers", "stock" ] }, "in": "path", "name": "kind", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/exports/{kind}": { "get": { "summary": "Download a CSV export", "tags": [ "Data" ], "parameters": [ { "schema": {}, "in": "query", "name": "from", "required": false }, { "schema": {}, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true }, { "schema": { "type": "string", "enum": [ "products", "customers", "suppliers", "stock", "sales", "sale_lines", "payments", "journal_lines", "audit" ] }, "in": "path", "name": "kind", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/businesses/{businessId}/exports/full": { "get": { "summary": "Complete business data export (JSON) for portability and backup", "tags": [ "Data" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "businessId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/support/contact": { "post": { "summary": "Send a message to TechTur support", "tags": [ "Support" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "topic": { "default": "general", "type": "string", "enum": [ "general", "billing", "technical", "integrations", "hardware", "account" ] }, "subject": { "type": "string", "minLength": 3, "maxLength": 150 }, "message": { "type": "string", "minLength": 10, "maxLength": 5000 }, "businessId": { "type": "string", "maxLength": 64 }, "website": { "type": "string", "maxLength": 0 } }, "required": [ "name", "email", "subject", "message" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/providers": { "get": { "summary": "Sign-in methods available", "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/google/start": { "get": { "summary": "Begin Google sign-in (browser redirect)", "tags": [ "Auth" ], "parameters": [ { "schema": { "default": "login", "type": "string", "enum": [ "login", "link" ] }, "in": "query", "name": "intent", "required": false }, { "schema": { "type": "string", "maxLength": 300 }, "in": "query", "name": "next", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/google/callback": { "get": { "tags": [ "Auth" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "code", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "state", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "error", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/v1/auth/google/unlink": { "post": { "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/oauth/authorize": { "get": { "summary": "Validate an authorization request (used by the consent screen)", "tags": [ "OAuth" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "client_id", "required": true }, { "schema": { "type": "string", "format": "uri" }, "in": "query", "name": "redirect_uri", "required": true }, { "schema": { "type": "string", "enum": [ "code" ] }, "in": "query", "name": "response_type", "required": true }, { "schema": { "default": "", "type": "string" }, "in": "query", "name": "scope", "required": false }, { "schema": { "type": "string", "maxLength": 500 }, "in": "query", "name": "state", "required": false }, { "schema": { "type": "string", "minLength": 43, "maxLength": 128 }, "in": "query", "name": "code_challenge", "required": true }, { "schema": { "type": "string", "enum": [ "S256" ] }, "in": "query", "name": "code_challenge_method", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "summary": "Grant access for one business and receive the redirect", "tags": [ "OAuth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "response_type": { "type": "string", "enum": [ "code" ] }, "scope": { "default": "", "type": "string" }, "state": { "type": "string", "maxLength": 500 }, "code_challenge": { "type": "string", "minLength": 43, "maxLength": 128 }, "code_challenge_method": { "type": "string", "enum": [ "S256" ] }, "businessId": { "type": "string" }, "decision": { "type": "string", "enum": [ "allow", "deny" ] } }, "required": [ "client_id", "redirect_uri", "response_type", "code_challenge", "code_challenge_method", "businessId", "decision" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/oauth/token": { "post": { "summary": "Exchange a code, refresh a token, or use client credentials", "tags": [ "OAuth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token", "client_credentials" ] }, "code": { "type": "string" }, "redirect_uri": { "type": "string" }, "code_verifier": { "type": "string" }, "refresh_token": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "grant_type" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/oauth/revoke": { "post": { "summary": "Revoke an access or refresh token (RFC 7009)", "tags": [ "OAuth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Default Response" } } } } }, "servers": [ { "url": "https://pos.techtursolutions.com" }, { "url": "http://localhost:4600" } ], "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ] }