{ "swagger": "2.0", "info": { "description": "High-performance REST API for e-commerce operations including orders, products, SKUs, and staging management", "title": "Linkit API v1", "termsOfService": "https://linkit.works/terms/", "contact": { "name": "API Support", "url": "https://www.linkit.works/support", "email": "info@linkit.works" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.0" }, "host": "https://linkit.works", "basePath": "/api/v1", "paths": { "/api/v1/apps": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get list of available installed apps for the authenticated organization", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Integrations" ], "summary": "List apps", "responses": { "200": { "description": "List of integrations", "schema": { "$ref": "#/definitions/v1.IntegrationListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/branches": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve a paginated list of branches with optional filtering and proximity search", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Branches" ], "summary": "List branches", "parameters": [ { "type": "string", "example": "\"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "minimum": 1, "type": "integer", "default": 1, "example": 1, "description": "Page number", "name": "page", "in": "query" }, { "maximum": 100, "minimum": 1, "type": "integer", "default": 20, "example": 20, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "default": "\"-created\"", "example": "\"-created\"", "description": "Sort order (prefix with - for desc)", "name": "sort", "in": "query" }, { "type": "boolean", "example": true, "description": "Filter by active status", "name": "active", "in": "query" }, { "enum": [ "New", "Pending", "Verifying", "Published", "Rejected", "Terminated" ], "type": "string", "example": "\"Published\"", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "string", "example": "\"Dubai\"", "description": "Search in branch names", "name": "search", "in": "query" }, { "maximum": 90, "minimum": -90, "type": "number", "example": 25.2048, "description": "Proximity search center latitude", "name": "near_lat", "in": "query" }, { "maximum": 180, "minimum": -180, "type": "number", "example": 55.2708, "description": "Proximity search center longitude", "name": "near_lon", "in": "query" }, { "maximum": 100, "minimum": 0.1, "type": "number", "default": 10, "example": 5, "description": "Search radius in kilometers", "name": "radius_km", "in": "query" } ], "responses": { "200": { "description": "Successful response with branch list", "schema": { "$ref": "#/definitions/v1.BranchListResponse" } }, "400": { "description": "Invalid request parameters", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new branch with validation and duplicate checking. Supports multipart/form-data (with files) and application/json.", "consumes": [ "application/json", "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "Branches" ], "summary": "Create new branch", "parameters": [ { "type": "string", "example": "\"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"BR-2024-001\"", "description": "Internal branch identifier", "name": "iv_id", "in": "formData", "required": true }, { "type": "string", "example": "\"فرع دبي\"", "description": "Arabic name", "name": "name_ar", "in": "formData", "required": true }, { "type": "string", "example": "\"Dubai Branch\"", "description": "English name", "name": "name_en", "in": "formData", "required": true }, { "type": "string", "example": "\"dubai@example.com\"", "description": "Contact email", "name": "email", "in": "formData" }, { "type": "boolean", "default": true, "example": true, "description": "Active status", "name": "active", "in": "formData", "required": true }, { "enum": [ "New", "Pending", "Verifying", "Published", "Rejected", "Terminated" ], "type": "string", "default": "\"New\"", "example": "\"New\"", "description": "Branch status", "name": "status", "in": "formData" }, { "type": "string", "example": "\"{\\\"lat\\\": 25.2048, \\\"lon\\\": 55.2708}\"", "description": "Geographic location as JSON", "name": "location", "in": "formData", "required": true }, { "type": "string", "example": "\"ChIJrTLr-GyuEmsRBfy61i59si0\"", "description": "Apple Maps place ID", "name": "apple_maps_id", "in": "formData" }, { "type": "string", "example": "\"ChIJN1t_tDeuEmsRUsoyG83frY4\"", "description": "Google Maps place ID", "name": "google_maps_id", "in": "formData" }, { "type": "string", "example": "\"[{\\\"WeekDay\\\":\\\"Monday\\\",\\\"OpenHour\\\":9,\\\"OpenMinute\\\":0,\\\"CloseHour\\\":17,\\\"CloseMinute\\\":0}]\"", "description": "Working hours schedule as JSON. Supports weekday-object or canonical multi-period array.", "name": "working_hours", "in": "formData" }, { "type": "file", "description": "Hero image file (jpg, jpeg, png, webp, gif - max 10MB)", "name": "hero_image", "in": "formData" }, { "type": "file", "description": "Banner image file (jpg, jpeg, png, webp, gif - max 10MB)", "name": "banner_image", "in": "formData" }, { "type": "file", "description": "Photos (multiple files allowed, max 20 files, each max 10MB)", "name": "photos", "in": "formData" } ], "responses": { "201": { "description": "Branch created successfully", "schema": { "$ref": "#/definitions/v1.BranchCreateResponse" } }, "400": { "description": "Validation error or wrong content type", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "409": { "description": "Branch already exists", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } } } } }, "/api/v1/branches/bulk": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create, update, or upsert multiple branches in a single request. Max 1000 branches per request.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Branches" ], "summary": "Bulk branch operations", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Bulk operation request", "name": "bulk", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.BranchBulkRequest" } } ], "responses": { "200": { "description": "Bulk operation completed", "schema": { "$ref": "#/definitions/v1.BranchBulkResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "413": { "description": "Payload too large", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/branches/{ivId}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve detailed information about a specific branch", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Branches" ], "summary": "Get branch by ID", "parameters": [ { "type": "string", "example": "\"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"BR-2024-001\"", "description": "Internal branch identifier", "name": "ivId", "in": "path", "required": true } ], "responses": { "200": { "description": "Branch details", "schema": { "$ref": "#/definitions/v1.BranchResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "404": { "description": "Branch not found", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update an existing branch with partial updates support. Supports multipart/form-data (with files) and application/json.", "consumes": [ "application/json", "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "Branches" ], "summary": "Update branch", "parameters": [ { "type": "string", "example": "\"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"BR-2024-001\"", "description": "Internal branch identifier", "name": "ivId", "in": "path", "required": true }, { "type": "string", "example": "\"فرع دبي الرئيسي\"", "description": "Arabic name", "name": "name_ar", "in": "formData" }, { "type": "string", "example": "\"Dubai Main Branch\"", "description": "English name", "name": "name_en", "in": "formData" }, { "type": "string", "example": "\"main.dubai@example.com\"", "description": "Contact email", "name": "email", "in": "formData" }, { "type": "boolean", "example": true, "description": "Active status", "name": "active", "in": "formData" }, { "enum": [ "New", "Pending", "Verifying", "Published", "Rejected", "Terminated" ], "type": "string", "example": "\"Published\"", "description": "Branch status", "name": "status", "in": "formData" }, { "type": "string", "example": "\"{\\\"lat\\\": 25.2048, \\\"lon\\\": 55.2708}\"", "description": "Geographic location as JSON", "name": "location", "in": "formData" }, { "type": "string", "example": "\"ChIJrTLr-GyuEmsRBfy61i59si0\"", "description": "Apple Maps place ID", "name": "apple_maps_id", "in": "formData" }, { "type": "string", "example": "\"ChIJN1t_tDeuEmsRUsoyG83frY4\"", "description": "Google Maps place ID", "name": "google_maps_id", "in": "formData" }, { "type": "string", "example": "\"[{\\\"WeekDay\\\":\\\"Friday\\\",\\\"OpenHour\\\":12,\\\"OpenMinute\\\":30,\\\"CloseHour\\\":16,\\\"CloseMinute\\\":45},{\\\"WeekDay\\\":\\\"Friday\\\",\\\"OpenHour\\\":21,\\\"OpenMinute\\\":0,\\\"CloseHour\\\":1,\\\"CloseMinute\\\":45}]\"", "description": "Working hours schedule as JSON. Supports weekday-object or canonical multi-period array.", "name": "working_hours", "in": "formData" }, { "type": "file", "description": "Hero image file (jpg, jpeg, png, webp, gif - max 10MB)", "name": "hero_image", "in": "formData" }, { "type": "file", "description": "Banner image file (jpg, jpeg, png, webp, gif - max 10MB)", "name": "banner_image", "in": "formData" }, { "type": "file", "description": "Photos (multiple files allowed, max 20 files, each max 10MB)", "name": "photos", "in": "formData" } ], "responses": { "200": { "description": "Branch updated successfully", "schema": { "$ref": "#/definitions/v1.BranchUpdateResponse" } }, "400": { "description": "Validation error or wrong content type", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "404": { "description": "Branch not found", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently delete a branch from the runtime", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Branches" ], "summary": "Delete branch", "parameters": [ { "type": "string", "example": "\"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"BR-2024-001\"", "description": "Internal branch identifier", "name": "ivId", "in": "path", "required": true } ], "responses": { "204": { "description": "Branch deleted successfully" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "404": { "description": "Branch not found", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } } } } }, "/api/v1/branches/{ivId}/working-hours": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Update branch working hours using either weekday-object payloads or canonical multi-period arrays.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Branches" ], "summary": "Update branch working hours", "parameters": [ { "type": "string", "example": "\"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"BR-2024-001\"", "description": "Internal branch identifier", "name": "ivId", "in": "path", "required": true }, { "description": "Working hours update payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.BranchWorkingHoursRequest" } } ], "responses": { "200": { "description": "Working hours updated successfully", "schema": { "$ref": "#/definitions/v1.BranchWorkingHoursResponse" } }, "400": { "description": "Validation error", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "404": { "description": "Branch not found", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.DetailedErrorResponse" } } } } }, "/api/v1/brands": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get paginated list of brands with comprehensive filtering options", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Brands" ], "summary": "List brands", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "maximum": 100, "minimum": 1, "type": "integer", "default": 20, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Search in brand names", "name": "search", "in": "query" }, { "type": "boolean", "description": "Filter brands with/without products", "name": "has_products", "in": "query" } ], "responses": { "200": { "description": "Brands list", "schema": { "$ref": "#/definitions/v1.BrandListResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new brand in the catalog with full validation and duplicate checking", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Brands" ], "summary": "Create new brand", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Brand details", "name": "brand", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.BrandRequest" } } ], "responses": { "201": { "description": "Brand created successfully", "schema": { "$ref": "#/definitions/v1.BrandCreateResponse" } }, "400": { "description": "Bad request - validation failed", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Conflict - duplicate brand code", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Unprocessable entity", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/brands/bulk": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create, update, or upsert multiple brands in a single request. Max 1000 brands per request.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Brands" ], "summary": "Bulk brand operations", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Bulk operation request", "name": "bulk", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.BrandBulkRequest" } } ], "responses": { "200": { "description": "Bulk operation completed", "schema": { "$ref": "#/definitions/v1.BrandBulkResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "413": { "description": "Payload too large", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/brands/code/{brandCode}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve detailed brand information by brand code", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Brands" ], "summary": "Get brand by code", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"BR001\"", "description": "Brand code", "name": "brandCode", "in": "path", "required": true } ], "responses": { "200": { "description": "Brand details", "schema": { "$ref": "#/definitions/v1.BrandResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Brand not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update existing brand details by brand code", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Brands" ], "summary": "Update brand", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"BR001\"", "description": "Brand code", "name": "brandCode", "in": "path", "required": true }, { "description": "Updated brand details", "name": "brand", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.BrandRequest" } } ], "responses": { "200": { "description": "Brand updated successfully", "schema": { "$ref": "#/definitions/v1.BrandUpdateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Brand not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Unprocessable entity", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete a brand by brand code (fails if brand has associated products)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Brands" ], "summary": "Delete brand", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"BR001\"", "description": "Brand code", "name": "brandCode", "in": "path", "required": true }, { "type": "boolean", "default": false, "description": "Force delete even if brand has products", "name": "force", "in": "query" } ], "responses": { "204": { "description": "Brand deleted successfully" }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Brand not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Conflict - brand has products", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/brands/code/{brandCode}/products": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update the list of products associated with a brand", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Brands" ], "summary": "Update brand products", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"BR001\"", "description": "Brand code", "name": "brandCode", "in": "path", "required": true }, { "description": "Product update request", "name": "products", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.BrandProductsUpdateRequest" } } ], "responses": { "200": { "description": "Products updated successfully", "schema": { "$ref": "#/definitions/v1.BrandUpdateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Brand not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/categories": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get paginated list of categories with filtering", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Categories" ], "summary": "List categories", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "maximum": 100, "minimum": 1, "type": "integer", "default": 20, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Filter by parent code (empty for root)", "name": "parent", "in": "query" }, { "type": "string", "description": "Search in category names", "name": "search", "in": "query" }, { "type": "boolean", "description": "Filter categories with/without products", "name": "has_products", "in": "query" }, { "type": "integer", "description": "Filter by specific depth level", "name": "depth", "in": "query" } ], "responses": { "200": { "description": "Categories list", "schema": { "$ref": "#/definitions/v1.CategoryListResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new category with hierarchical support", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Categories" ], "summary": "Create new category", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Category details", "name": "category", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.CategoryRequest" } } ], "responses": { "201": { "description": "Category created successfully", "schema": { "$ref": "#/definitions/v1.CategoryCreateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Conflict - duplicate code", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Unprocessable entity", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/categories/code/{code}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve detailed category information by code", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Categories" ], "summary": "Get category by code", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"CAT001\"", "description": "Category code", "name": "code", "in": "path", "required": true } ], "responses": { "200": { "description": "Category details", "schema": { "$ref": "#/definitions/v1.CategoryResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Category not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update existing category details by code", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Categories" ], "summary": "Update category", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"CAT001\"", "description": "Category code", "name": "code", "in": "path", "required": true }, { "description": "Updated category details", "name": "category", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.CategoryRequest" } } ], "responses": { "200": { "description": "Category updated successfully", "schema": { "$ref": "#/definitions/v1.CategoryUpdateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Category not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Unprocessable entity", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete a category (fails if category has children or products)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Categories" ], "summary": "Delete category", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"CAT001\"", "description": "Category code", "name": "code", "in": "path", "required": true }, { "type": "boolean", "default": false, "description": "Force delete even if it has children/products", "name": "force", "in": "query" }, { "type": "boolean", "default": false, "description": "Delete all child categories", "name": "cascade", "in": "query" } ], "responses": { "204": { "description": "Category deleted successfully" }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Category not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Conflict - has children/products", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/categories/code/{code}/move": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Move category to a new parent in the hierarchy", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Categories" ], "summary": "Move category", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"CAT001\"", "description": "Category code", "name": "code", "in": "path", "required": true }, { "description": "Move request", "name": "move", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.CategoryMoveRequest" } } ], "responses": { "200": { "description": "Category moved successfully", "schema": { "$ref": "#/definitions/v1.CategoryUpdateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Category not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/categories/code/{code}/products": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update the list of products associated with a category", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Categories" ], "summary": "Update category products", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"CAT001\"", "description": "Category code", "name": "code", "in": "path", "required": true }, { "description": "Product update request", "name": "products", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.CategoryProductsUpdateRequest" } } ], "responses": { "200": { "description": "Products updated successfully", "schema": { "$ref": "#/definitions/v1.CategoryUpdateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Category not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/categories/tree": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve full or partial category hierarchy tree", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Categories" ], "summary": "Get category tree", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Root category code (empty for all roots)", "name": "root", "in": "query" }, { "type": "integer", "default": 10, "description": "Maximum depth to retrieve", "name": "max_depth", "in": "query" } ], "responses": { "200": { "description": "Category tree", "schema": { "type": "array", "items": { "$ref": "#/definitions/v1.CategoryTreeResponse" } } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/customer-groups": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves a paginated list of customer groups sorted by creation date (newest first)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customer Groups" ], "summary": "List all customer groups", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "integer", "description": "Page number for pagination (default: 1, min: 1)", "name": "page", "in": "query" }, { "type": "integer", "description": "Number of items per page (default: 50, max: 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paginated list of customer groups with metadata", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error during fetch", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new customer group for organizing customers. Groups can be used for segmentation and bulk operations.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customer Groups" ], "summary": "Create a new customer group", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "description": "Group details. Name is required and must be unique when combined with description.", "name": "group", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.CustomerGroupRequest" } } ], "responses": { "201": { "description": "Customer group successfully created", "schema": { "$ref": "#/definitions/v1.CustomerGroupResponse" } }, "400": { "description": "Invalid request format", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Group with same name and description already exists", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Validation error - name is required", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during creation", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/customer-groups/{id}": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Updates an existing customer group's name and description", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customer Groups" ], "summary": "Update customer group details", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Customer group ID to update (UUID format)", "name": "id", "in": "path", "required": true }, { "description": "Updated group details. Name is required.", "name": "group", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.CustomerGroupRequest" } } ], "responses": { "200": { "description": "Customer group successfully updated", "schema": { "$ref": "#/definitions/v1.CustomerGroupResponse" } }, "400": { "description": "Invalid request format or missing group ID", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Customer group not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Update would create duplicate group", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Validation error - name is required", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during update", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently deletes a customer group. Note: This does not delete customers associated with the group.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customer Groups" ], "summary": "Delete a customer group", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Customer group ID to delete (UUID format)", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "Customer group successfully deleted" }, "400": { "description": "Missing group ID", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Customer group not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during deletion", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/customers": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves a paginated list of customers for the organization. Supports filtering by status, type, and search across multiple fields.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customers" ], "summary": "List customers with pagination and filtering", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID to filter customers", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "integer", "description": "Page number for pagination (default: 1, min: 1)", "name": "page", "in": "query" }, { "type": "integer", "description": "Number of items per page (default: 50, max: 100)", "name": "limit", "in": "query" }, { "type": "string", "description": "Filter by customer status (active, inactive, pending)", "name": "status", "in": "query" }, { "type": "string", "description": "Filter by customer type (individual, corporate, vip)", "name": "type", "in": "query" }, { "type": "string", "description": "Search across first_name, last_name, email, and phone fields (case-insensitive partial match)", "name": "search", "in": "query" } ], "responses": { "200": { "description": "Paginated list of customers with metadata including total count and pagination info", "schema": { "$ref": "#/definitions/v1.CustomerListResponse" } }, "400": { "description": "Invalid request parameters or missing organization ID", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during query execution", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new customer record with the provided details. Email addresses are normalized to lowercase and phone numbers are normalized to contain only digits (with optional leading +).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customers" ], "summary": "Create a new customer", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID to associate the customer with", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Customer details to create. All fields are trimmed of whitespace. Email must be valid format. Phone must have at least 10 digits. Birthdate must be in YYYY-MM-DD format. Status must be one of: active, inactive, pending. Type must be one of: individual, corporate, vip. Gender (if provided) must be one of: male, female, other.", "name": "customer", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.CustomerRequest" } } ], "responses": { "201": { "description": "Customer successfully created with normalized email and phone", "schema": { "$ref": "#/definitions/v1.CustomerResponse" } }, "400": { "description": "Invalid request format or missing organization ID", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Customer with same email/phone already exists in the organization", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Validation error - check field requirements and enum values", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during customer creation", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/customers/lookup": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Provides a unified lookup endpoint to find a customer by either email address or phone number. Email lookup is case-insensitive. Phone lookup normalizes the input to digits only.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customers" ], "summary": "Lookup customer by email or phone", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID to search within", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Email address to search for (case-insensitive, normalized)", "name": "email", "in": "query" }, { "type": "string", "description": "Phone number to search for (normalized to digits only with optional leading +)", "name": "phone", "in": "query" } ], "responses": { "200": { "description": "Customer found matching the search criteria", "schema": { "$ref": "#/definitions/v1.CustomerResponse" } }, "400": { "description": "Missing both email and phone parameters, or missing organization ID", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "No customer found with the provided email or phone", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/customers/search": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Performs complex searches across customer records with multiple filter criteria. All string comparisons are case-insensitive partial matches except for exact email and phone matching.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customers" ], "summary": "Advanced customer search", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID to search within", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Search criteria object. Query field searches across multiple fields. Individual field filters can be combined. Date filters use YYYY-MM-DD format. Status and Type arrays allow multiple value filtering.", "name": "search", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.CustomerSearchRequest" } } ], "responses": { "200": { "description": "Search results with pagination metadata and applied search criteria in meta field", "schema": { "$ref": "#/definitions/v1.CustomerListResponse" } }, "400": { "description": "Invalid request format or missing organization ID", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during search execution", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/customers/{customerId}/addresses": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves all addresses associated with a customer. Addresses are sorted with default address first, then by creation date (newest first).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customer Addresses" ], "summary": "List all addresses for a customer", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID for verification", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Customer ID to get addresses for (UUID format)", "name": "customerId", "in": "path", "required": true } ], "responses": { "200": { "description": "List of customer addresses (may be empty array)", "schema": { "type": "array", "items": { "$ref": "#/definitions/v1.AddressResponse" } } }, "400": { "description": "Missing customer ID or organization ID", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Customer not found or doesn't belong to the organization", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during fetch", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new address for a customer. If is_default is true, all other addresses for the customer will have is_default set to false.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customer Addresses" ], "summary": "Add a new address to customer", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID for verification", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Customer ID to add address to (UUID format)", "name": "customerId", "in": "path", "required": true }, { "description": "Address details. Country must be 2-letter ISO code (automatically converted to uppercase). Label is a friendly name for the address.", "name": "address", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.AddressRequest" } } ], "responses": { "201": { "description": "Address successfully created", "schema": { "$ref": "#/definitions/v1.AddressResponse" } }, "400": { "description": "Invalid request format or missing IDs", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Customer not found or doesn't belong to the organization", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Address with same details already exists", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Validation error - check field requirements", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during address creation", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/customers/{customerId}/addresses/{addressId}": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Updates a customer's address. If is_default is changed to true, all other addresses will have is_default set to false.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customer Addresses" ], "summary": "Update an existing address", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID for verification", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Customer ID the address belongs to (UUID format)", "name": "customerId", "in": "path", "required": true }, { "type": "string", "description": "Address ID to update (UUID format)", "name": "addressId", "in": "path", "required": true }, { "description": "Updated address details. All fields required (full replacement). Country automatically converted to uppercase.", "name": "address", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.AddressRequest" } } ], "responses": { "200": { "description": "Address successfully updated", "schema": { "$ref": "#/definitions/v1.AddressResponse" } }, "400": { "description": "Invalid request format or missing IDs", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Customer or address not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Update would create duplicate address", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Validation error - check field requirements", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during update", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently deletes an address from a customer's address list", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customer Addresses" ], "summary": "Delete a customer address", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID for verification", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Customer ID the address belongs to (UUID format)", "name": "customerId", "in": "path", "required": true }, { "type": "string", "description": "Address ID to delete (UUID format)", "name": "addressId", "in": "path", "required": true } ], "responses": { "204": { "description": "Address successfully deleted" }, "400": { "description": "Missing required IDs", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Customer or address not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during deletion", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/customers/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves detailed information about a specific customer by their ID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customers" ], "summary": "Get customer by ID", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID the customer belongs to", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Customer ID (UUID format)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Customer details retrieved successfully", "schema": { "$ref": "#/definitions/v1.CustomerResponse" } }, "400": { "description": "Invalid or missing customer ID or organization ID", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Customer not found or doesn't belong to the organization", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Updates an existing customer's information. All fields must be provided (full replacement). Email and phone are normalized before saving.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customers" ], "summary": "Update customer details", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID the customer belongs to", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Customer ID to update (UUID format)", "name": "id", "in": "path", "required": true }, { "description": "Updated customer details. All fields are required as this performs a full replacement. Same validation rules apply as creation.", "name": "customer", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.CustomerRequest" } } ], "responses": { "200": { "description": "Customer successfully updated with normalized data", "schema": { "$ref": "#/definitions/v1.CustomerResponse" } }, "400": { "description": "Invalid request format or missing required IDs", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Customer not found or doesn't belong to the organization", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Update would create duplicate (email/phone already exists for another customer)", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Validation error - check field requirements and enum values", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during update", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently deletes a customer and all their associated addresses. This operation is performed in a transaction to ensure data consistency.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Customers" ], "summary": "Delete customer and all associated data", "parameters": [ { "type": "string", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID the customer belongs to", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Customer ID to delete (UUID format)", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "Customer and all associated addresses successfully deleted" }, "400": { "description": "Missing customer ID or organization ID", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Customer not found or doesn't belong to the organization", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error during deletion", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/docs": { "get": { "description": "Interactive API documentation interface", "produces": [ "text/html" ], "tags": [ "Documentation" ], "summary": "Swagger UI", "responses": { "200": { "description": "HTML page", "schema": { "type": "string" } } } } }, "/api/v1/docs/info": { "get": { "description": "Returns metadata about the API documentation", "produces": [ "application/json" ], "tags": [ "Documentation" ], "summary": "API documentation info", "responses": { "200": { "description": "Documentation metadata", "schema": { "$ref": "#/definitions/v1.specMetadata" } } } } }, "/api/v1/docs/swagger.json": { "get": { "description": "Returns the OpenAPI/Swagger specification in JSON format", "produces": [ "application/json" ], "tags": [ "Documentation" ], "summary": "Get Swagger specification", "responses": { "200": { "description": "OpenAPI specification", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Specification not available", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/email-marketing/{slug}/preview": { "get": { "produces": [ "application/json" ], "tags": [ "Email marketing" ], "summary": "Preview offer marketing email HTML", "parameters": [ { "type": "string", "description": "App slug", "name": "slug", "in": "path", "required": true }, { "type": "string", "description": "top_impact | all_active | pdf_manual", "name": "content_mode", "in": "query" }, { "type": "integer", "description": "Top N offers when content_mode=top_impact", "name": "top_n", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/emailmarketing.PreviewResult" } } } } }, "/api/v1/email-marketing/{slug}/send": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Email marketing" ], "summary": "Send offer marketing email", "parameters": [ { "type": "string", "description": "App slug", "name": "slug", "in": "path", "required": true }, { "description": "Payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.EmailMarketingSendRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/emailmarketing.SendResult" } } } } }, "/api/v1/generics": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get paginated list of generic medicines with filtering", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Generics" ], "summary": "List generic medicines", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "maximum": 100, "minimum": 1, "type": "integer", "default": 25, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Search in generic names", "name": "search", "in": "query" }, { "type": "boolean", "description": "Filter generics with/without products", "name": "has_products", "in": "query" } ], "responses": { "200": { "description": "Generics list", "schema": { "$ref": "#/definitions/v1.GenericListResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new generic medicine with validation for global name uniqueness", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Generics" ], "summary": "Create new generic medicine", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Generic medicine details", "name": "generic", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.GenericRequest" } } ], "responses": { "201": { "description": "Generic created successfully", "schema": { "$ref": "#/definitions/v1.GenericCreateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Conflict - duplicate code or name", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Unprocessable entity", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/generics/bulk": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create, update, or upsert multiple generics in a single request", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Generics" ], "summary": "Bulk generic operations", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Bulk operation request", "name": "bulk", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.GenericBulkRequest" } } ], "responses": { "200": { "description": "Bulk operation completed", "schema": { "$ref": "#/definitions/v1.GenericBulkResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "413": { "description": "Payload too large", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/generics/cache/clear": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Clear all cached generic data (admin only)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Generics" ], "summary": "Clear generic cache", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true } ], "responses": { "200": { "description": "Cache cleared", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/generics/code/{genericCode}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve detailed generic medicine information by code", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Generics" ], "summary": "Get generic medicine by code", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"GEN001\"", "description": "Generic code", "name": "genericCode", "in": "path", "required": true } ], "responses": { "200": { "description": "Generic details", "schema": { "$ref": "#/definitions/v1.GenericResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Generic not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update existing generic medicine details by code", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Generics" ], "summary": "Update generic medicine", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"GEN001\"", "description": "Generic code", "name": "genericCode", "in": "path", "required": true }, { "description": "Updated generic details", "name": "generic", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.GenericRequest" } } ], "responses": { "200": { "description": "Generic updated successfully", "schema": { "$ref": "#/definitions/v1.GenericUpdateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Generic not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Conflict - duplicate name", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Unprocessable entity", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete a generic medicine (fails if it has associated products)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Generics" ], "summary": "Delete generic medicine", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"GEN001\"", "description": "Generic code", "name": "genericCode", "in": "path", "required": true }, { "type": "boolean", "default": false, "description": "Force delete even if it has products", "name": "force", "in": "query" } ], "responses": { "204": { "description": "Generic deleted successfully" }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Generic not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Conflict - has products", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/generics/search": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Advanced search with fuzzy matching and filters", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Generics" ], "summary": "Search generic medicines", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Search query", "name": "query", "in": "body", "required": true, "schema": { "type": "object", "additionalProperties": true } } ], "responses": { "200": { "description": "Search results", "schema": { "$ref": "#/definitions/v1.GenericListResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/health": { "get": { "description": "Get basic health status of the API", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Health check", "responses": { "200": { "description": "API is healthy", "schema": { "$ref": "#/definitions/v1.HealthResponse" } } } } }, "/api/v1/health/system": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get detailed runtime health information including integration status", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "System health check", "responses": { "200": { "description": "System health details", "schema": { "$ref": "#/definitions/v1.SystemHealthResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "503": { "description": "System unhealthy", "schema": { "$ref": "#/definitions/v1.SystemHealthResponse" } } } } }, "/api/v1/integrations": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get list of available installed apps for the authenticated organization", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Integrations" ], "summary": "List apps", "responses": { "200": { "description": "List of integrations", "schema": { "$ref": "#/definitions/v1.IntegrationListResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/integrations/{orgId}/execute-batch": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Execute multiple integrations for an organization with bounded concurrency", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Integrations" ], "summary": "Execute multiple integrations", "parameters": [ { "type": "string", "description": "Organization ID", "name": "orgId", "in": "path", "required": true }, { "description": "Batch execution parameters", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.BatchExecuteRequest" } } ], "responses": { "200": { "description": "Batch execution results", "schema": { "$ref": "#/definitions/v1.BatchExecuteResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Batch execution failed", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/integrations/{orgId}/{slug}/config": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get configuration details for a specific integration", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Integrations" ], "summary": "Get integration config", "parameters": [ { "type": "string", "description": "Organization ID", "name": "orgId", "in": "path", "required": true }, { "type": "string", "description": "Integration slug", "name": "slug", "in": "path", "required": true } ], "responses": { "200": { "description": "Integration configuration", "schema": { "$ref": "#/definitions/v1.IntegrationConfigResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "404": { "description": "Integration not found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/integrations/{orgId}/{slug}/execute": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Execute a specific integration with optional parameters", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Integrations" ], "summary": "Execute integration", "parameters": [ { "type": "string", "description": "Organization ID", "name": "orgId", "in": "path", "required": true }, { "type": "string", "description": "Integration slug", "name": "slug", "in": "path", "required": true }, { "description": "Execution parameters", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/v1.IntegrationExecuteRequest" } } ], "responses": { "200": { "description": "Execution successful", "schema": { "$ref": "#/definitions/v1.IntegrationExecuteResponse" } }, "202": { "description": "Execution started (dry run)", "schema": { "$ref": "#/definitions/v1.IntegrationExecuteResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "404": { "description": "Integration not found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Execution failed", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/mcp": { "get": { "description": "Model Context Protocol (MCP) endpoint for AI assistant integration.\n\nThis endpoint implements the MCP Streamable HTTP transport, enabling AI assistants\n(Claude, Cursor, Windsurf, Gemini, etc.) to discover and call all Linkit API\noperations as MCP tools. The endpoint is **public** — no authentication required\nfor protocol communication. Individual tool calls to protected API endpoints\nrequire passing a Bearer token in the tool's `authorization` argument.\n\n**Available MCP Methods:**\n- `initialize` — Negotiate protocol version and capabilities\n- `tools/list` — List all semantic API tools (~10 domain-grouped tools)\n- `tools/call` — Execute an API operation (proxied to PocketBase)\n- `resources/list` — List API documentation resources\n- `resources/read` — Read swagger specs, API overview, tool catalog\n\n**Quick Setup (Claude Desktop):**\n```json\n{ \"mcpServers\": { \"linkit\": { \"url\": \"https://your-instance.com/api/v1/mcp\" } } }\n```\n\n**Supported Transports:** Streamable HTTP (stateless)\n\n**Protocol Version:** 2025-06-18", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MCP" ], "summary": "MCP Protocol Endpoint (Streamable HTTP)", "parameters": [ { "description": "JSON-RPC 2.0 request (POST)", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/mcpserver.MCPToolCallRequest" } }, { "type": "string", "default": "2025-06-18", "description": "MCP protocol version", "name": "Mcp-Protocol-Version", "in": "header" }, { "type": "string", "description": "Session ID for stateful connections (optional in stateless mode)", "name": "Mcp-Session-Id", "in": "header" } ], "responses": { "200": { "description": "Resources list response", "schema": { "$ref": "#/definitions/mcpserver.MCPResourceListResponse" } }, "400": { "description": "Invalid JSON-RPC request", "schema": { "$ref": "#/definitions/mcpserver.MCPErrorResponse" } }, "405": { "description": "Method not allowed", "schema": { "type": "string" } } } }, "post": { "description": "Model Context Protocol (MCP) endpoint for AI assistant integration.\n\nThis endpoint implements the MCP Streamable HTTP transport, enabling AI assistants\n(Claude, Cursor, Windsurf, Gemini, etc.) to discover and call all Linkit API\noperations as MCP tools. The endpoint is **public** — no authentication required\nfor protocol communication. Individual tool calls to protected API endpoints\nrequire passing a Bearer token in the tool's `authorization` argument.\n\n**Available MCP Methods:**\n- `initialize` — Negotiate protocol version and capabilities\n- `tools/list` — List all semantic API tools (~10 domain-grouped tools)\n- `tools/call` — Execute an API operation (proxied to PocketBase)\n- `resources/list` — List API documentation resources\n- `resources/read` — Read swagger specs, API overview, tool catalog\n\n**Quick Setup (Claude Desktop):**\n```json\n{ \"mcpServers\": { \"linkit\": { \"url\": \"https://your-instance.com/api/v1/mcp\" } } }\n```\n\n**Supported Transports:** Streamable HTTP (stateless)\n\n**Protocol Version:** 2025-06-18", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MCP" ], "summary": "MCP Protocol Endpoint (Streamable HTTP)", "parameters": [ { "description": "JSON-RPC 2.0 request (POST)", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/mcpserver.MCPToolCallRequest" } }, { "type": "string", "default": "2025-06-18", "description": "MCP protocol version", "name": "Mcp-Protocol-Version", "in": "header" }, { "type": "string", "description": "Session ID for stateful connections (optional in stateless mode)", "name": "Mcp-Session-Id", "in": "header" } ], "responses": { "200": { "description": "Resources list response", "schema": { "$ref": "#/definitions/mcpserver.MCPResourceListResponse" } }, "400": { "description": "Invalid JSON-RPC request", "schema": { "$ref": "#/definitions/mcpserver.MCPErrorResponse" } }, "405": { "description": "Method not allowed", "schema": { "type": "string" } } } }, "delete": { "description": "Model Context Protocol (MCP) endpoint for AI assistant integration.\n\nThis endpoint implements the MCP Streamable HTTP transport, enabling AI assistants\n(Claude, Cursor, Windsurf, Gemini, etc.) to discover and call all Linkit API\noperations as MCP tools. The endpoint is **public** — no authentication required\nfor protocol communication. Individual tool calls to protected API endpoints\nrequire passing a Bearer token in the tool's `authorization` argument.\n\n**Available MCP Methods:**\n- `initialize` — Negotiate protocol version and capabilities\n- `tools/list` — List all semantic API tools (~10 domain-grouped tools)\n- `tools/call` — Execute an API operation (proxied to PocketBase)\n- `resources/list` — List API documentation resources\n- `resources/read` — Read swagger specs, API overview, tool catalog\n\n**Quick Setup (Claude Desktop):**\n```json\n{ \"mcpServers\": { \"linkit\": { \"url\": \"https://your-instance.com/api/v1/mcp\" } } }\n```\n\n**Supported Transports:** Streamable HTTP (stateless)\n\n**Protocol Version:** 2025-06-18", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MCP" ], "summary": "MCP Protocol Endpoint (Streamable HTTP)", "parameters": [ { "description": "JSON-RPC 2.0 request (POST)", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/mcpserver.MCPToolCallRequest" } }, { "type": "string", "default": "2025-06-18", "description": "MCP protocol version", "name": "Mcp-Protocol-Version", "in": "header" }, { "type": "string", "description": "Session ID for stateful connections (optional in stateless mode)", "name": "Mcp-Session-Id", "in": "header" } ], "responses": { "200": { "description": "Resources list response", "schema": { "$ref": "#/definitions/mcpserver.MCPResourceListResponse" } }, "400": { "description": "Invalid JSON-RPC request", "schema": { "$ref": "#/definitions/mcpserver.MCPErrorResponse" } }, "405": { "description": "Method not allowed", "schema": { "type": "string" } } } } }, "/api/v1/offers": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get paginated offers for the authenticated organization with filtering and sorting.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Offers" ], "summary": "List offers", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "maximum": 500, "minimum": 1, "type": "integer", "default": 50, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "default": "-updated", "description": "Sort field (prefix with - for descending)", "name": "sort", "in": "query" }, { "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "string", "description": "Filter by offer type", "name": "offer_type", "in": "query" }, { "type": "string", "description": "Filter by target scope", "name": "target_scope", "in": "query" }, { "type": "string", "description": "Filter by organization app", "name": "organization_app_id", "in": "query" }, { "type": "string", "description": "Filter by target iv_id", "name": "target_iv_id", "in": "query" }, { "type": "string", "description": "Filter by target barcode", "name": "target_barcode", "in": "query" }, { "type": "boolean", "description": "Filter by active flag", "name": "is_active", "in": "query" }, { "type": "boolean", "description": "Filter by sync flag", "name": "synced", "in": "query" }, { "type": "string", "description": "Search in offer name/description", "name": "search", "in": "query" } ], "responses": { "200": { "description": "Offers list", "schema": { "$ref": "#/definitions/domain.OfferListResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new offer rule for the authenticated organization.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Offers" ], "summary": "Create offer", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Offer payload", "name": "offer", "in": "body", "required": true, "schema": { "$ref": "#/definitions/domain.OfferRequest" } } ], "responses": { "201": { "description": "Offer created", "schema": { "$ref": "#/definitions/domain.OfferCreateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Validation failed", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/offers/bulk": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Validate and upsert multiple offers in one request.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Offers" ], "summary": "Bulk upsert offers", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Bulk offers payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.offerBulkRequest" } } ], "responses": { "200": { "description": "Bulk result", "schema": { "$ref": "#/definitions/domain.OfferBulkResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Validation failed", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/offers/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get a single offer by ID scoped to the authenticated organization.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Offers" ], "summary": "Get offer", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Offer ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Offer record", "schema": { "$ref": "#/definitions/domain.OfferResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Offer not found", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update an existing offer by ID for the authenticated organization.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Offers" ], "summary": "Update offer", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Offer ID", "name": "id", "in": "path", "required": true }, { "description": "Offer payload", "name": "offer", "in": "body", "required": true, "schema": { "$ref": "#/definitions/domain.OfferRequest" } } ], "responses": { "200": { "description": "Offer updated", "schema": { "$ref": "#/definitions/domain.OfferUpdateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Offer not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Validation failed", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete an offer by ID for the authenticated organization.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Offers" ], "summary": "Delete offer", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Offer ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "Offer deleted" }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Offer not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/offers/{id}/status": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update status flags of an existing offer by ID.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Offers" ], "summary": "Update offer status", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Offer ID", "name": "id", "in": "path", "required": true }, { "description": "Status payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/domain.OfferStatusUpdate" } } ], "responses": { "200": { "description": "Status updated", "schema": { "$ref": "#/definitions/domain.OfferUpdateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Offer not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Validation failed", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/orders": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get a paginated list of orders with comprehensive filtering options", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "List orders", "parameters": [ { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "maximum": 100, "minimum": 1, "type": "integer", "default": 50, "description": "Items per page", "name": "limit", "in": "query" }, { "enum": [ "pending", "confirmed", "processing", "completed", "cancelled" ], "type": "string", "description": "Filter by order status", "name": "status", "in": "query" }, { "enum": [ "pending", "processing", "completed", "failed", "refunded" ], "type": "string", "description": "Filter by payment status", "name": "payment_status", "in": "query" }, { "type": "string", "description": "Filter by fulfillment status (free text)", "name": "fulfillment_status", "in": "query" }, { "type": "string", "description": "Filter by order source", "name": "source", "in": "query" }, { "type": "string", "description": "Filter by customer email", "name": "customer_email", "in": "query" }, { "type": "string", "example": "\"2024-01-01T00:00:00Z\"", "description": "Start date (RFC3339)", "name": "from", "in": "query" }, { "type": "string", "example": "\"2024-12-31T23:59:59Z\"", "description": "End date (RFC3339)", "name": "to", "in": "query" }, { "type": "string", "description": "Search in customer name, email, phone, or order ID", "name": "search", "in": "query" }, { "enum": [ "created", "-created", "total_amount", "-total_amount", "customer_name", "-customer_name" ], "type": "string", "default": "-created", "description": "Sort order", "name": "sort", "in": "query" }, { "type": "number", "description": "Minimum order amount", "name": "min_amount", "in": "query" }, { "type": "number", "description": "Maximum order amount", "name": "max_amount", "in": "query" }, { "type": "string", "description": "Filter by currency code (3 letters)", "name": "currency", "in": "query" } ], "responses": { "200": { "description": "Successful response: list envelope + order.snapshot payloads", "schema": { "$ref": "#/definitions/webhooks.UnifiedOrdersListHTTPBody" } }, "400": { "description": "Bad request - invalid parameters", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized - authentication required", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Create a new order with validation and duplicate checking", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "Create order", "parameters": [ { "description": "Order details with all required fields", "name": "order", "in": "body", "required": true, "schema": { "$ref": "#/definitions/domain.OrderRequest" } } ], "responses": { "201": { "description": "Order created successfully", "schema": { "$ref": "#/definitions/domain.OrderCreateResponse" } }, "400": { "description": "Bad request - validation failed", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized - authentication required", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "409": { "description": "Conflict - duplicate order", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/orders/analytics/summary": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get analytical summary of orders with various telemetry", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "Get order analytics", "parameters": [ { "type": "string", "example": "\"2024-01-01T00:00:00Z\"", "description": "Start date (RFC3339)", "name": "from", "in": "query" }, { "type": "string", "example": "\"2024-12-31T23:59:59Z\"", "description": "End date (RFC3339)", "name": "to", "in": "query" }, { "enum": [ "day", "week", "month", "status", "source" ], "type": "string", "description": "Group results by", "name": "group_by", "in": "query" } ], "responses": { "200": { "description": "Analytics summary", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/orders/bulk": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Create multiple orders in a single atomic transaction", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "Bulk create orders", "parameters": [ { "description": "Array of order details", "name": "orders", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/domain.OrderRequest" } } } ], "responses": { "201": { "description": "Orders created successfully", "schema": { "$ref": "#/definitions/domain.OrderBulkResponse" } }, "400": { "description": "Bad request - validation failed", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized - authentication required", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Delete multiple orders in a single request", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "Bulk delete orders", "parameters": [ { "description": "Array of order IDs to delete", "name": "order_ids", "in": "body", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Orders deleted successfully", "schema": { "$ref": "#/definitions/domain.OrderBulkResponse" } }, "400": { "description": "Bad request - invalid order IDs", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized - authentication required", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/orders/bulk/status": { "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update status for multiple orders in a single request", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "Bulk update order status", "parameters": [ { "description": "Bulk status update request", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "additionalProperties": true } } ], "responses": { "200": { "description": "Status updated successfully", "schema": { "$ref": "#/definitions/domain.OrderBulkResponse" } }, "400": { "description": "Bad request - validation failed", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized - authentication required", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/orders/export": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Export simple orders totals report (alias to /api/v1/orders/export/summary)", "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "Export orders", "parameters": [ { "maximum": 730, "minimum": 1, "type": "integer", "default": 365, "description": "Report window in days", "name": "days", "in": "query" } ], "responses": { "200": { "description": "Simple orders totals export data", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/orders/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieve detailed information about a specific order", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "Get order by ID", "parameters": [ { "type": "string", "example": "\"ord_1234567890\"", "description": "Order ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Order snapshot (order.snapshot) without vendor raw payloads", "schema": { "$ref": "#/definitions/webhooks.UnifiedOrderEventPayload" } }, "400": { "description": "Bad request - invalid order ID", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized - authentication required", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "404": { "description": "Order not found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } }, "put": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update order details with validation", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "Update order", "parameters": [ { "type": "string", "example": "\"ord_1234567890\"", "description": "Order ID", "name": "id", "in": "path", "required": true }, { "description": "Updated order details", "name": "order", "in": "body", "required": true, "schema": { "$ref": "#/definitions/domain.OrderRequest" } } ], "responses": { "200": { "description": "Order updated successfully", "schema": { "$ref": "#/definitions/domain.OrderUpdateResponse" } }, "400": { "description": "Bad request - validation failed", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized - authentication required", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "404": { "description": "Order not found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } }, "delete": { "security": [ { "ApiKeyAuth": [] } ], "description": "Permanently delete an order from the runtime", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "Delete order", "parameters": [ { "type": "string", "example": "\"ord_1234567890\"", "description": "Order ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "Order deleted successfully - no content returned" }, "400": { "description": "Bad request - invalid order ID", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized - authentication required", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "404": { "description": "Order not found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/orders/{id}/status": { "patch": { "security": [ { "ApiKeyAuth": [] } ], "description": "Update order, payment, or fulfillment status with validation", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Orders" ], "summary": "Update order status", "parameters": [ { "type": "string", "example": "\"ord_1234567890\"", "description": "Order ID", "name": "id", "in": "path", "required": true }, { "description": "Status update request", "name": "status", "in": "body", "required": true, "schema": { "$ref": "#/definitions/domain.OrderStatusUpdate" } } ], "responses": { "200": { "description": "Status updated successfully", "schema": { "$ref": "#/definitions/domain.OrderUpdateResponse" } }, "400": { "description": "Bad request - invalid status", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized - authentication required", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "404": { "description": "Order not found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/org-apps/{orgAppId}/dependents": { "get": { "description": "Returns counts of whitelists, identifier mappings, branches, staging records", "tags": [ "Organization Apps" ], "summary": "Preview dependents for an organization app", "parameters": [ { "type": "string", "description": "Organization App ID", "name": "orgAppId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/appstore.DependentCounts" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/org-apps/{orgAppId}/uninstall": { "delete": { "description": "Cleanly removes an installed app, optionally transferring data first", "tags": [ "Organization Apps" ], "summary": "Uninstall an organization app", "parameters": [ { "type": "string", "description": "Organization App ID", "name": "orgAppId", "in": "path", "required": true }, { "type": "string", "description": "Target org app ID for data migration", "name": "transferTo", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/payments/orders": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Accepts order payload and requested providers, stores pending order in orders table, resolves provider app config from apps collection, then executes the selected provider app.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Payments" ], "summary": "Create payment order", "parameters": [ { "description": "Payment order request", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.paymentOrderRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/v1.paymentOrderCreateResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/payments/orders/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns a unified order snapshot (same shape as GET /api/v1/orders/{id}).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Payments" ], "summary": "Get payment order", "parameters": [ { "type": "string", "description": "Order ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/webhooks.UnifiedOrderEventPayload" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/payments/orders/{id}/confirm": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Confirms payment completion for a selected supported provider, updates order statuses, and executes the mapped provider app.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Payments" ], "summary": "Confirm payment order", "parameters": [ { "type": "string", "description": "Order ID", "name": "id", "in": "path", "required": true }, { "description": "Confirm payment request", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.paymentOrderConfirmRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/ping": { "get": { "description": "Simple ping/pong endpoint for connectivity checks", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Connectivity" ], "summary": "Ping endpoint", "responses": { "200": { "description": "Pong response", "schema": { "$ref": "#/definitions/v1.PingResponse" } } } } }, "/api/v1/posts": { "get": { "description": "Get a paginated list of Published posts with optional filtering", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Posts" ], "summary": "List Published posts", "parameters": [ { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "maximum": 100, "minimum": 1, "type": "integer", "default": 20, "description": "Items per page", "name": "limit", "in": "query" }, { "enum": [ "Published" ], "type": "string", "default": "Published", "description": "Post status filter", "name": "status", "in": "query" }, { "type": "string", "description": "Filter by author name", "name": "author", "in": "query" }, { "type": "string", "description": "Filter by tags (comma-separated)", "name": "tags", "in": "query" }, { "type": "string", "description": "Search in title, content, and excerpt", "name": "search", "in": "query" }, { "type": "boolean", "description": "Filter newsletter posts only", "name": "newsletter", "in": "query" }, { "enum": [ "created", "-created", "updated", "-updated", "title", "-title" ], "type": "string", "default": "-created", "description": "Sort order", "name": "sort", "in": "query" }, { "type": "string", "description": "Filter posts created after this date (ISO 8601)", "name": "start_date", "in": "query" }, { "type": "string", "description": "Filter posts created before this date (ISO 8601)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "Successful response", "schema": { "$ref": "#/definitions/v1.PostListResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/posts/id/{id}": { "get": { "description": "Retrieve a single Published post by its unique identifier", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Posts" ], "summary": "Get post by ID", "parameters": [ { "type": "string", "description": "Post ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Post found", "schema": { "$ref": "#/definitions/v1.PostResponse" } }, "404": { "description": "Post not found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/posts/{slug}": { "get": { "description": "Retrieve a single Published post by its URL slug", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Posts" ], "summary": "Get post by slug", "parameters": [ { "type": "string", "description": "Post slug", "name": "slug", "in": "path", "required": true } ], "responses": { "200": { "description": "Post found", "schema": { "$ref": "#/definitions/v1.PostResponse" } }, "404": { "description": "Post not found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/products": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves a paginated list of products with comprehensive filtering options, search capabilities, and performance optimizations\n\n## Features:\n- **Smart Pagination**: Efficient cursor-based pagination with configurable page sizes\n- **Advanced Filtering**: Filter by multiple attributes including category, brand, and product characteristics\n- **Hybrid Search**: Fast identifier lookup + name/generic search with index-friendly short-query behavior\n- **Performance Optimized**: Uses indexed queries and minimal data transfer\n- **Organization Scoped**: Automatically filters products by user's organization\n\n## Search Behavior:\nThe search parameter performs case-insensitive matching across:\n- Product names (Arabic and English)\n- Generic name\n- Barcode\n- GTIN (Global Trade Item Number)\n- IV ID / SFDA / ASIN / NSKU identifiers\n\n## Performance Notes:\n- Product-list responses are cached for 12 seconds (DragonflyDB, with in-process fallback)\n- Maximum 100 items per page for optimal performance\n- Indexed on commonly filtered fields\n\n## Example Request:\n```bash\ncurl -X GET \"https://linkit.works/api/v1/products?page=1\u0026limit=50\u0026search=coffee\u0026is_enabled=true\" -H \"Authorization: Bearer \u003ctoken\u003e\"\n```\n\n## Example JavaScript:\n```javascript\nconst params = new URLSearchParams({\npage: 1,\nlimit: 50,\nsearch: 'coffee',\nis_enabled: true\n});\nconst response = await fetch(`https://linkit.works/api/v1/products?${params}`, {\nheaders: { 'Authorization': 'Bearer \u003ctoken\u003e' }\n});\n```", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Products" ], "summary": "List products with pagination and filtering", "parameters": [ { "type": "string", "default": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID (optional if user belongs to single org)", "name": "X-Organization-ID", "in": "header" }, { "minimum": 1, "type": "integer", "default": 1, "description": "Page number (1-based indexing)", "name": "page", "in": "query" }, { "maximum": 100, "minimum": 1, "type": "integer", "default": 50, "description": "Number of items per page", "name": "limit", "in": "query" }, { "type": "boolean", "description": "Filter by enabled/disabled status", "name": "enabled", "in": "query" }, { "type": "string", "description": "Filter by category ID", "name": "category_id", "in": "query" }, { "type": "string", "description": "Filter by brand ID", "name": "brand_id", "in": "query" }, { "type": "string", "description": "Search term for name, description, barcode, or GTIN", "name": "search", "in": "query" }, { "type": "boolean", "description": "Filter for fast-moving products", "name": "is_fast_moving", "in": "query" }, { "type": "boolean", "description": "Filter for refrigerated products", "name": "is_refrigerated", "in": "query" }, { "type": "boolean", "description": "Filter for quick commerce eligible products", "name": "is_quick_commerce", "in": "query" } ], "responses": { "200": { "description": "Paginated list of products with metadata", "schema": { "$ref": "#/definitions/v1.ProductListResponse" } }, "400": { "description": "Bad Request - Invalid query parameters", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized - Invalid or expired authentication token", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal Server Error - Database or runtime error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new product in the catalog with comprehensive validation, duplicate checking, and automatic hash generation for change tracking\n\n## Features:\n- **Duplicate Prevention**: Checks for existing products with the same IV ID within the organization\n- **Data Validation**: Validates all required fields and data formats before persistence\n- **Automatic Timestamping**: Sets creation and update timestamps automatically\n- **Hash Generation**: Creates a unique hash for change detection and synchronization\n- **Transaction Safety**: Entire operation is wrapped in a database transaction\n\n## Required Permissions:\n- Valid authentication token\n- Organization membership\n- Product creation privileges\n\n## Example Request:\n```bash\ncurl -X POST \"https://linkit.works/api/v1/products\" -H \"Authorization: Bearer \u003ctoken\u003e\" -H \"Content-Type: application/json\" -d '{\n\"iv_id\": \"IV123456\",\n\"name_en\": \"Premium Coffee Beans\",\n\"name_ar\": \"حبوب القهوة الممتازة\",\n\"barcode\": \"1234567890123\",\n\"average_price\": 29.99\n}'\n```", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Products" ], "summary": "Create a new product", "parameters": [ { "type": "string", "default": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID (optional if user belongs to single org)", "name": "X-Organization-ID", "in": "header" }, { "description": "Product details to create", "name": "product", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.ProductRequest" } } ], "responses": { "201": { "description": "Product created successfully with generated ID and timestamps", "schema": { "$ref": "#/definitions/v1.ProductCreateResponse" } }, "400": { "description": "Bad Request - Invalid input data or missing required fields", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized - Invalid or expired authentication token", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Conflict - Product with same IV ID already exists in organization", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Unprocessable Entity - Validation failed for one or more fields", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal Server Error - Database or runtime error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/products/bulk": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create, update, or upsert multiple products in a single request. Max 1000 products per request.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Products" ], "summary": "Bulk product operations", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Bulk operation request", "name": "bulk", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.ProductBulkRequest" } } ], "responses": { "200": { "description": "Bulk operation completed", "schema": { "$ref": "#/definitions/v1.ProductBulkResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "413": { "description": "Payload too large", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/products/fix-skus": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Iterates through all products in the organization and generates SKUs for any missing branches.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Products" ], "summary": "Fix missing SKUs for all products", "responses": {} } }, "/api/v1/products/iv/{ivId}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieves detailed product information using either the Internal Vendor ID (IV ID) or internal runtime ID with organization-level access control\n\n## Identifier Resolution:\nThe endpoint accepts either:\n- Internal Vendor ID (IV ID) - External runtime identifier\n- Internal System ID - PocketBase record ID\n\nThe resolution follows this sequence:\n1. Attempt to find by IV ID\n2. If not found, attempt to find by internal ID\n3. Return 404 only if both lookups fail\n\n## Access Control:\n- Products are scoped to the authenticated user's organization\n- Cross-organization access is prevented at the API level\n- Returns 404 for products outside the user's organization\n\n## Response Details:\nThe response includes all product attributes including:\n- Basic information (names, descriptions in multiple languages)\n- Pricing details (with and without VAT)\n- Product characteristics and flags\n- Media assets (hero image and secondary images)\n- Related data (brand, category, SKUs)\n- Regulatory codes (GTIN, HSA, SFDA, ASIN)\n\n## Example Requests:\n```bash\n# Using IV ID\ncurl -X GET \"https://linkit.works/api/v1/products/iv/IV123456\" -H \"Authorization: Bearer \u003ctoken\u003e\"\n\n# Using internal ID\ncurl -X GET \"https://linkit.works/api/v1/products/iv/rec_abc123def456\" -H \"Authorization: Bearer \u003ctoken\u003e\"\n```", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Products" ], "summary": "Get product by Internal Vendor ID or internal ID", "parameters": [ { "type": "string", "default": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID (optional if user belongs to single org)", "name": "X-Organization-ID", "in": "header" }, { "maxLength": 100, "minLength": 1, "type": "string", "description": "Product Internal Vendor ID or internal ID", "name": "ivId", "in": "path", "required": true } ], "responses": { "200": { "description": "Detailed product information", "schema": { "$ref": "#/definitions/v1.ProductResponse" } }, "400": { "description": "Bad Request - Invalid ID format or missing parameter", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized - Invalid or expired authentication token", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Not Found - Product does not exist or not accessible", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal Server Error - Database or runtime error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Updates an existing product's information with validation and change tracking through hash generation\n\n## Update Behavior:\n- All fields in the request body will overwrite existing values\n- Omitted fields will retain their current values\n- Timestamps are automatically updated\n- A new hash is generated for change tracking\n- Organization ID and IV ID cannot be changed\n\n## Validation Rules:\n- Product must exist in the user's organization\n- Required fields must be provided\n- Data types must match schema definitions\n- Business rules are enforced (e.g., price validation)\n\n## Audit Trail:\n- Update operations are logged with user information\n- Previous values are preserved in audit logs\n- Hash changes indicate data modifications\n\n## Example Request:\n```bash\ncurl -X PUT \"https://linkit.works/api/v1/products/iv/IV123456\" -H \"Authorization: Bearer \u003ctoken\u003e\" -H \"Content-Type: application/json\" -d '{\n\"name_en\": \"Updated Product Name\",\n\"average_price\": 35.99,\n\"is_enabled\": true\n}'\n```", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Products" ], "summary": "Update product by Internal Vendor ID", "parameters": [ { "type": "string", "default": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID (optional if user belongs to single org)", "name": "X-Organization-ID", "in": "header" }, { "maxLength": 100, "minLength": 1, "type": "string", "description": "Product Internal Vendor ID to update", "name": "ivId", "in": "path", "required": true }, { "description": "Updated product information", "name": "product", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.ProductRequest" } } ], "responses": { "200": { "description": "Product updated successfully", "schema": { "$ref": "#/definitions/v1.ProductUpdateResponse" } }, "400": { "description": "Bad Request - Invalid input data or IV ID", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized - Invalid or expired authentication token", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Not Found - Product does not exist in organization", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Unprocessable Entity - Validation failed", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal Server Error - Update operation failed", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Permanently deletes a product and all associated data including SKUs and inventory records in a transactional operation\n\n## Cascade Deletion:\nThis operation will permanently delete:\n- The product record\n- All associated SKUs\n- All inventory records\n- All price history (if applicable)\n\n## Transaction Safety:\n- Entire operation is wrapped in a database transaction\n- If any deletion fails, all changes are rolled back\n- Ensures data consistency across related tables\n\n## Important Notes:\n- This operation is irreversible\n- Consider using soft delete (is_enabled=false) for temporary removal\n- Deletion is logged for audit purposes\n- Active orders referencing this product may be affected\n\n## Example Request:\n```bash\ncurl -X DELETE \"https://linkit.works/api/v1/products/iv/IV123456\" -H \"Authorization: Bearer \u003ctoken\u003e\"\n```", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Products" ], "summary": "Delete product and all related data", "parameters": [ { "type": "string", "default": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "Bearer token for authentication", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "description": "Organization ID (optional if user belongs to single org)", "name": "X-Organization-ID", "in": "header" }, { "maxLength": 100, "minLength": 1, "type": "string", "description": "Product Internal Vendor ID to delete", "name": "ivId", "in": "path", "required": true } ], "responses": { "204": { "description": "Product and all related data deleted successfully - No content returned" }, "400": { "description": "Bad Request - Invalid IV ID format", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized - Invalid or expired authentication token", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "Not Found - Product does not exist in organization", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal Server Error - Deletion failed, transaction rolled back", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/providers": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns all registered BNPL and direct payment providers with their metadata.", "produces": [ "application/json" ], "tags": [ "Providers" ], "summary": "List available payment providers", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/providers/config/{provider}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns provider-specific configuration such as required fields and endpoint docs.", "produces": [ "application/json" ], "tags": [ "Providers" ], "summary": "Get provider configuration", "parameters": [ { "type": "string", "description": "Provider ID (tabby, tamara, mispay, stripe, moyasar, tap, dinero, paypal, hyperpay)", "name": "provider", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/providers/paylinks": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns all payment links, filterable by provider and/or org_app_id query parameters.", "produces": [ "application/json" ], "tags": [ "Providers" ], "summary": "List payment links", "parameters": [ { "type": "string", "description": "Filter by provider (tabby, tamara, mispay, ...)", "name": "provider", "in": "query" }, { "type": "string", "description": "Filter by organization app ID", "name": "org_app_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } }, "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Creates a BNPL payment link using the specified provider (tabby, tamara, mispay). Gateway sync providers (stripe, moyasar, tap, dinero) are rejected here — use POST /api/v1/payments/orders instead.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Providers" ], "summary": "Create payment link", "parameters": [ { "description": "Paylink create request with provider, org_app_id, order_id, amount, currency", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.ProviderPaylinkRequest" } } ], "responses": { "201": { "description": "Payment link created", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Validation error", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Provider API error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/providers/paylinks/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves the current status of a payment link. If supported, also polls the provider API for real-time status.", "produces": [ "application/json" ], "tags": [ "Providers" ], "summary": "Get payment link status", "parameters": [ { "type": "string", "description": "Payment link ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/providers/paylinks/{id}/cancel": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Cancels a pending payment link. Attempts to cancel on the provider side if possible.", "produces": [ "application/json" ], "tags": [ "Providers" ], "summary": "Cancel payment link", "parameters": [ { "type": "string", "description": "Payment link ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/providers/paylinks/{id}/capture": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Captures (Tabby/Tamara) or finalizes (MisPay) a payment link. Provider-specific logic is dispatched automatically.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Providers" ], "summary": "Capture/finalize payment", "parameters": [ { "type": "string", "description": "Payment link ID", "name": "id", "in": "path", "required": true }, { "description": "Optional capture details", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/v1.ProviderPaylinkCaptureRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Bad Gateway", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/reports/offers": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get aggregated offers analytics (summary, byType, byStatus, recent, target and app breakdown) for the authenticated organization.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Offers" ], "summary": "Offers analytics report", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "maximum": 3650, "minimum": 1, "type": "integer", "default": 90, "description": "Recent offers window in days", "name": "days", "in": "query" } ], "responses": { "200": { "description": "Offers analytics report envelope", "schema": { "$ref": "#/definitions/v1.reportEnvelope" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/skus": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new SKU using internal vendor ID (iv_id) scoped to organization and branch", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SKUs" ], "summary": "Create new SKU with organization scoping", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "SKU details with iv_id", "name": "sku", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.SKURequest" } } ], "responses": { "201": { "description": "SKU created successfully", "schema": { "$ref": "#/definitions/v1.SKUResponse" } }, "400": { "description": "Bad request - validation failed", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "409": { "description": "Conflict - SKU already exists for organization/branch/iv_id", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Unprocessable entity", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/skus/bulk": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create, update, or upsert multiple SKUs in a single request. Max 1000 SKUs per request.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SKUs" ], "summary": "Bulk SKU operations", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "description": "Bulk operation request", "name": "bulk", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.SKUBulkRequest" } } ], "responses": { "200": { "description": "Bulk operation completed", "schema": { "$ref": "#/definitions/v1.SKUBulkResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "413": { "description": "Payload too large", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/skus/iv/{ivId}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve detailed SKU information by Internal Vendor ID or internal runtime ID\n\n## Identifier Resolution:\nThe endpoint accepts either:\n- Internal Vendor ID (IV ID) - External runtime identifier\n- Internal System ID - PocketBase record ID\n\nThe resolution follows this sequence:\n1. Attempt to find by IV ID\n2. If not found, attempt to find by internal ID\n3. Return 404 only if both lookups fail", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SKUs" ], "summary": "Get SKU by IV ID or internal ID", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"IV123456\"", "description": "SKU IV ID or internal ID", "name": "ivId", "in": "path", "required": true }, { "type": "string", "description": "Branch Internal Vendor ID (required if multiple branches have same SKU IV ID)", "name": "branch_iv_id", "in": "query" } ], "responses": { "200": { "description": "SKU details", "schema": { "$ref": "#/definitions/v1.SKUResponse" } }, "400": { "description": "Bad request or ambiguous SKU", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "SKU or Branch not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update existing SKU details by Internal Vendor ID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SKUs" ], "summary": "Update SKU", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"IV123456\"", "description": "SKU IV ID", "name": "ivId", "in": "path", "required": true }, { "type": "string", "description": "Branch IV ID (required if multiple branches have same SKU IV ID)", "name": "branch_iv_id", "in": "query" }, { "description": "Updated SKU details", "name": "sku", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.SKURequest" } } ], "responses": { "200": { "description": "SKU updated successfully", "schema": { "$ref": "#/definitions/v1.SKUUpdateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "SKU not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "422": { "description": "Unprocessable entity", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete a SKU by Internal Vendor ID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SKUs" ], "summary": "Delete SKU", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"IV123456\"", "description": "SKU IV ID", "name": "ivId", "in": "path", "required": true }, { "type": "string", "description": "Branch IV ID (required if multiple branches have same SKU IV ID)", "name": "branch_iv_id", "in": "query" } ], "responses": { "204": { "description": "SKU deleted successfully" }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "SKU not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/skus/iv/{ivId}/stock": { "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update SKU quantity and availability by Internal Vendor ID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SKUs" ], "summary": "Update SKU stock", "parameters": [ { "type": "string", "default": "Bearer \u003ctoken\u003e", "description": "Bearer token", "name": "Authorization", "in": "header", "required": true }, { "type": "string", "example": "\"IV123456\"", "description": "SKU IV ID", "name": "ivId", "in": "path", "required": true }, { "type": "string", "description": "Branch IV ID (required if multiple branches have same SKU IV ID)", "name": "branch_iv_id", "in": "query" }, { "description": "Stock update", "name": "stock", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.SKUStockUpdateRequest" } } ], "responses": { "200": { "description": "Stock updated successfully", "schema": { "$ref": "#/definitions/v1.SKUUpdateResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "404": { "description": "SKU not found", "schema": { "$ref": "#/definitions/v1.ProductError" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ProductError" } } } } }, "/api/v1/sms-providers/{slug}/balance": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns provider balance when supported; otherwise supported=false.", "produces": [ "application/json" ], "tags": [ "SMS providers" ], "summary": "Account balance / credits", "parameters": [ { "type": "string", "description": "Provider slug", "name": "slug", "in": "path", "required": true } ], "responses": { "200": { "description": "Balance or not-supported payload", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/sms-providers/{slug}/bulk-send": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Multipart upload (field `file`). CSV columns: mobile, message, optional sender, optional datetime.", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "SMS providers" ], "summary": "Bulk send SMS from CSV", "parameters": [ { "type": "string", "description": "Provider slug", "name": "slug", "in": "path", "required": true }, { "type": "file", "description": "CSV file", "name": "file", "in": "formData", "required": true } ], "responses": { "200": { "description": "Batch result", "schema": { "$ref": "#/definitions/v1.SmsManualBulkSendResponse" } }, "400": { "description": "Invalid file", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Bulk send failed", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/sms-providers/{slug}/progress": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Live sent/failed/total for the current in-process bulk operation on this instance.", "produces": [ "application/json" ], "tags": [ "SMS providers" ], "summary": "Bulk-send progress", "parameters": [ { "type": "string", "description": "Provider slug", "name": "slug", "in": "path", "required": true } ], "responses": { "200": { "description": "sent, failed, total", "schema": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/sms-providers/{slug}/send": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Dispatches one SMS through the installed SMS provider for this organization (slug: mora-sms, taqnyat-sms, …).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SMS providers" ], "summary": "Send a single SMS", "parameters": [ { "type": "string", "description": "Provider slug (e.g. mora-sms)", "name": "slug", "in": "path", "required": true }, { "description": "Message body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.SmsManualSendRequest" } } ], "responses": { "200": { "description": "Provider-specific send result", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Invalid request or provider", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Send failed", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/sms-providers/{slug}/sender-names": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Registered sender names for the organization’s provider account when supported.", "produces": [ "application/json" ], "tags": [ "SMS providers" ], "summary": "List sender IDs / names", "parameters": [ { "type": "string", "description": "Provider slug", "name": "slug", "in": "path", "required": true } ], "responses": { "200": { "description": "sender_names, count, supported", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/sms-providers/{slug}/template/{format}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Standard CSV template (format csv). Slug must be an installed SMS provider.", "produces": [ "text/csv" ], "tags": [ "SMS providers" ], "summary": "Download bulk CSV template", "parameters": [ { "type": "string", "description": "Provider slug", "name": "slug", "in": "path", "required": true }, { "type": "string", "description": "Template format (csv)", "name": "format", "in": "path", "required": true } ], "responses": { "200": { "description": "CSV file", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/sms/outbox": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Queues one SMS for the organization. Any installed manual SMS provider may dispatch it; optional preferred_provider_slug pins routing. Uses staging tables and per–organization_app status rows (see SMS outbox docs).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SMS outbox" ], "summary": "Enqueue SMS (provider-agnostic)", "parameters": [ { "description": "Outbox payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.SmsOutboxEnqueueRequest" } } ], "responses": { "200": { "description": "Queued or idempotent replay", "schema": { "$ref": "#/definitions/v1.SmsOutboxEnqueueResponse" } }, "400": { "description": "Validation or no SMS provider installed", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "500": { "description": "Persistence error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/sms/outbox/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Returns dispatch_status, provider_slug when known, and provider response payload after send.", "produces": [ "application/json" ], "tags": [ "SMS outbox" ], "summary": "Get SMS outbox request status", "parameters": [ { "type": "string", "description": "Outbox request id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Snapshot fields", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/tags": { "get": { "description": "Get a paginated list of all available tags", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Tags" ], "summary": "List all tags", "parameters": [ { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "maximum": 100, "minimum": 1, "type": "integer", "default": 50, "description": "Items per page", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Successful response", "schema": { "$ref": "#/definitions/v1.TagListResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/telemetry": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get comprehensive runtime telemetry including store, staging, and runtime performance", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Metrics" ], "summary": "System telemetry", "responses": { "200": { "description": "System telemetry", "schema": { "$ref": "#/definitions/v1.MetricsResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "503": { "description": "Service unavailable", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/api/v1/verifications/{slug}": { "post": { "security": [ { "ApiKeyAuth": [] } ], "description": "Checks if the provided credentials are valid for the specified app slug", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Verifications" ], "summary": "Verify app credentials", "parameters": [ { "type": "string", "description": "App Slug", "name": "slug", "in": "path", "required": true }, { "description": "Credentials", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1.VerificationRequest" } } ], "responses": { "200": { "description": "Verification result", "schema": { "$ref": "#/definitions/v1.VerificationResponse" } }, "400": { "description": "Bad request", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } }, "404": { "description": "Verifier not found", "schema": { "$ref": "#/definitions/v1.ErrorResponse" } } } } }, "/mcp": { "get": { "description": "Alias endpoint for MCP protocol access. Identical to /api/v1/mcp.\nUse whichever URL is more convenient in your MCP client configuration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MCP" ], "summary": "MCP Protocol Endpoint (Shorthand)", "parameters": [ { "description": "JSON-RPC 2.0 request", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/mcpserver.MCPToolCallRequest" } }, { "type": "string", "default": "2025-06-18", "description": "MCP protocol version", "name": "Mcp-Protocol-Version", "in": "header" }, { "type": "string", "description": "Session ID", "name": "Mcp-Session-Id", "in": "header" } ], "responses": { "200": { "description": "JSON-RPC 2.0 response", "schema": { "$ref": "#/definitions/mcpserver.MCPSessionResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/mcpserver.MCPErrorResponse" } } } }, "post": { "description": "Alias endpoint for MCP protocol access. Identical to /api/v1/mcp.\nUse whichever URL is more convenient in your MCP client configuration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MCP" ], "summary": "MCP Protocol Endpoint (Shorthand)", "parameters": [ { "description": "JSON-RPC 2.0 request", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/mcpserver.MCPToolCallRequest" } }, { "type": "string", "default": "2025-06-18", "description": "MCP protocol version", "name": "Mcp-Protocol-Version", "in": "header" }, { "type": "string", "description": "Session ID", "name": "Mcp-Session-Id", "in": "header" } ], "responses": { "200": { "description": "JSON-RPC 2.0 response", "schema": { "$ref": "#/definitions/mcpserver.MCPSessionResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/mcpserver.MCPErrorResponse" } } } }, "delete": { "description": "Alias endpoint for MCP protocol access. Identical to /api/v1/mcp.\nUse whichever URL is more convenient in your MCP client configuration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MCP" ], "summary": "MCP Protocol Endpoint (Shorthand)", "parameters": [ { "description": "JSON-RPC 2.0 request", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/mcpserver.MCPToolCallRequest" } }, { "type": "string", "default": "2025-06-18", "description": "MCP protocol version", "name": "Mcp-Protocol-Version", "in": "header" }, { "type": "string", "description": "Session ID", "name": "Mcp-Session-Id", "in": "header" } ], "responses": { "200": { "description": "JSON-RPC 2.0 response", "schema": { "$ref": "#/definitions/mcpserver.MCPSessionResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/mcpserver.MCPErrorResponse" } } } } } }, "definitions": { "appstore.DependentCounts": { "type": "object", "properties": { "branches": { "type": "integer" }, "identifier_mappings": { "type": "integer" }, "processing_reports": { "type": "integer" }, "staging_statuses": { "type": "integer" }, "whitelists": { "type": "integer" } } }, "contracts.RegistryMetrics": { "type": "object", "properties": { "average_create_time_ns": { "$ref": "#/definitions/time.Duration" }, "create_count": { "type": "integer" }, "create_errors": { "type": "integer" }, "factory_count": { "type": "integer" }, "factory_hits": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" } }, "fallback_count": { "type": "integer" } } }, "domain.BulkError": { "description": "Error detail for bulk operation failure", "type": "object", "properties": { "error": { "type": "string", "example": "Invalid status transition" }, "order_id": { "type": "string", "example": "ord_789" } } }, "domain.OfferBulkError": { "type": "object", "properties": { "error": { "type": "string" }, "index": { "type": "integer" }, "offer_id": { "type": "string" } } }, "domain.OfferBulkResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/domain.OfferBulkResponseData" }, "message": { "type": "string" }, "success": { "type": "boolean" }, "timestamp": { "type": "string" } } }, "domain.OfferBulkResponseData": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/domain.OfferBulkError" } }, "failed": { "type": "integer" }, "meta": { "type": "object" }, "offer_ids": { "type": "array", "items": { "type": "string" } }, "processed": { "type": "integer" } } }, "domain.OfferCreateData": { "type": "object", "properties": { "id": { "type": "string" } } }, "domain.OfferCreateResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/domain.OfferCreateData" }, "message": { "type": "string" }, "success": { "type": "boolean" }, "timestamp": { "type": "string" } } }, "domain.OfferListResponse": { "type": "object", "properties": { "meta": { "type": "object" }, "offers": { "type": "array", "items": { "$ref": "#/definitions/domain.OfferResponse" } }, "pagination": { "$ref": "#/definitions/domain.PaginationMeta" } } }, "domain.OfferRequest": { "type": "object", "properties": { "branch_ids": { "type": "array", "items": { "type": "string" } }, "branch_scope": { "description": "BranchScope is all branches (default) or selected branch record IDs (branches collection).", "type": "string" }, "buy_barcode": { "type": "string" }, "buy_iv_id": { "type": "string" }, "buy_product_id": { "type": "string" }, "buy_qty": { "type": "integer" }, "buy_sku_id": { "type": "string" }, "cap_amount": { "type": "number" }, "currency": { "type": "string" }, "description": { "type": "string" }, "discount_name_ar": { "description": "Optional labels for Jahez/Pik product discount API; ignored by HungerStation and other channels.", "type": "string" }, "discount_name_en": { "type": "string" }, "discount_type": { "type": "string" }, "discount_value": { "type": "number" }, "end_at": { "type": "string" }, "get_barcode": { "type": "string" }, "get_discount_percent": { "type": "number" }, "get_iv_id": { "type": "string" }, "get_product_id": { "type": "string" }, "get_qty": { "type": "integer" }, "get_sku_id": { "type": "string" }, "is_stackable": { "type": "boolean" }, "max_qty": { "type": "integer" }, "max_redemptions": { "type": "integer" }, "meta": { "type": "object" }, "min_qty": { "type": "integer" }, "name": { "type": "string" }, "offer_type": { "type": "string" }, "organization_app_id": { "type": "string" }, "priority": { "type": "integer" }, "remote_offer_id": { "type": "string" }, "start_at": { "type": "string" }, "status": { "type": "string" }, "target_barcode": { "type": "string" }, "target_brand_id": { "type": "string" }, "target_category_id": { "type": "string" }, "target_iv_id": { "type": "string" }, "target_product_id": { "type": "string" }, "target_scope": { "type": "string" }, "target_sku_id": { "type": "string" } } }, "domain.OfferResponse": { "type": "object", "properties": { "branch_ids": { "type": "array", "items": { "type": "string" } }, "branch_scope": { "type": "string" }, "buy_barcode": { "type": "string" }, "buy_iv_id": { "type": "string" }, "buy_product_id": { "type": "string" }, "buy_qty": { "type": "integer" }, "buy_sku_id": { "type": "string" }, "cap_amount": { "type": "number" }, "created": { "type": "string" }, "currency": { "type": "string" }, "description": { "type": "string" }, "discount_name_ar": { "type": "string" }, "discount_name_en": { "type": "string" }, "discount_type": { "type": "string" }, "discount_value": { "type": "number" }, "end_at": { "type": "string" }, "get_barcode": { "type": "string" }, "get_discount_percent": { "type": "number" }, "get_iv_id": { "type": "string" }, "get_product_id": { "type": "string" }, "get_qty": { "type": "integer" }, "get_sku_id": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "is_stackable": { "type": "boolean" }, "max_qty": { "type": "integer" }, "max_redemptions": { "type": "integer" }, "meta": { "type": "object" }, "min_qty": { "type": "integer" }, "name": { "type": "string" }, "offer_type": { "type": "string" }, "organization_app_id": { "type": "string" }, "organization_id": { "type": "string" }, "priority": { "type": "integer" }, "redeemed_count": { "type": "integer" }, "remote_offer_id": { "type": "string" }, "start_at": { "type": "string" }, "status": { "type": "string" }, "synced": { "type": "boolean" }, "synced_at": { "type": "string" }, "target_barcode": { "type": "string" }, "target_brand_id": { "type": "string" }, "target_category_id": { "type": "string" }, "target_iv_id": { "type": "string" }, "target_product_id": { "type": "string" }, "target_scope": { "type": "string" }, "target_sku_id": { "type": "string" }, "updated": { "type": "string" } } }, "domain.OfferStatusUpdate": { "type": "object", "properties": { "is_active": { "type": "boolean" }, "status": { "type": "string" } } }, "domain.OfferUpdateResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/domain.OfferCreateData" }, "message": { "type": "string" }, "success": { "type": "boolean" }, "timestamp": { "type": "string" } } }, "domain.OrderBulkResponse": { "description": "Response for bulk order operations", "type": "object", "properties": { "data": { "$ref": "#/definitions/domain.OrderBulkResponseData" }, "message": { "type": "string", "example": "Bulk operation completed" }, "success": { "type": "boolean", "example": true }, "timestamp": { "type": "string", "example": "2024-01-01T00:00:00Z" } } }, "domain.OrderBulkResponseData": { "description": "Bulk operation results summary", "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/domain.BulkError" } }, "failed": { "type": "integer", "example": 2 }, "meta": { "type": "object" }, "order_ids": { "type": "array", "items": { "type": "string" }, "example": [ "[\"ord_123\"", "\"ord_456\"]" ] }, "processed": { "type": "integer", "example": 10 } } }, "domain.OrderCreateData": { "description": "Created order data with unique identifier", "type": "object", "properties": { "id": { "type": "string", "example": "ord_1234567890" }, "order_number": { "type": "string", "example": "ORD-2024-001" } } }, "domain.OrderCreateResponse": { "description": "Order creation success response with generated ID", "type": "object", "properties": { "data": { "$ref": "#/definitions/domain.OrderCreateData" }, "message": { "type": "string", "example": "Order created successfully" }, "success": { "type": "boolean", "example": true }, "timestamp": { "type": "string", "example": "2024-01-01T00:00:00Z" } } }, "domain.OrderProduct": { "description": "Product information within an order", "type": "object", "required": [ "name", "price", "product_id", "quantity", "sku_id" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Product Name" }, "price": { "type": "number", "minimum": 0, "example": 49.99 }, "product_id": { "type": "string", "maxLength": 255, "example": "prd_123" }, "quantity": { "type": "integer", "minimum": 1, "example": 2 }, "sku_id": { "type": "string", "maxLength": 255, "example": "sku_123" } } }, "domain.OrderRequest": { "description": "Order creation or update request with comprehensive validation", "type": "object", "required": [ "currency", "customer_name", "destination", "fulfillment_method", "fulfillment_status", "order_status", "payment_method", "payment_status", "skus", "source", "source_time_stamp", "source_transaction_id", "total_amount" ], "properties": { "currency": { "type": "string", "example": "USD" }, "customer_email": { "type": "string", "example": "john@example.com" }, "customer_name": { "type": "string", "maxLength": 255, "example": "John Doe" }, "customer_phone": { "type": "string", "maxLength": 50, "example": "+1234567890" }, "destination": { "type": "string", "maxLength": 255, "example": "store_123" }, "destination_reference": { "type": "string", "maxLength": 255, "example": "REF-001" }, "discounts_amount": { "type": "number", "minimum": 0, "example": 10 }, "fulfillment_method": { "type": "string", "enum": [ "delivery", "pickup", "shipping" ], "example": "delivery" }, "fulfillment_status": { "type": "string", "maxLength": 100, "example": "pending" }, "order_status": { "type": "string", "maxLength": 100, "example": "pending" }, "payment_method": { "type": "string", "enum": [ "credit_card", "debit_card", "cash", "bank_transfer", "wallet" ], "example": "credit_card" }, "payment_status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "refunded" ], "example": "pending" }, "products": { "type": "array", "items": { "$ref": "#/definitions/domain.OrderProduct" } }, "raw_payload": { "type": "object" }, "receiver_name": { "type": "string", "maxLength": 255, "example": "Jane Doe" }, "receiver_phone": { "type": "string", "maxLength": 50, "example": "+0987654321" }, "shipping_address": { "type": "object" }, "skus": { "type": "array", "minItems": 1, "items": { "type": "string" }, "example": [ "[\"sku_123\"", "\"sku_456\"]" ] }, "source": { "type": "string", "maxLength": 100, "example": "website" }, "source_reference": { "type": "string", "maxLength": 255, "example": "SRC-001" }, "source_time_stamp": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "source_transaction_id": { "type": "string", "maxLength": 255, "example": "TXN-001" }, "total_amount": { "type": "number", "minimum": 0, "example": 99.99 }, "vat_amount": { "type": "number", "minimum": 0, "example": 15 } } }, "domain.OrderStatusUpdate": { "description": "Request body for updating order statuses", "type": "object", "properties": { "fulfillment_status": { "type": "string", "example": "shipped" }, "notes": { "type": "string", "example": "Status updated by runtime" }, "order_status": { "type": "string", "example": "confirmed" }, "payment_status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "refunded" ], "example": "completed" } } }, "domain.OrderUpdateData": { "description": "Updated order data with change summary", "type": "object", "properties": { "id": { "type": "string", "example": "ord_1234567890" }, "updated": { "type": "object" } } }, "domain.OrderUpdateResponse": { "description": "Order update success response", "type": "object", "properties": { "data": { "$ref": "#/definitions/domain.OrderUpdateData" }, "message": { "type": "string", "example": "Order updated successfully" }, "success": { "type": "boolean", "example": true }, "timestamp": { "type": "string", "example": "2024-01-01T00:00:00Z" } } }, "domain.PaginationMeta": { "type": "object", "properties": { "has_next": { "type": "boolean" }, "has_prev": { "type": "boolean" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_items": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "emailmarketing.PreviewResult": { "type": "object", "properties": { "content_mode": { "type": "string" }, "html": { "type": "string" }, "offer_count": { "type": "integer" }, "recipients": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" } } }, "emailmarketing.SendResult": { "type": "object", "properties": { "message": { "type": "string" }, "offer_count": { "type": "integer" }, "ok": { "type": "boolean" }, "recipient_count": { "type": "integer" } } }, "integrations.GlobalSystemHealth": { "type": "object", "properties": { "active_apps": { "type": "integer" }, "details": { "type": "object", "additionalProperties": {} }, "initialized": { "type": "boolean" }, "manager_metrics": { "$ref": "#/definitions/lifecycle.Metrics" }, "registry_metrics": { "$ref": "#/definitions/registry.Metrics" }, "scheduler_metrics": { "$ref": "#/definitions/scheduler.Metrics" }, "staging_metrics": { "$ref": "#/definitions/staging.Metrics" }, "started": { "type": "boolean" }, "status": { "type": "string" }, "timestamp": { "type": "string" }, "total_apps": { "type": "integer" } } }, "lifecycle.Metrics": { "type": "object", "properties": { "active_instances": { "type": "integer" }, "last_refresh": { "type": "string" }, "refresh_count": { "description": "Refresh operation metrics", "type": "integer" }, "refresh_duration_ns": { "$ref": "#/definitions/time.Duration" }, "registry_metrics": { "description": "Nested component metrics", "allOf": [ { "$ref": "#/definitions/contracts.RegistryMetrics" } ] }, "scheduler_notifies": { "description": "Scheduler coordination metrics", "type": "integer" }, "total_instances": { "type": "integer" }, "total_organizations": { "description": "Organization and app counts", "type": "integer" }, "vendor_cache_hit_rate": { "type": "number" }, "vendor_cache_hits": { "type": "integer" }, "vendor_cache_misses": { "type": "integer" }, "vendor_config_calls": { "description": "Vendor configuration metrics", "type": "integer" } } }, "mcpserver.MCPCapabilities": { "type": "object", "properties": { "resources": { "description": "Resource support", "type": "object" }, "tools": { "description": "Tool support", "type": "object" } } }, "mcpserver.MCPContentBlock": { "type": "object", "properties": { "text": { "description": "Text content (HTTP response body)", "type": "string", "example": "HTTP 200 OK\n\n{\"items\": [...]}" }, "type": { "description": "Content type (always \"text\" for API responses)", "type": "string", "example": "text" } } }, "mcpserver.MCPErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/definitions/mcpserver.MCPRPCError" }, "id": { "type": "integer", "example": 1 }, "jsonrpc": { "type": "string", "example": "2.0" } } }, "mcpserver.MCPInitializeResult": { "type": "object", "properties": { "capabilities": { "description": "Server capabilities", "allOf": [ { "$ref": "#/definitions/mcpserver.MCPCapabilities" } ] }, "protocolVersion": { "description": "Protocol version supported by this server", "type": "string", "example": "2025-06-18" }, "serverInfo": { "description": "Server implementation info", "allOf": [ { "$ref": "#/definitions/mcpserver.MCPServerInfo" } ] } } }, "mcpserver.MCPRPCError": { "type": "object", "properties": { "code": { "type": "integer", "example": -32600 }, "message": { "type": "string", "example": "Invalid request" } } }, "mcpserver.MCPResourceDef": { "type": "object", "properties": { "description": { "description": "Resource description", "type": "string", "example": "Complete Swagger/OpenAPI 2.0 specification for the Linkit REST API in JSON format" }, "mimeType": { "description": "MIME type of the resource content", "type": "string", "example": "application/json" }, "name": { "description": "Human-readable resource name", "type": "string", "example": "Linkit API Specification (JSON)" }, "uri": { "description": "Unique resource URI", "type": "string", "example": "linkit://docs/swagger.json" } } }, "mcpserver.MCPResourceListResponse": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "jsonrpc": { "type": "string", "example": "2.0" }, "result": { "$ref": "#/definitions/mcpserver.MCPResourceListResult" } } }, "mcpserver.MCPResourceListResult": { "type": "object", "properties": { "resources": { "description": "List of available resources", "type": "array", "items": { "$ref": "#/definitions/mcpserver.MCPResourceDef" } } } }, "mcpserver.MCPServerInfo": { "type": "object", "properties": { "name": { "description": "Server name", "type": "string", "example": "linkit" }, "version": { "description": "Server version", "type": "string", "example": "1.0.0" } } }, "mcpserver.MCPSessionResponse": { "type": "object", "properties": { "id": { "description": "Unique request identifier", "type": "integer", "example": 1 }, "jsonrpc": { "description": "JSON-RPC version (always \"2.0\")", "type": "string", "example": "2.0" }, "result": { "description": "Server information and capabilities", "allOf": [ { "$ref": "#/definitions/mcpserver.MCPInitializeResult" } ] } } }, "mcpserver.MCPToolCallParams": { "type": "object", "properties": { "arguments": { "description": "Tool arguments (varies by tool)", "type": "object", "additionalProperties": {} }, "name": { "description": "Name of the tool to call (e.g. \"get_products\")", "type": "string", "example": "get_products" } } }, "mcpserver.MCPToolCallRequest": { "type": "object", "properties": { "id": { "description": "Request identifier", "type": "integer", "example": 1 }, "jsonrpc": { "description": "JSON-RPC version", "type": "string", "example": "2.0" }, "method": { "description": "Method name (always \"tools/call\")", "type": "string", "example": "tools/call" }, "params": { "description": "Call parameters", "allOf": [ { "$ref": "#/definitions/mcpserver.MCPToolCallParams" } ] } } }, "mcpserver.MCPToolCallResponse": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "jsonrpc": { "type": "string", "example": "2.0" }, "result": { "$ref": "#/definitions/mcpserver.MCPToolCallResult" } } }, "mcpserver.MCPToolCallResult": { "type": "object", "properties": { "content": { "description": "Content blocks returned by the tool", "type": "array", "items": { "$ref": "#/definitions/mcpserver.MCPContentBlock" } }, "isError": { "description": "Whether the call resulted in an error", "type": "boolean" } } }, "mcpserver.MCPToolDef": { "type": "object", "properties": { "description": { "description": "Human-readable tool description", "type": "string", "example": "[GET /api/v1/products] List all products" }, "inputSchema": { "description": "JSON Schema for the tool's input parameters", "type": "object", "additionalProperties": {} }, "name": { "description": "Tool name (e.g. \"get_products\", \"post_orders\")", "type": "string", "example": "get_products" } } }, "mcpserver.MCPToolListResponse": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "jsonrpc": { "type": "string", "example": "2.0" }, "result": { "$ref": "#/definitions/mcpserver.MCPToolListResult" } } }, "mcpserver.MCPToolListResult": { "type": "object", "properties": { "tools": { "description": "List of available tools", "type": "array", "items": { "$ref": "#/definitions/mcpserver.MCPToolDef" } } } }, "registry.Metrics": { "type": "object", "properties": { "average_creation_time_ns": { "$ref": "#/definitions/time.Duration" }, "cache_hit_rate": { "description": "Extended metrics for enhanced observability", "type": "number" }, "factory_hits": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" } }, "last_reset_time": { "type": "string" }, "peak_concurrency": { "type": "integer" }, "total_created": { "type": "integer" }, "total_errors": { "type": "integer" }, "total_factories": { "type": "integer" }, "total_fallbacks": { "type": "integer" } } }, "scheduler.Metrics": { "type": "object", "properties": { "active_executions": { "type": "integer" }, "active_workers": { "type": "integer" }, "average_execution_time_ns": { "$ref": "#/definitions/time.Duration" }, "current_gen_records": { "type": "integer" }, "execution_records": { "type": "integer" }, "failed_runs": { "type": "integer" }, "generation": { "type": "integer" }, "immediate_executions": { "type": "integer" }, "last_execution": { "type": "string" }, "peak_concurrent": { "type": "integer" }, "refresh_count": { "type": "integer" }, "running": { "type": "boolean" }, "stale_clears": { "type": "integer" }, "success_rate": { "type": "number" }, "successful_runs": { "type": "integer" }, "total_executions": { "type": "integer" } } }, "smsmanual.BulkError": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "mobile": { "type": "string" } } }, "staging.Metrics": { "type": "object", "properties": { "running": { "type": "boolean" }, "total_cleaned_up": { "type": "integer" }, "total_failed": { "type": "integer" }, "total_processed": { "type": "integer" }, "trigger_queued": { "type": "integer" }, "usage_recorded": { "type": "integer" } } }, "time.Duration": { "type": "integer", "format": "int64", "enum": [ -9223372036854775808, 9223372036854775807, 1, 1000, 1000000, 1000000000, 60000000000, 3600000000000 ], "x-enum-varnames": [ "minDuration", "maxDuration", "Nanosecond", "Microsecond", "Millisecond", "Second", "Minute", "Hour" ] }, "types.DateTime": { "type": "object" }, "v1.AddressRequest": { "type": "object", "required": [ "address_line1", "city", "country", "label", "state" ], "properties": { "address_line1": { "type": "string", "maxLength": 200, "minLength": 1 }, "address_line2": { "type": "string" }, "city": { "type": "string", "maxLength": 100, "minLength": 1 }, "country": { "type": "string" }, "is_default": { "type": "boolean" }, "label": { "type": "string", "maxLength": 50, "minLength": 1 }, "state": { "type": "string", "maxLength": 100, "minLength": 1 } } }, "v1.AddressResponse": { "type": "object", "properties": { "address_line1": { "type": "string" }, "address_line2": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "created": { "$ref": "#/definitions/types.DateTime" }, "customer_id": { "type": "string" }, "id": { "type": "string" }, "is_default": { "type": "boolean" }, "label": { "type": "string" }, "state": { "type": "string" }, "updated": { "$ref": "#/definitions/types.DateTime" } } }, "v1.BatchExecuteRequest": { "description": "Request to execute multiple integrations", "type": "object", "properties": { "full_sync": { "type": "boolean", "example": false }, "max_concurrent": { "type": "integer", "example": 5 }, "slugs": { "type": "array", "items": { "type": "string" }, "example": [ "[\"app1\"", "\"app2\"]" ] } } }, "v1.BatchExecuteResponse": { "description": "Batch execution summary and individual results", "type": "object", "properties": { "failed": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "$ref": "#/definitions/v1.BatchExecuteResult" } }, "successful": { "type": "integer", "example": 4 }, "total_duration_ms": { "type": "integer", "example": 3000 }, "total_requests": { "type": "integer", "example": 5 } } }, "v1.BatchExecuteResult": { "description": "Individual integration execution result", "type": "object", "properties": { "duration_ms": { "type": "integer", "example": 1500 }, "error": { "type": "string", "example": "" }, "slug": { "type": "string", "example": "app1" }, "started_at": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "success": { "type": "boolean", "example": true } } }, "v1.BranchBulkData": { "description": "Statistics from bulk branch operation", "type": "object", "properties": { "errors": { "description": "Details of failures (iv_id -\u003e error)", "type": "object" }, "failed": { "description": "Number of failed items\n@Example 5", "type": "integer", "example": 5 }, "succeeded": { "description": "Number of successfully processed items\n@Example 95", "type": "integer", "example": 95 } } }, "v1.BranchBulkRequest": { "description": "Request for bulk branch operations", "type": "object", "required": [ "branches", "mode" ], "properties": { "branches": { "description": "Branches to process\n@maxItems 1000", "type": "array", "maxItems": 1000, "minItems": 1, "items": { "type": "object" } }, "mode": { "description": "Operation mode: \"create\", \"update\", or \"upsert\"\n@Example upsert\n@Enum create,update,upsert", "type": "string", "enum": [ "create", "update", "upsert" ], "example": "upsert" }, "skip_validation": { "description": "Skip validation for faster processing (use with caution)", "type": "boolean", "example": false } } }, "v1.BranchBulkResponse": { "description": "Result of bulk branch operation", "type": "object", "properties": { "data": { "description": "Operation results", "allOf": [ { "$ref": "#/definitions/v1.BranchBulkData" } ] }, "message": { "description": "Human-readable summary message\n@Example Processed 100 branches successfully", "type": "string", "example": "Processed 100 branches successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.BranchCreateData": { "description": "Identifiers for newly created branch", "type": "object", "properties": { "id": { "description": "@Description Database record ID\n@Example \"xc9wk3n8p2q4r5t6\"", "type": "string" }, "iv_id": { "description": "@Description Internal branch ID\n@Example \"BR-2024-001\"", "type": "string" } } }, "v1.BranchCreateResponse": { "description": "Response returned after successful branch creation", "type": "object", "properties": { "data": { "description": "@Description Created branch data", "allOf": [ { "$ref": "#/definitions/v1.BranchCreateData" } ] }, "message": { "description": "@Description Human-readable success message\n@Example \"Branch created successfully\"", "type": "string" }, "success": { "description": "@Description Operation success indicator\n@Example true", "type": "boolean" }, "timestamp": { "description": "@Description Response timestamp\n@Example \"2024-01-15T10:30:00Z\"", "type": "string" } } }, "v1.BranchListResponse": { "description": "Paginated list of branches with metadata", "type": "object", "properties": { "branches": { "description": "@Description Array of branch records", "type": "array", "items": { "$ref": "#/definitions/v1.BranchResponse" } }, "meta": { "description": "@Description Additional metadata", "type": "object", "additionalProperties": {} }, "pagination": { "description": "@Description Pagination information", "allOf": [ { "$ref": "#/definitions/v1.PaginationMeta" } ] } } }, "v1.BranchResponse": { "description": "Complete branch information returned in API responses", "type": "object", "properties": { "active": { "description": "@Description Whether the branch is active\n@Example true", "type": "boolean" }, "apple_maps_id": { "description": "@Description Apple Maps identifier\n@Example \"ChIJrTLr-GyuEmsRBfy61i59si0\"", "type": "string" }, "banner_image": { "description": "@Description Banner image URL\n@Example \"https://example.com/images/banner.jpg\"", "type": "string" }, "created": { "description": "@Description Record creation timestamp\n@Example \"2024-01-15T09:30:00Z\"", "type": "string" }, "email": { "description": "@Description Contact email\n@Example \"dubai@example.com\"", "type": "string" }, "google_maps_id": { "description": "@Description Google Maps identifier\n@Example \"ChIJN1t_tDeuEmsRUsoyG83frY4\"", "type": "string" }, "hash": { "description": "@Description Unique hash for change detection\n@Example \"a1b2c3d4e5f6g7h8\"", "type": "string" }, "hero_image": { "description": "@Description Hero image URL\n@Example \"https://example.com/images/hero.jpg\"", "type": "string" }, "id": { "description": "@Description Unique database identifier\n@Example \"xc9wk3n8p2q4r5t6\"", "type": "string" }, "iv_id": { "description": "@Description Internal branch identifier\n@Example \"BR-2024-001\"", "type": "string" }, "latitude": { "description": "@Description Latitude (legacy field)\n@Deprecated Use location.lat instead", "type": "number" }, "location": { "description": "@Description Geographic location", "allOf": [ { "$ref": "#/definitions/v1.Location" } ] }, "longitude": { "description": "@Description Longitude (legacy field)\n@Deprecated Use location.lon instead", "type": "number" }, "name_ar": { "description": "@Description Branch name in Arabic\n@Example \"فرع دبي\"", "type": "string" }, "name_en": { "description": "@Description Branch name in English\n@Example \"Dubai Branch\"", "type": "string" }, "organization_id": { "description": "@Description Organization this branch belongs to\n@Example \"org_123456\"", "type": "string" }, "photos": { "description": "@Description Array of photo URLs\n@Example [\"https://example.com/photo1.jpg\", \"https://example.com/photo2.jpg\"]", "type": "array", "items": { "type": "string" } }, "status": { "description": "@Description Current branch status\n@Example \"Published\"", "type": "string" }, "updated": { "description": "@Description Last update timestamp\n@Example \"2024-01-15T10:45:00Z\"", "type": "string" }, "vendor_ids": { "description": "@Description Third-party vendor IDs associated with the branch\n@Example {\"hungerstation\": \"12345\"}", "type": "object", "additionalProperties": { "type": "string" } }, "working_hours": { "description": "@Description Weekly operating hours", "allOf": [ { "$ref": "#/definitions/v1.WorkingHours" } ] }, "working_hours_periods": { "description": "@Description Weekly operating hours in canonical multi-period format", "type": "array", "items": { "$ref": "#/definitions/v1.WorkingHoursPeriod" } } } }, "v1.BranchUpdateData": { "description": "Identifier for updated branch", "type": "object", "properties": { "iv_id": { "description": "@Description Internal branch ID\n@Example \"BR-2024-001\"", "type": "string" } } }, "v1.BranchUpdateResponse": { "description": "Response returned after successful branch update", "type": "object", "properties": { "data": { "description": "@Description Updated branch data", "allOf": [ { "$ref": "#/definitions/v1.BranchUpdateData" } ] }, "message": { "description": "@Description Human-readable success message\n@Example \"Branch updated successfully\"", "type": "string" }, "success": { "description": "@Description Operation success indicator\n@Example true", "type": "boolean" }, "timestamp": { "description": "@Description Response timestamp\n@Example \"2024-01-15T11:00:00Z\"", "type": "string" } } }, "v1.BranchWorkingHoursRequest": { "description": "Body must be JSON with a top-level `working_hours` key. The value is either a weekday-keyed object (`WorkingHours`) or a canonical array of `WorkingHoursPeriod` (multi-period and overnight supported).", "type": "object", "properties": { "working_hours": { "description": "Weekday-keyed object (`WorkingHours`) or canonical `[]WorkingHoursPeriod` array (see docsite `api/branches`).", "type": "object" } } }, "v1.BranchWorkingHoursResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/v1.BranchWorkingHoursResponseData" }, "message": { "type": "string" }, "success": { "type": "boolean" }, "timestamp": { "type": "string" } } }, "v1.BranchWorkingHoursResponseData": { "type": "object", "properties": { "iv_id": { "type": "string" }, "working_hours": { "type": "array", "items": { "$ref": "#/definitions/v1.WorkingHoursPeriod" } } } }, "v1.BrandBulkData": { "description": "Statistics from bulk brand operation", "type": "object", "properties": { "errors": { "description": "Details of failures (brand_code -\u003e error)", "type": "object" }, "failed": { "description": "Number of failed items\n@Example 5", "type": "integer", "example": 5 }, "succeeded": { "description": "Number of successfully processed items\n@Example 95", "type": "integer", "example": 95 } } }, "v1.BrandBulkRequest": { "description": "Request for bulk brand operations", "type": "object", "required": [ "brands", "mode" ], "properties": { "brands": { "description": "Brands to process\n@maxItems 1000", "type": "array", "maxItems": 1000, "minItems": 1, "items": { "type": "object" } }, "mode": { "description": "Operation mode: \"create\", \"update\", or \"upsert\"\n@Example upsert\n@Enum create,update,upsert", "type": "string", "enum": [ "create", "update", "upsert" ], "example": "upsert" }, "skip_validation": { "description": "Skip validation for faster processing (use with caution)", "type": "boolean", "example": false } } }, "v1.BrandBulkResponse": { "description": "Result of bulk brand operation", "type": "object", "properties": { "data": { "description": "Operation results", "allOf": [ { "$ref": "#/definitions/v1.BrandBulkData" } ] }, "message": { "description": "Human-readable summary message\n@Example Processed 100 brands successfully", "type": "string", "example": "Processed 100 brands successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.BrandCreateData": { "description": "Minimal brand data returned after creation", "type": "object", "properties": { "brand_code": { "description": "Brand code (external identifier)\n@Example BR001", "type": "string", "example": "BR001" }, "id": { "description": "System-generated internal ID\n@Example r1234567890abcdef", "type": "string", "example": "r1234567890abcdef" } } }, "v1.BrandCreateResponse": { "description": "Response returned after successful brand creation", "type": "object", "properties": { "data": { "description": "Created brand data", "allOf": [ { "$ref": "#/definitions/v1.BrandCreateData" } ] }, "message": { "description": "Human-readable success message\n@Example Brand created successfully", "type": "string", "example": "Brand created successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.BrandListResponse": { "description": "Paginated list of brands with filtering and metadata", "type": "object", "properties": { "count": { "description": "Number of items in current page\n@Example 10", "type": "integer", "example": 10 }, "data": { "description": "Array of brand records", "type": "array", "items": { "$ref": "#/definitions/v1.BrandResponse" } }, "has_next": { "description": "Indicates if more pages are available\n@Example true", "type": "boolean", "example": true }, "limit": { "description": "Items per page\n@Example 20\n@minimum 1\n@maximum 100", "type": "integer", "example": 20 }, "meta": { "description": "Additional metadata including applied filters", "type": "object" }, "page": { "description": "Current page number (1-indexed)\n@Example 1\n@minimum 1", "type": "integer", "example": 1 }, "total_count": { "description": "Total number of items across all pages\n@Example 50", "type": "integer", "example": 50 } } }, "v1.BrandProductsUpdateRequest": { "description": "Request to update brand's associated products", "type": "object", "required": [ "products" ], "properties": { "mode": { "description": "Update mode: \"replace\" (default) or \"append\"\n@Example replace\n@Enum replace,append", "type": "string", "enum": [ "replace", "append" ], "example": "replace" }, "products": { "description": "Product IDs to associate with brand\n@Example [\"prd_123\", \"prd_456\", \"prd_789\"]", "type": "array", "items": { "type": "string" } } } }, "v1.BrandRequest": { "description": "Brand information for creation or update operations Supports multi-language content (Arabic/English)", "type": "object", "required": [ "brand_code" ], "properties": { "brand_code": { "description": "Brand code - unique identifier within organization\n@Required\n@Example BR001\n@maxLength 50", "type": "string", "maxLength": 50, "minLength": 1, "example": "BR001" }, "image": { "description": "Brand logo/image URL\n@Example https://cdn.example.com/brands/logo-123.png", "type": "string", "example": "https://cdn.example.com/brands/logo-123.png" }, "name_ar": { "description": "Brand name in Arabic\n@Example علامة تجارية ممتازة\n@maxLength 200", "type": "string", "maxLength": 200, "example": "علامة تجارية ممتازة" }, "name_en": { "description": "Brand name in English\n@Example Premium Brand\n@maxLength 200", "type": "string", "maxLength": 200, "example": "Premium Brand" }, "products": { "description": "Associated product IDs\n@Example [\"prd_123\", \"prd_456\", \"prd_789\"]", "type": "array", "items": { "type": "string" } } } }, "v1.BrandResponse": { "description": "Full brand details including runtime-generated fields", "type": "object", "properties": { "brand_code": { "description": "Brand code\n@Example BR001", "type": "string", "example": "BR001" }, "created": { "description": "Record creation timestamp (UTC)\n@Example 2024-01-01T00:00:00Z", "type": "string", "example": "2024-01-01T00:00:00Z" }, "id": { "description": "Brand code (used as external identifier)\n@Example BR001", "type": "string", "example": "BR001" }, "image": { "description": "Brand image URL\n@Example https://cdn.example.com/brands/logo-123.png", "type": "string", "example": "https://cdn.example.com/brands/logo-123.png" }, "name_ar": { "description": "Brand name in Arabic\n@Example علامة تجارية ممتازة", "type": "string", "example": "علامة تجارية ممتازة" }, "name_en": { "description": "Brand name in English\n@Example Premium Brand", "type": "string", "example": "Premium Brand" }, "organization_id": { "description": "Organization identifier for multi-tenancy\n@Example org_abc123", "type": "string", "example": "org_abc123" }, "product_count": { "description": "Total number of associated products\n@Example 15", "type": "integer", "example": 15 }, "products": { "description": "Associated product IDs\n@Example [\"prd_123\", \"prd_456\"]", "type": "array", "items": { "type": "string" } }, "updated": { "description": "Last update timestamp (UTC)\n@Example 2024-01-02T12:30:45Z", "type": "string", "example": "2024-01-02T12:30:45Z" } } }, "v1.BrandUpdateData": { "description": "Reference to updated brand", "type": "object", "properties": { "brand_code": { "description": "Brand code of updated brand\n@Example BR001", "type": "string", "example": "BR001" } } }, "v1.BrandUpdateResponse": { "description": "Response returned after successful brand update", "type": "object", "properties": { "data": { "description": "Updated brand reference", "allOf": [ { "$ref": "#/definitions/v1.BrandUpdateData" } ] }, "message": { "description": "Human-readable success message\n@Example Brand updated successfully", "type": "string", "example": "Brand updated successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.CategoryCreateData": { "description": "Minimal category data returned after creation", "type": "object", "properties": { "code": { "description": "Category code (external identifier)\n@Example CAT001", "type": "string", "example": "CAT001" }, "id": { "description": "System-generated internal ID\n@Example r1234567890abcdef", "type": "string", "example": "r1234567890abcdef" } } }, "v1.CategoryCreateResponse": { "description": "Response returned after successful category creation", "type": "object", "properties": { "data": { "description": "Created category data", "allOf": [ { "$ref": "#/definitions/v1.CategoryCreateData" } ] }, "message": { "description": "Human-readable success message\n@Example Category created successfully", "type": "string", "example": "Category created successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.CategoryListResponse": { "description": "Paginated list of categories with filtering", "type": "object", "properties": { "count": { "description": "Number of items in current page\n@Example 10", "type": "integer", "example": 10 }, "data": { "description": "Array of category records", "type": "array", "items": { "$ref": "#/definitions/v1.CategoryResponse" } }, "has_next": { "description": "Indicates if more pages are available\n@Example true", "type": "boolean", "example": true }, "limit": { "description": "Items per page\n@Example 20\n@minimum 1\n@maximum 100", "type": "integer", "example": 20 }, "meta": { "description": "Additional metadata", "type": "object" }, "page": { "description": "Current page number (1-indexed)\n@Example 1\n@minimum 1", "type": "integer", "example": 1 }, "total_count": { "description": "Total number of items across all pages\n@Example 50", "type": "integer", "example": 50 } } }, "v1.CategoryMoveRequest": { "description": "Request to move category to new parent", "type": "object", "properties": { "new_parent": { "description": "New parent category code (empty for root)\n@Example CAT002", "type": "string", "maxLength": 50, "example": "CAT002" } } }, "v1.CategoryProductsUpdateRequest": { "description": "Request to update category's associated products", "type": "object", "required": [ "product_ids" ], "properties": { "mode": { "description": "Update mode: \"replace\" (default) or \"append\"\n@Example replace\n@Enum replace,append", "type": "string", "enum": [ "replace", "append" ], "example": "replace" }, "product_ids": { "description": "Product IDs to associate with category\n@Example [\"prd_123\", \"prd_456\", \"prd_789\"]", "type": "array", "items": { "type": "string" } } } }, "v1.CategoryRequest": { "description": "Category information for creation or update operations Supports hierarchical structure and multi-language content", "type": "object", "required": [ "code" ], "properties": { "code": { "description": "Category code - unique identifier within organization\n@Required\n@Example CAT001\n@maxLength 50", "type": "string", "maxLength": 50, "minLength": 1, "example": "CAT001" }, "image": { "description": "Category image URL\n@Example https://cdn.example.com/categories/electronics.png", "type": "string", "example": "https://cdn.example.com/categories/electronics.png" }, "name_ar": { "description": "Category name in Arabic\n@Example إلكترونيات\n@maxLength 200", "type": "string", "maxLength": 200, "example": "إلكترونيات" }, "name_en": { "description": "Category name in English\n@Example Electronics\n@maxLength 200", "type": "string", "maxLength": 200, "example": "Electronics" }, "parent": { "description": "Parent category code (empty for root categories)\n@Example ROOT001", "type": "string", "maxLength": 50, "example": "ROOT001" }, "product_ids": { "description": "Associated product IDs\n@Example [\"prd_123\", \"prd_456\", \"prd_789\"]", "type": "array", "items": { "type": "string" } } } }, "v1.CategoryResponse": { "description": "Full category details including hierarchical relationships", "type": "object", "properties": { "child_count": { "description": "Number of immediate children\n@Example 5", "type": "integer", "example": 5 }, "children": { "description": "Child category codes\n@Example [\"CAT002\", \"CAT003\"]", "type": "array", "items": { "type": "string" } }, "code": { "description": "Category code\n@Example CAT001", "type": "string", "example": "CAT001" }, "created": { "description": "Record creation timestamp (UTC)\n@Example 2024-01-01T00:00:00Z", "type": "string", "example": "2024-01-01T00:00:00Z" }, "depth": { "description": "Category depth in hierarchy (0 for root)\n@Example 2", "type": "integer", "example": 2 }, "id": { "description": "Category code (used as external identifier)\n@Example CAT001", "type": "string", "example": "CAT001" }, "image": { "description": "Category image URL\n@Example https://cdn.example.com/categories/electronics.png", "type": "string", "example": "https://cdn.example.com/categories/electronics.png" }, "name_ar": { "description": "Category name in Arabic\n@Example إلكترونيات", "type": "string", "example": "إلكترونيات" }, "name_en": { "description": "Category name in English\n@Example Electronics", "type": "string", "example": "Electronics" }, "organization_id": { "description": "Organization identifier for multi-tenancy\n@Example org_abc123", "type": "string", "example": "org_abc123" }, "parent": { "description": "Parent category code\n@Example ROOT001", "type": "string", "example": "ROOT001" }, "path": { "description": "Full path from root to this category\n@Example [\"ROOT001\", \"CAT001\"]", "type": "array", "items": { "type": "string" } }, "product_count": { "description": "Total number of associated products\n@Example 25", "type": "integer", "example": 25 }, "product_ids": { "description": "Associated product IDs\n@Example [\"prd_123\", \"prd_456\"]", "type": "array", "items": { "type": "string" } }, "updated": { "description": "Last update timestamp (UTC)\n@Example 2024-01-02T12:30:45Z", "type": "string", "example": "2024-01-02T12:30:45Z" } } }, "v1.CategoryTreeResponse": { "description": "Hierarchical category structure with full tree", "type": "object", "properties": { "child_count": { "description": "Number of immediate children\n@Example 5", "type": "integer", "example": 5 }, "children": { "description": "Nested child categories", "type": "array", "items": { "$ref": "#/definitions/v1.CategoryTreeResponse" } }, "code": { "description": "Category code\n@Example CAT001", "type": "string", "example": "CAT001" }, "created": { "description": "Record creation timestamp (UTC)\n@Example 2024-01-01T00:00:00Z", "type": "string", "example": "2024-01-01T00:00:00Z" }, "depth": { "description": "Category depth in hierarchy (0 for root)\n@Example 2", "type": "integer", "example": 2 }, "id": { "description": "Category code (used as external identifier)\n@Example CAT001", "type": "string", "example": "CAT001" }, "image": { "description": "Category image URL\n@Example https://cdn.example.com/categories/electronics.png", "type": "string", "example": "https://cdn.example.com/categories/electronics.png" }, "name_ar": { "description": "Category name in Arabic\n@Example إلكترونيات", "type": "string", "example": "إلكترونيات" }, "name_en": { "description": "Category name in English\n@Example Electronics", "type": "string", "example": "Electronics" }, "organization_id": { "description": "Organization identifier for multi-tenancy\n@Example org_abc123", "type": "string", "example": "org_abc123" }, "parent": { "description": "Parent category code\n@Example ROOT001", "type": "string", "example": "ROOT001" }, "path": { "description": "Full path from root to this category\n@Example [\"ROOT001\", \"CAT001\"]", "type": "array", "items": { "type": "string" } }, "product_count": { "description": "Total number of associated products\n@Example 25", "type": "integer", "example": 25 }, "product_ids": { "description": "Associated product IDs\n@Example [\"prd_123\", \"prd_456\"]", "type": "array", "items": { "type": "string" } }, "updated": { "description": "Last update timestamp (UTC)\n@Example 2024-01-02T12:30:45Z", "type": "string", "example": "2024-01-02T12:30:45Z" } } }, "v1.CategoryUpdateData": { "description": "Reference to updated category", "type": "object", "properties": { "code": { "description": "Category code of updated category\n@Example CAT001", "type": "string", "example": "CAT001" } } }, "v1.CategoryUpdateResponse": { "description": "Response returned after successful category update", "type": "object", "properties": { "data": { "description": "Updated category reference", "allOf": [ { "$ref": "#/definitions/v1.CategoryUpdateData" } ] }, "message": { "description": "Human-readable success message\n@Example Category updated successfully", "type": "string", "example": "Category updated successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.CustomerGroupRequest": { "type": "object", "required": [ "name" ], "properties": { "description": { "type": "string" }, "name": { "type": "string", "maxLength": 100, "minLength": 1 } } }, "v1.CustomerGroupResponse": { "type": "object", "properties": { "created": { "$ref": "#/definitions/types.DateTime" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "updated": { "$ref": "#/definitions/types.DateTime" } } }, "v1.CustomerListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/definitions/v1.CustomerResponse" } }, "has_next": { "type": "boolean" }, "limit": { "type": "integer" }, "meta": { "type": "object", "additionalProperties": {} }, "page": { "type": "integer" }, "total_count": { "type": "integer" } } }, "v1.CustomerRequest": { "type": "object", "required": [ "email", "first_name", "last_name", "phone", "status", "type" ], "properties": { "birthdate": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string", "maxLength": 100, "minLength": 1 }, "gender": { "type": "string", "enum": [ "male", "female", "other" ] }, "last_name": { "type": "string", "maxLength": 100, "minLength": 1 }, "phone": { "type": "string", "maxLength": 20, "minLength": 10 }, "status": { "type": "string", "enum": [ "active", "inactive", "pending", "banned" ] }, "type": { "type": "string", "enum": [ "individual", "corporate", "vip" ] } } }, "v1.CustomerResponse": { "type": "object", "properties": { "birthdate": { "type": "string" }, "created": { "$ref": "#/definitions/types.DateTime" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "gender": { "type": "string" }, "id": { "type": "string" }, "last_name": { "type": "string" }, "organization_id": { "type": "string" }, "phone": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" }, "updated": { "$ref": "#/definitions/types.DateTime" } } }, "v1.CustomerSearchRequest": { "type": "object", "properties": { "created_from": { "type": "string" }, "created_to": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "phone": { "type": "string" }, "query": { "type": "string" }, "status": { "type": "array", "items": { "type": "string" } }, "type": { "type": "array", "items": { "type": "string" } } } }, "v1.DaySchedule": { "description": "Daily operating schedule", "type": "object", "properties": { "close": { "description": "@Description Closing time in HH:MM format\n@Example \"18:00\"\n@Pattern ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$", "type": "string" }, "closed": { "description": "@Description Whether the branch is closed on this day\n@Example false", "type": "boolean" }, "open": { "description": "@Description Opening time in HH:MM format\n@Example \"09:00\"\n@Pattern ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$", "type": "string" }, "periods": { "description": "@Description Optional split shifts: `{ \"periods\": [ {\"open\",\"close\"}, ... ] }` for this weekday in object form", "type": "array", "items": { "$ref": "#/definitions/v1.DayTimeWindow" } } } }, "v1.DayTimeWindow": { "description": "Single HH:MM window within a day (split shifts)", "type": "object", "properties": { "close": { "description": "@Description Closing time in HH:MM format\n@Example \"16:45\"", "type": "string" }, "open": { "description": "@Description Opening time in HH:MM format\n@Example \"12:30\"", "type": "string" } } }, "v1.DetailedErrorResponse": { "description": "Comprehensive error response with validation details", "type": "object", "properties": { "code": { "description": "@Description HTTP status code\n@Example 400", "type": "integer" }, "details": { "description": "@Description Field-specific validation errors", "type": "array", "items": { "$ref": "#/definitions/v1.ValidationError" } }, "error": { "description": "@Description Main error message\n@Example \"Validation failed\"", "type": "string" }, "request_id": { "description": "@Description Unique request identifier for debugging\n@Example \"req_1705315800000000000_12345\"", "type": "string" }, "timestamp": { "description": "@Description Error timestamp\n@Example \"2024-01-15T10:30:00Z\"", "type": "string" } } }, "v1.EmailMarketingSendRequest": { "type": "object", "properties": { "content_mode": { "type": "string" }, "pdf_base64": { "type": "string" }, "pdf_filename": { "type": "string" }, "subject": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "top_n": { "type": "integer" } } }, "v1.ErrorResponse": { "description": "Standard error response format", "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "details": {}, "error": { "type": "string", "example": "Post not found" }, "message": { "type": "string", "example": "Post not found" } } }, "v1.GenericBulkData": { "description": "Statistics from bulk operation", "type": "object", "properties": { "errors": { "description": "Details of failures (generic_code -\u003e error)", "type": "object" }, "failed": { "description": "Number of failed items\n@Example 5", "type": "integer", "example": 5 }, "succeeded": { "description": "Number of successfully processed items\n@Example 95", "type": "integer", "example": 95 } } }, "v1.GenericBulkRequest": { "description": "Request for bulk generic operations", "type": "object", "required": [ "generics", "mode" ], "properties": { "generics": { "description": "Generics to process\n@maxItems 1000", "type": "array", "maxItems": 1000, "minItems": 1, "items": { "type": "object" } }, "mode": { "description": "Operation mode: \"create\", \"update\", or \"upsert\"\n@Example upsert\n@Enum create,update,upsert", "type": "string", "enum": [ "create", "update", "upsert" ], "example": "upsert" }, "skip_validation": { "description": "Skip validation for faster processing (use with caution)\n@Example false", "type": "boolean", "example": false } } }, "v1.GenericBulkResponse": { "description": "Result of bulk generic operation", "type": "object", "properties": { "data": { "description": "Operation results", "allOf": [ { "$ref": "#/definitions/v1.GenericBulkData" } ] }, "message": { "description": "Human-readable summary message\n@Example Processed 100 generics successfully", "type": "string", "example": "Processed 100 generics successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.GenericCreateData": { "description": "Minimal generic data returned after creation", "type": "object", "properties": { "generic_code": { "description": "Generic code (external identifier)\n@Example GEN001", "type": "string", "example": "GEN001" }, "id": { "description": "System-generated internal ID\n@Example r1234567890abcdef", "type": "string", "example": "r1234567890abcdef" } } }, "v1.GenericCreateResponse": { "description": "Response returned after successful generic medicine creation", "type": "object", "properties": { "data": { "description": "Created generic data", "allOf": [ { "$ref": "#/definitions/v1.GenericCreateData" } ] }, "message": { "description": "Human-readable success message\n@Example Generic medicine created successfully", "type": "string", "example": "Generic medicine created successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.GenericListResponse": { "description": "Paginated list of generic medicines with metadata", "type": "object", "properties": { "count": { "description": "Number of items in current page\n@Example 10", "type": "integer", "example": 10 }, "data": { "description": "Array of generic records", "type": "array", "items": { "$ref": "#/definitions/v1.GenericResponse" } }, "has_next": { "description": "Indicates if more pages are available\n@Example true", "type": "boolean", "example": true }, "limit": { "description": "Items per page\n@Example 25\n@minimum 1\n@maximum 100", "type": "integer", "example": 25 }, "meta": { "description": "Additional metadata", "type": "object" }, "page": { "description": "Current page number (1-indexed)\n@Example 1\n@minimum 1", "type": "integer", "example": 1 }, "total_count": { "description": "Total number of items across all pages\n@Example 100", "type": "integer", "example": 100 } } }, "v1.GenericRequest": { "description": "Generic medicine information for pharmaceutical catalog management Supports multi-language content and product associations", "type": "object", "required": [ "generic_code" ], "properties": { "generic_code": { "description": "Generic code - unique identifier within the runtime\n@Required\n@Example GEN001\n@maxLength 50", "type": "string", "maxLength": 50, "minLength": 1, "example": "GEN001" }, "name_ar": { "description": "Generic name in Arabic\n@Example باراسيتامول\n@maxLength 200", "type": "string", "maxLength": 200, "example": "باراسيتامول" }, "name_en": { "description": "Generic name in English (must be globally unique)\n@Example Paracetamol\n@maxLength 200", "type": "string", "maxLength": 200, "example": "Paracetamol" }, "products": { "description": "Associated product IDs\n@Example [\"prd_123\", \"prd_456\", \"prd_789\"]", "type": "array", "items": { "type": "string" } } } }, "v1.GenericResponse": { "description": "Full generic medicine details with metadata and associations", "type": "object", "properties": { "common_brands": { "description": "Common brand names using this generic\n@Example [\"Tylenol\", \"Panadol\"]", "type": "array", "items": { "type": "string" } }, "created": { "description": "Record creation timestamp (UTC)\n@Example 2024-01-01T00:00:00Z", "type": "string", "example": "2024-01-01T00:00:00Z" }, "generic_code": { "description": "Generic code\n@Example GEN001", "type": "string", "example": "GEN001" }, "id": { "description": "Generic code (used as external identifier)\n@Example GEN001", "type": "string", "example": "GEN001" }, "name_ar": { "description": "Generic name in Arabic\n@Example باراسيتامول", "type": "string", "example": "باراسيتامول" }, "name_en": { "description": "Generic name in English\n@Example Paracetamol", "type": "string", "example": "Paracetamol" }, "organization_id": { "description": "Organization identifier for multi-tenancy\n@Example org_abc123", "type": "string", "example": "org_abc123" }, "product_count": { "description": "Total number of associated products\n@Example 15", "type": "integer", "example": 15 }, "products": { "description": "Associated product IDs\n@Example [\"prd_123\", \"prd_456\"]", "type": "array", "items": { "type": "string" } }, "updated": { "description": "Last update timestamp (UTC)\n@Example 2024-01-02T12:30:45Z", "type": "string", "example": "2024-01-02T12:30:45Z" } } }, "v1.GenericUpdateData": { "description": "Reference to updated generic", "type": "object", "properties": { "generic_code": { "description": "Generic code of updated medicine\n@Example GEN001", "type": "string", "example": "GEN001" } } }, "v1.GenericUpdateResponse": { "description": "Response returned after successful generic medicine update", "type": "object", "properties": { "data": { "description": "Updated generic reference", "allOf": [ { "$ref": "#/definitions/v1.GenericUpdateData" } ] }, "message": { "description": "Human-readable success message\n@Example Generic medicine updated successfully", "type": "string", "example": "Generic medicine updated successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.HealthResponse": { "description": "Basic health status for load balancers and uptime monitoring", "type": "object", "properties": { "environment": { "type": "string", "example": "production" }, "status": { "type": "string", "example": "healthy" }, "timestamp": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "version": { "type": "string", "example": "1.0.0" } } }, "v1.IntegrationConfigResponse": { "description": "Integration configuration details with sanitized settings", "type": "object", "properties": { "base_url": { "type": "string", "example": "https://api.example.com" }, "configured_at": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "custom_config": { "type": "object" }, "headers_count": { "type": "integer", "example": 5 }, "name": { "type": "string", "example": "App Name" }, "organization_id": { "type": "string", "example": "org_123" }, "params_count": { "type": "integer", "example": 3 }, "slug": { "type": "string", "example": "app-slug" }, "supports_staging": { "type": "boolean", "example": true }, "type": { "type": "string", "example": "ecommerce" }, "version": { "type": "string", "example": "1.0.0" } } }, "v1.IntegrationExecuteRequest": { "description": "Optional parameters for integration execution", "type": "object", "properties": { "dry_run": { "type": "boolean", "example": false }, "full_sync": { "type": "boolean", "example": false }, "reload_config": { "type": "boolean", "example": false }, "timeout_seconds": { "type": "integer", "example": 120 } } }, "v1.IntegrationExecuteResponse": { "description": "Integration execution result with performance telemetry", "type": "object", "properties": { "duration_ms": { "type": "integer", "example": 1500 }, "error": { "type": "string", "example": "" }, "executed_at": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "message": { "type": "string" }, "processed_ids": { "type": "array", "items": { "type": "string" }, "example": [ "[\"id1\"", "\"id2\"]" ] }, "success": { "type": "boolean", "example": true }, "target_response": { "type": "object" }, "telemetry": { "type": "object" } } }, "v1.IntegrationListResponse": { "description": "List of available integrations for an organization", "type": "object", "properties": { "count": { "type": "integer", "example": 10 }, "integrations": { "type": "array", "items": { "$ref": "#/definitions/v1.IntegrationSummary" } } } }, "v1.IntegrationSummary": { "description": "Summary information for an integration", "type": "object", "properties": { "enabled": { "type": "boolean", "example": true }, "last_sync": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "name": { "type": "string", "example": "App Name" }, "slug": { "type": "string", "example": "app-slug" }, "type": { "type": "string", "example": "ecommerce" } } }, "v1.Location": { "description": "Geographic location with latitude and longitude", "type": "object", "required": [ "lat", "lon" ], "properties": { "lat": { "description": "@Description Latitude coordinate\n@Example 25.2048\n@Minimum -90\n@Maximum 90", "type": "number", "maximum": 90, "minimum": -90 }, "lon": { "description": "@Description Longitude coordinate\n@Example 55.2708\n@Minimum -180\n@Maximum 180", "type": "number", "maximum": 180, "minimum": -180 } } }, "v1.Meta": { "description": "Additional metadata for responses", "type": "object", "additionalProperties": {} }, "v1.MetricsResponse": { "description": "Comprehensive runtime telemetry including store, staging, and runtime performance", "type": "object", "properties": { "measured": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "runtime": { "$ref": "#/definitions/v1.RuntimeMetrics" }, "staging": { "type": "object" }, "store": { "type": "object" }, "system": { "type": "object" }, "version": { "type": "string", "example": "1.0.0" } } }, "v1.PaginationMeta": { "description": "Pagination metadata for list responses", "type": "object", "properties": { "has_next": { "description": "@Description Whether next page exists\n@Example true", "type": "boolean" }, "has_prev": { "description": "@Description Whether previous page exists\n@Example false", "type": "boolean" }, "page": { "description": "@Description Current page number\n@Example 1", "type": "integer" }, "per_page": { "description": "@Description Items per page\n@Example 20", "type": "integer" }, "total": { "description": "@Description Total number of items\n@Example 150", "type": "integer" }, "total_pages": { "description": "@Description Total number of pages\n@Example 8", "type": "integer" } } }, "v1.PingResponse": { "description": "Simple ping response structure", "type": "object", "properties": { "message": { "description": "Message contains the ping response", "type": "string", "example": "pong" }, "timestamp": { "description": "Timestamp of the ping response", "type": "string", "example": "2024-01-15T10:30:00Z" } } }, "v1.PostListResponse": { "description": "Paginated list of posts with metadata", "type": "object", "properties": { "meta": { "type": "object", "additionalProperties": {} }, "pagination": { "$ref": "#/definitions/v1.PaginationMeta" }, "posts": { "type": "array", "items": { "$ref": "#/definitions/v1.PostResponse" } } } }, "v1.PostResponse": { "description": "Complete post information with computed fields", "type": "object", "properties": { "attachment": { "type": "string", "example": "brief.pdf" }, "author": { "type": "string", "example": "rel_user_id_or_legacy" }, "author_name": { "type": "string", "example": "Linkit Team" }, "category": { "type": "string", "example": "Updates" }, "content": { "type": "string", "example": "\u003cp\u003eFull HTML content...\u003c/p\u003e" }, "created": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "excerpt": { "type": "string", "example": "A brief introduction to Go generics..." }, "featured_image": { "type": "string", "example": "https://example.com/image.jpg" }, "featured_video": { "type": "string", "example": "" }, "id": { "type": "string", "example": "r1234567" }, "is_featured": { "type": "boolean", "example": true }, "is_newsletter": { "type": "boolean", "example": false }, "newsletter_sent_at": { "type": "string", "example": "2024-01-15T10:00:00Z" }, "reading_time": { "type": "integer", "example": 5 }, "seo_description": { "type": "string", "example": "Learn Go generics with practical examples" }, "seo_title": { "type": "string", "example": "Go Generics Guide | Best Practices" }, "slug": { "type": "string", "example": "understanding-go-generics" }, "status": { "type": "string", "example": "Published" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "golang", "generics", "tutorial" ] }, "title": { "type": "string", "example": "Understanding Go Generics" }, "updated": { "type": "string", "example": "2024-01-02T00:00:00Z" } } }, "v1.ProductBulkData": { "description": "Statistics from bulk product operation", "type": "object", "properties": { "errors": { "description": "Details of failures (iv_id -\u003e error)", "type": "object" }, "failed": { "description": "Number of failed items\n@Example 5", "type": "integer", "example": 5 }, "succeeded": { "description": "Number of successfully processed items\n@Example 95", "type": "integer", "example": 95 } } }, "v1.ProductBulkRequest": { "description": "Request for bulk product operations", "type": "object", "required": [ "mode", "products" ], "properties": { "mode": { "description": "Operation mode: \"create\", \"update\", or \"upsert\"\n@Example upsert\n@Enum create,update,upsert", "type": "string", "enum": [ "create", "update", "upsert" ], "example": "upsert" }, "products": { "description": "Products to process\n@maxItems 1000", "type": "array", "maxItems": 1000, "minItems": 1, "items": { "type": "object" } }, "skip_validation": { "description": "Skip validation for faster processing (use with caution)", "type": "boolean", "example": false } } }, "v1.ProductBulkResponse": { "description": "Result of bulk product operation", "type": "object", "properties": { "data": { "description": "Operation results", "allOf": [ { "$ref": "#/definitions/v1.ProductBulkData" } ] }, "message": { "description": "Human-readable summary message\n@Example Processed 100 products successfully", "type": "string", "example": "Processed 100 products successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.ProductCreateData": { "description": "Minimal product data returned after creation", "type": "object", "properties": { "id": { "description": "System-generated product ID\n@Example prd_1234567890123456", "type": "string", "example": "prd_1234567890123456" }, "iv_id": { "description": "Internal Vendor ID\n@Example IV123456", "type": "string", "example": "IV123456" } } }, "v1.ProductCreateResponse": { "description": "Response returned after successful product creation", "type": "object", "properties": { "data": { "description": "Created product data", "allOf": [ { "$ref": "#/definitions/v1.ProductCreateData" } ] }, "message": { "description": "Human-readable success message\n@Example Product created successfully", "type": "string", "example": "Product created successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.ProductError": { "description": "Standard error response for product operations", "type": "object", "properties": { "code": { "description": "HTTP status code\n@Example 404", "type": "integer", "example": 404 }, "details": { "description": "Additional error details", "type": "object" }, "error": { "description": "Error message\n@Example Product not found", "type": "string", "example": "Product not found" } } }, "v1.ProductListResponse": { "description": "Paginated list of products with comprehensive filtering and metadata", "type": "object", "properties": { "count": { "description": "Number of items in current page\n@Example 10", "type": "integer", "example": 10 }, "data": { "description": "Array of product records", "type": "array", "items": { "$ref": "#/definitions/v1.ProductResponse" } }, "has_next": { "description": "Indicates if more pages are available\n@Example true", "type": "boolean", "example": true }, "limit": { "description": "Items per page\n@Example 50\n@minimum 1\n@maximum 100", "type": "integer", "example": 50 }, "meta": { "description": "Additional metadata including filters applied", "type": "object" }, "page": { "description": "Current page number (1-indexed)\n@Example 1\n@minimum 1", "type": "integer", "example": 1 }, "stats": { "description": "Aggregated statistics", "allOf": [ { "$ref": "#/definitions/v1.ProductStats" } ] }, "total_count": { "description": "Total number of items across all pages\n@Example 100", "type": "integer", "example": 100 } } }, "v1.ProductRequest": { "description": "Comprehensive product information for catalog management All fields support multi-language content (Arabic/English)", "type": "object", "required": [ "iv_id" ], "properties": { "asin": { "description": "Amazon Standard Identification Number\n@Example B08N5WRWNW", "type": "string", "example": "B08N5WRWNW" }, "average_price": { "description": "Average price before VAT\n@Example 29.99\n@minimum 0.01", "type": "number", "minimum": 0, "example": 29.99 }, "average_price_after_vat": { "description": "Average price including VAT\n@Example 34.49\n@minimum 0.01", "type": "number", "minimum": 0, "example": 34.49 }, "barcode": { "description": "Product barcode\n@Example 1234567890123", "type": "string", "example": "1234567890123" }, "brand_id": { "description": "Associated brand identifier\n@Example brand_123456", "type": "string", "maxLength": 50, "example": "brand_123456" }, "buffer": { "description": "Inventory buffer percentage\n@Example 10\n@minimum 0.01\n@maximum 100", "type": "number", "maximum": 100, "minimum": 0, "example": 10 }, "category_id": { "description": "Product category identifier\n@Example cat_electronics_456", "type": "string", "maxLength": 50, "example": "cat_electronics_456" }, "desc_ar": { "description": "Product description in Arabic\n@Example وصف تفصيلي للمنتج بالعربية", "type": "string", "maxLength": 2000, "example": "وصف تفصيلي للمنتج بالعربية" }, "desc_en": { "description": "Product description in English\n@Example Detailed product description in English", "type": "string", "maxLength": 2000, "example": "Detailed product description in English" }, "generic": { "description": "Generic medicine name\n@Example Paracetamol", "type": "string", "maxLength": 200, "example": "Paracetamol" }, "generics": { "description": "List of generic alternatives\n@Example [\"Generic1\", \"Generic2\"]", "type": "array", "items": { "type": "string" } }, "gtin": { "description": "Global Trade Item Number\n@Example 00123456789012", "type": "string", "example": "00123456789012" }, "hero_image_url": { "description": "Primary product image URL\n@Example https://cdn.example.com/products/hero-123.jpg", "type": "string", "example": "https://cdn.example.com/products/hero-123.jpg" }, "hsa_code": { "description": "Harmonized System of Arab States code\n@Example HSA123456", "type": "string", "maxLength": 20, "example": "HSA123456" }, "is_breakable": { "description": "Fragile item indicator for special handling\n@Example false", "type": "boolean", "example": false }, "is_enabled": { "description": "Product availability status\n@Example true", "type": "boolean", "example": true }, "is_fast_moving": { "description": "Fast-moving consumer goods indicator\n@Example false", "type": "boolean", "example": false }, "is_pom": { "description": "Prescription-only medicine indicator\n@Example false", "type": "boolean", "example": false }, "is_quick_commerce": { "description": "Quick commerce availability\n@Example true", "type": "boolean", "example": true }, "is_refrigerated": { "description": "Cold chain requirement indicator\n@Example false", "type": "boolean", "example": false }, "is_restricted": { "description": "Age or purchase restriction indicator\n@Example false", "type": "boolean", "example": false }, "is_shippable": { "description": "Shipping eligibility indicator\n@Example true", "type": "boolean", "example": true }, "is_wasfaty": { "description": "Wasfaty prescription runtime compatibility\n@Example false", "type": "boolean", "example": false }, "iv_id": { "description": "Internal Vendor ID - unique identifier from external runtime\n@Required\n@Example IV123456", "type": "string", "maxLength": 100, "minLength": 1, "example": "IV123456" }, "name_ar": { "description": "Product name in Arabic\n@Example منتج عالي الجودة", "type": "string", "maxLength": 500, "example": "منتج عالي الجودة" }, "name_en": { "description": "Product name in English\n@Example High Quality Product", "type": "string", "maxLength": 500, "example": "High Quality Product" }, "nsku": { "description": "National Stock Keeping Unit\n@Example NSKU-123456", "type": "string", "maxLength": 50, "example": "NSKU-123456" }, "related_skus": { "description": "Related product SKUs for cross-selling\n@Example [\"SKU123\", \"SKU456\"]", "type": "array", "items": { "type": "string" } }, "secondary_images_urls": { "description": "Additional product image URLs\n@Example [\"https://cdn.example.com/p1.jpg\", \"https://cdn.example.com/p2.jpg\"]", "type": "array", "items": { "type": "string" } }, "sfda_code": { "description": "Saudi Food and Drug Authority code\n@Example SFDA-REG-123456", "type": "string", "maxLength": 50, "example": "SFDA-REG-123456" }, "sitemap_priority": { "description": "SEO sitemap priority\n@Example 0.8\n@minimum 0.01\n@maximum 1", "type": "number", "maximum": 1, "minimum": 0, "example": 0.8 }, "vat_value": { "description": "VAT percentage value\n@Example 15\n@minimum 0.01\n@maximum 100", "type": "number", "maximum": 100, "minimum": 0, "example": 15 } } }, "v1.ProductResponse": { "description": "Full product details including runtime-generated fields and metadata", "type": "object", "properties": { "asin": { "type": "string", "example": "B08N5WRWNW" }, "average_price": { "description": "Average price before VAT\n@Example 29.99", "type": "number", "example": 29.99 }, "average_price_after_vat": { "description": "Average price including VAT\n@Example 34.49", "type": "number", "example": 34.49 }, "barcode": { "description": "Product barcode\n@Example 1234567890123", "type": "string", "example": "1234567890123" }, "brand_id": { "description": "Brand identifier\n@Example brand_123456", "type": "string", "example": "brand_123456" }, "buffer": { "description": "Inventory and SEO", "type": "number", "example": 10 }, "category_id": { "description": "Category identifier\n@Example cat_electronics_456", "type": "string", "example": "cat_electronics_456" }, "created": { "description": "Record creation timestamp (UTC)\n@Example 2024-01-01T00:00:00Z", "type": "string", "example": "2024-01-01T00:00:00Z" }, "desc_ar": { "description": "Product description in Arabic\n@Example وصف تفصيلي للمنتج", "type": "string", "example": "وصف تفصيلي للمنتج" }, "desc_en": { "description": "Product description in English\n@Example Detailed product description", "type": "string", "example": "Detailed product description" }, "generic": { "description": "Generic information", "type": "string", "example": "Paracetamol" }, "generics": { "type": "array", "items": { "type": "string" } }, "gtin": { "description": "Product codes", "type": "string", "example": "00123456789012" }, "hash": { "description": "Content hash for change detection\n@Example abc123def456ghi789", "type": "string", "example": "abc123def456ghi789" }, "hero_image_file": { "description": "Hero image file reference\n@Example file_abc123.jpg", "type": "string", "example": "file_abc123.jpg" }, "hero_image_url": { "description": "Hero image URL\n@Example https://cdn.example.com/products/hero-123.jpg", "type": "string", "example": "https://cdn.example.com/products/hero-123.jpg" }, "hsa_code": { "type": "string", "example": "HSA123456" }, "id": { "description": "System-generated unique identifier\n@Example prd_1234567890123456", "type": "string", "example": "prd_1234567890123456" }, "is_breakable": { "type": "boolean", "example": false }, "is_enabled": { "description": "Product flags", "type": "boolean", "example": true }, "is_fast_moving": { "type": "boolean", "example": false }, "is_pom": { "type": "boolean", "example": false }, "is_quick_commerce": { "type": "boolean", "example": true }, "is_refrigerated": { "type": "boolean", "example": false }, "is_restricted": { "type": "boolean", "example": false }, "is_shippable": { "type": "boolean", "example": true }, "is_wasfaty": { "type": "boolean", "example": false }, "iv_id": { "description": "Internal Vendor ID\n@Example IV123456", "type": "string", "example": "IV123456" }, "name_ar": { "description": "Product name in Arabic\n@Example منتج عالي الجودة", "type": "string", "example": "منتج عالي الجودة" }, "name_en": { "description": "Product name in English\n@Example High Quality Product", "type": "string", "example": "High Quality Product" }, "nsku": { "type": "string", "example": "NSKU-123456" }, "organization_id": { "description": "Organization identifier for multi-tenancy\n@Example org_abc123", "type": "string", "example": "org_abc123" }, "related_skus": { "type": "array", "items": { "type": "string" } }, "secondary_images_files": { "description": "Secondary image file references\n@Example [\"file_def456.jpg\", \"file_ghi789.jpg\"]", "type": "array", "items": { "type": "string" } }, "secondary_images_urls": { "description": "Secondary image URLs\n@Example [\"https://cdn.example.com/p1.jpg\", \"https://cdn.example.com/p2.jpg\"]", "type": "array", "items": { "type": "string" } }, "sfda_code": { "type": "string", "example": "SFDA-REG-123456" }, "sitemap_priority": { "type": "number", "example": 0.8 }, "updated": { "description": "Last update timestamp (UTC)\n@Example 2024-01-02T12:30:45Z", "type": "string", "example": "2024-01-02T12:30:45Z" }, "vat_value": { "description": "VAT percentage\n@Example 15", "type": "number", "example": 15 } } }, "v1.ProductStats": { "description": "Aggregated statistics for products", "type": "object", "properties": { "avg_price": { "type": "number" }, "digital_readiness": { "type": "number" }, "fast_moving": { "type": "integer" }, "price_std_dev": { "type": "number" }, "refrigerated": { "type": "integer" }, "restricted": { "type": "integer" }, "total": { "type": "integer" }, "vat_revenue": { "type": "number" } } }, "v1.ProductUpdateData": { "description": "Reference to updated product", "type": "object", "properties": { "iv_id": { "description": "Internal Vendor ID of updated product\n@Example IV123456", "type": "string", "example": "IV123456" } } }, "v1.ProductUpdateResponse": { "description": "Response returned after successful product update", "type": "object", "properties": { "data": { "description": "Updated product reference", "allOf": [ { "$ref": "#/definitions/v1.ProductUpdateData" } ] }, "message": { "description": "Human-readable success message\n@Example Product updated successfully", "type": "string", "example": "Product updated successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.ProviderPaylinkCaptureRequest": { "type": "object", "properties": { "amount": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "reference_id": { "type": "string" } } }, "v1.ProviderPaylinkRequest": { "type": "object", "properties": { "amount": { "type": "string" }, "buyer_email": { "type": "string" }, "buyer_name": { "type": "string" }, "buyer_phone": { "type": "string" }, "currency": { "type": "string" }, "description": { "type": "string" }, "items": { "type": "array", "items": { "type": "integer" } }, "lang": { "type": "string" }, "locale": { "description": "Tamara-specific", "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "order_id": { "type": "string" }, "org_app_id": { "type": "string" }, "payment_type": { "description": "Tamara-specific", "type": "string" }, "phone_number": { "description": "Tamara-specific", "type": "string" }, "provider": { "type": "string" }, "store_code": { "description": "Tamara-specific", "type": "string" } } }, "v1.RuntimeMetrics": { "description": "Go runtime performance telemetry for runtime monitoring", "type": "object", "properties": { "alloc_mb": { "type": "integer", "example": 128 }, "cpu_count": { "type": "integer", "example": 8 }, "gc_pause_ns": { "type": "integer", "example": 500000 }, "goroutines": { "type": "integer", "example": 50 }, "num_gc": { "type": "integer", "example": 10 }, "sys_mb": { "type": "integer", "example": 256 }, "total_alloc_mb": { "type": "integer", "example": 1024 } } }, "v1.SKUBulkData": { "description": "Statistics from bulk SKU operation", "type": "object", "properties": { "errors": { "description": "Details of failures (iv_id -\u003e error)", "type": "object" }, "failed": { "description": "Number of failed items\n@Example 5", "type": "integer", "example": 5 }, "succeeded": { "description": "Number of successfully processed items\n@Example 95", "type": "integer", "example": 95 } } }, "v1.SKUBulkRequest": { "description": "Request for bulk SKU operations", "type": "object", "required": [ "mode", "skus" ], "properties": { "mode": { "description": "Operation mode: \"create\", \"update\", or \"upsert\"\n@Example upsert\n@Enum create,update,upsert", "type": "string", "enum": [ "create", "update", "upsert" ], "example": "upsert" }, "skip_validation": { "description": "Skip validation for faster processing (use with caution)", "type": "boolean", "example": false }, "skus": { "description": "SKUs to process\n@maxItems 1000", "type": "array", "maxItems": 1000, "minItems": 1, "items": { "type": "object" } } } }, "v1.SKUBulkResponse": { "description": "Result of bulk SKU operation", "type": "object", "properties": { "data": { "description": "Operation results", "allOf": [ { "$ref": "#/definitions/v1.SKUBulkData" } ] }, "message": { "description": "Human-readable summary message\n@Example Processed 100 SKUs successfully", "type": "string", "example": "Processed 100 SKUs successfully" }, "success": { "description": "Operation success indicator\n@Example true", "type": "boolean", "example": true }, "timestamp": { "description": "Operation timestamp (UTC)\n@Example 2024-01-01T12:00:00Z", "type": "string", "example": "2024-01-01T12:00:00Z" } } }, "v1.SKUListResponse": { "description": "Paginated list of SKUs", "type": "object", "properties": { "items": { "description": "@Description List of SKUs", "type": "array", "items": { "$ref": "#/definitions/v1.SKUResponseData" } }, "message": { "description": "@Description Response message", "type": "string" }, "meta": { "description": "@Description Additional metadata", "type": "object", "additionalProperties": {} }, "page": { "description": "@Description Current page number\n@Example 1", "type": "integer" }, "perPage": { "description": "@Description Items per page\n@Example 20", "type": "integer" }, "stats": { "description": "@Description Aggregated statistics", "allOf": [ { "$ref": "#/definitions/v1.SKUStats" } ] }, "success": { "description": "@Description Success status", "type": "boolean" }, "timestamp": { "description": "@Description Response timestamp", "type": "string" }, "totalItems": { "description": "@Description Total number of items\n@Example 150", "type": "integer" }, "totalPages": { "description": "@Description Total number of pages\n@Example 8", "type": "integer" } } }, "v1.SKURequest": { "description": "SKU creation or update request", "type": "object", "required": [ "branch_iv_id", "iv_id" ], "properties": { "amazon_asin": { "type": "string", "example": "B08N5WRWNW" }, "amazon_sku": { "type": "string", "example": "AMZ-SKU-123" }, "available": { "type": "boolean", "example": true }, "barcode": { "type": "string", "example": "1234567890123" }, "branch_id": { "description": "BranchID is a backward-compatible alias used by older CSV import templates.\nIt is normalized into BranchIvId before validation/persistence.", "type": "string", "example": "branch_123" }, "branch_iv_id": { "type": "string", "example": "branch_123" }, "buffer": { "type": "number", "example": 10 }, "category_id": { "type": "string", "example": "cat_123" }, "gtin": { "type": "string", "example": "00123456789012" }, "iv_id": { "type": "string", "example": "IV123" }, "max_qty": { "type": "number", "example": 1000 }, "noon_nsku": { "type": "string", "example": "NOON-N123" }, "noon_zsku": { "type": "string", "example": "NOON-Z123" }, "price": { "type": "number", "example": 29.99 }, "product_id": { "description": "ProductID is a backward-compatible alias used by older CSV import templates.\nIt is normalized into ProductIvId before validation/persistence.", "type": "string", "example": "prd_123" }, "product_iv_id": { "type": "string", "example": "prd_123" }, "qty": { "type": "number", "example": 100 }, "reorder_threshold": { "type": "number", "example": 20 }, "salla_id": { "type": "string", "example": "SALLA123" }, "u_id": { "type": "string", "example": "U123" }, "zid_id": { "type": "string", "example": "ZID123" } } }, "v1.SKUResponse": { "description": "Complete SKU information", "type": "object", "properties": { "data": { "$ref": "#/definitions/v1.SKUResponseData" }, "message": { "type": "string" }, "success": { "type": "boolean", "example": true }, "timestamp": { "type": "string", "example": "2024-01-01T00:00:00Z" } } }, "v1.SKUResponseData": { "description": "SKU data", "type": "object", "properties": { "amazon_asin": { "type": "string" }, "amazon_sku": { "type": "string" }, "available": { "type": "boolean" }, "barcode": { "type": "string" }, "branch_id": { "type": "string" }, "branch_iv_id": { "type": "string" }, "branch_name": { "type": "string" }, "buffer": { "type": "number" }, "category_id": { "type": "string" }, "category_name": { "type": "string" }, "collectionId": { "type": "string" }, "collectionName": { "type": "string" }, "created": { "type": "string" }, "gtin": { "type": "string" }, "hash": { "type": "string" }, "id": { "type": "string" }, "iv_id": { "type": "string" }, "max_qty": { "type": "number" }, "noon_nsku": { "type": "string" }, "noon_zsku": { "type": "string" }, "organization_id": { "type": "string" }, "organization_name": { "type": "string" }, "price": { "type": "number" }, "product_hero_image_file": { "type": "string" }, "product_hero_image_url": { "type": "string" }, "product_id": { "type": "string" }, "product_iv_id": { "type": "string" }, "product_name": { "description": "Expanded fields", "type": "string" }, "product_name_ar": { "type": "string" }, "product_name_en": { "type": "string" }, "qty": { "type": "number" }, "reorder_threshold": { "type": "number" }, "salla_id": { "type": "string" }, "u_id": { "type": "string" }, "updated": { "type": "string" }, "zid_id": { "type": "string" } } }, "v1.SKUStats": { "description": "Aggregated statistics for SKUs", "type": "object", "properties": { "available": { "type": "integer" }, "low_stock": { "type": "integer" }, "out_of_stock": { "type": "integer" }, "total": { "type": "integer" }, "total_value": { "type": "number" } } }, "v1.SKUStockUpdateRequest": { "description": "SKU stock update request", "type": "object", "properties": { "available": { "type": "boolean", "example": true }, "qty": { "type": "number", "example": 100 } } }, "v1.SKUUpdateData": { "description": "Updated SKU data", "type": "object", "properties": { "iv_id": { "type": "string", "example": "IV123" }, "updated": { "type": "object" } } }, "v1.SKUUpdateResponse": { "description": "SKU update success response", "type": "object", "properties": { "data": { "$ref": "#/definitions/v1.SKUUpdateData" }, "message": { "type": "string", "example": "Operation successful" }, "meta": { "$ref": "#/definitions/v1.Meta" }, "success": { "type": "boolean", "example": true }, "timestamp": { "type": "string", "example": "2024-01-01T00:00:00Z" } } }, "v1.SmsManualBulkSendResponse": { "type": "object", "properties": { "elapsed_ms": { "type": "integer" }, "errors": { "type": "array", "items": { "$ref": "#/definitions/smsmanual.BulkError" } }, "failed": { "type": "integer" }, "sent": { "type": "integer" }, "total": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "v1.SmsManualSendRequest": { "type": "object", "properties": { "datetime": { "type": "string" }, "message": { "type": "string" }, "mobile": { "type": "string" }, "sender": { "type": "string" } } }, "v1.SmsOutboxEnqueueRequest": { "type": "object", "properties": { "datetime": { "type": "string" }, "idempotency_key": { "type": "string" }, "message": { "type": "string" }, "meta": { "type": "object", "additionalProperties": {} }, "mobile": { "type": "string" }, "preferred_provider_slug": { "type": "string" }, "sender": { "type": "string" } } }, "v1.SmsOutboxEnqueueResponse": { "type": "object", "properties": { "dispatch_status": { "type": "string" }, "id": { "type": "string" }, "idempotent_replay": { "type": "boolean" } } }, "v1.SystemHealthResponse": { "description": "Detailed runtime health information including integration status", "type": "object", "properties": { "environment": { "type": "string", "example": "production" }, "status": { "type": "string", "example": "healthy" }, "system_health": { "$ref": "#/definitions/integrations.GlobalSystemHealth" }, "uptime_seconds": { "type": "number", "example": 3600 }, "version": { "type": "string", "example": "1.0.0" } } }, "v1.TagListResponse": { "description": "List of tags with pagination info", "type": "object", "properties": { "count": { "type": "integer", "example": 25 }, "limit": { "type": "integer", "example": 50 }, "page": { "type": "integer", "example": 1 }, "tags": { "type": "array", "items": { "$ref": "#/definitions/v1.TagResponse" } } } }, "v1.TagResponse": { "description": "Tag information", "type": "object", "properties": { "created": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "id": { "type": "string", "example": "r7654321" }, "name": { "type": "string", "example": "Golang" }, "slug": { "type": "string", "example": "golang" }, "updated": { "type": "string", "example": "2024-01-01T00:00:00Z" } } }, "v1.ValidationError": { "description": "Detailed validation error information", "type": "object", "properties": { "code": { "description": "@Description Machine-readable error code\n@Example \"out_of_range\"", "type": "string" }, "field": { "description": "@Description Field path that failed validation\n@Example \"location.lat\"", "type": "string" }, "message": { "description": "@Description Human-readable error message\n@Example \"Latitude must be between -90 and 90\"", "type": "string" } } }, "v1.VerificationRequest": { "type": "object", "properties": { "access_token": { "type": "string" }, "api_key": { "type": "string" }, "api_secret": { "type": "string" }, "custom_body": { "type": "object", "additionalProperties": {} }, "custom_headers": { "type": "object", "additionalProperties": {} }, "custom_params": { "type": "object", "additionalProperties": {} }, "refresh_token": { "type": "string" } } }, "v1.VerificationResponse": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "message": { "type": "string" }, "valid": { "type": "boolean" } } }, "v1.WorkingHours": { "description": "Weekly operating hours for the branch", "type": "object", "properties": { "friday": { "description": "@Description Friday schedule", "allOf": [ { "$ref": "#/definitions/v1.DaySchedule" } ] }, "monday": { "description": "@Description Monday schedule", "allOf": [ { "$ref": "#/definitions/v1.DaySchedule" } ] }, "saturday": { "description": "@Description Saturday schedule", "allOf": [ { "$ref": "#/definitions/v1.DaySchedule" } ] }, "sunday": { "description": "@Description Sunday schedule", "allOf": [ { "$ref": "#/definitions/v1.DaySchedule" } ] }, "thursday": { "description": "@Description Thursday schedule", "allOf": [ { "$ref": "#/definitions/v1.DaySchedule" } ] }, "tuesday": { "description": "@Description Tuesday schedule", "allOf": [ { "$ref": "#/definitions/v1.DaySchedule" } ] }, "wednesday": { "description": "@Description Wednesday schedule", "allOf": [ { "$ref": "#/definitions/v1.DaySchedule" } ] } } }, "v1.WorkingHoursPeriod": { "type": "object", "properties": { "CloseHour": { "description": "@Description Closing hour (24h). Can be lower than OpenHour for overnight windows.\n@Example 17", "type": "integer" }, "CloseMinute": { "description": "@Description Closing minute\n@Example 30", "type": "integer" }, "OpenHour": { "description": "@Description Opening hour (24h)\n@Example 9", "type": "integer" }, "OpenMinute": { "description": "@Description Opening minute\n@Example 0", "type": "integer" }, "WeekDay": { "description": "@Description Weekday name\n@Example \"Monday\"", "type": "string" } } }, "v1.offerBulkRequest": { "type": "object", "properties": { "offers": { "type": "array", "items": { "$ref": "#/definitions/domain.OfferRequest" } } } }, "v1.paymentOrderConfirmRequest": { "type": "object", "properties": { "provider": { "type": "string" } } }, "v1.paymentOrderCreateResponse": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "message": { "type": "string" }, "success": { "type": "boolean" } } }, "v1.paymentOrderRequest": { "type": "object", "properties": { "order": { "type": "object", "additionalProperties": {} }, "providers": { "type": "array", "items": { "type": "string" } } } }, "v1.reportEnvelope": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "fetched_at": { "type": "string" }, "organization_id": { "type": "string" } } }, "v1.specMetadata": { "type": "object", "properties": { "description": { "type": "string" }, "generated": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "string" } } }, "webhooks.UnifiedOrderEventPayload": { "type": "object", "properties": { "app_slug": { "type": "string" }, "changed_fields": { "type": "array", "items": { "type": "string" } }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "occurred_at": { "type": "string" }, "order": { "$ref": "#/definitions/webhooks.UnifiedOrderPayload" }, "organization_app_id": { "type": "string" }, "organization_id": { "type": "string" }, "spec_version": { "type": "string" } } }, "webhooks.UnifiedOrderPayload": { "type": "object", "properties": { "comment": { "type": "string" }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "customer_email": { "type": "string" }, "customer_name": { "type": "string" }, "customer_phone": { "type": "string" }, "delivery_fee": { "type": "number" }, "destination_id": { "type": "string" }, "destination_reference": { "type": "string" }, "discounts_amount": { "type": "number" }, "dispatch_routing": {}, "fulfillment_method": { "type": "string" }, "fulfillment_status": { "type": "string" }, "id": { "type": "string" }, "is_preorder": { "type": "boolean" }, "order_code": { "type": "string" }, "order_status": { "type": "string" }, "order_type": { "type": "string" }, "organization_id": { "type": "string" }, "payment_method": { "type": "string" }, "payment_status": { "type": "string" }, "products": {}, "promised_for": { "type": "string" }, "receiver_name": { "type": "string" }, "receiver_phone": { "type": "string" }, "service_fee": { "type": "number" }, "shipping_address": { "type": "object", "additionalProperties": {} }, "shipping_fulfillment": {}, "skus": { "type": "array", "items": { "type": "string" } }, "source_reference": { "type": "string" }, "source_timestamp": { "type": "string" }, "source_transaction_id": { "type": "string" }, "store_name": { "type": "string" }, "subtotal": { "type": "number" }, "total_amount": { "type": "number" }, "transport_type": { "type": "string" }, "updated_at": { "type": "string" }, "vat_amount": { "type": "number" } } }, "webhooks.UnifiedOrdersListHTTPBody": { "type": "object", "properties": { "event_type": { "type": "string" }, "meta": { "type": "object", "additionalProperties": {} }, "occurred_at": { "type": "string" }, "orders": { "type": "array", "items": { "$ref": "#/definitions/webhooks.UnifiedOrderEventPayload" } }, "organization_id": { "type": "string" }, "pagination": { "$ref": "#/definitions/webhooks.UnifiedOrdersListPagination" }, "spec_version": { "type": "string" } } }, "webhooks.UnifiedOrdersListPagination": { "type": "object", "properties": { "has_next": { "type": "boolean" }, "has_prev": { "type": "boolean" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_items": { "type": "integer" }, "total_pages": { "type": "integer" } } } }, "securityDefinitions": { "ApiKeyAuth": { "type": "apiKey", "name": "Authorization", "in": "header" } } }