{ "openapi": "3.0.3", "info": { "title": "Sarraf Developer API", "version": "1.0.0", "description": "Storefront and scoped integration API. Customer tokens and integration API keys are separate actors." }, "servers": [ { "url": "https://api.sarraf.net" } ], "paths": { "/storefront/orders/{publicId}/returns": { "get": { "tags": [ "Merchant Commerce" ], "summary": "Read owned return cases and summary; managing staff also receives original refundable payment references and inspectionPieces barcode/RFID choices; customer responses never include physical unit identifiers", "security": [ { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Current safe result; private, no-store", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Invalid form or missing operation identity" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant, actor, branch, account or cashbox denied" }, "404": { "description": "Owned record unavailable" }, "409": { "description": "Revision, stage, quantity, amount, authority or identity conflict" }, "429": { "description": "Rate limit" }, "503": { "description": "Operation or storage unavailable; retry the same identity Shared rate-limit state outages also reject the request before its handler executes." } }, "operationId": "get_storefront_orders_publicId_returns", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false }, "post": { "tags": [ "Merchant Commerce" ], "summary": "Request an item/quantity return after delivery; withdrawal uses refund, defect rights preserve all remedies", "security": [ { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "withdrawal", "defect" ] }, "remedy": { "type": "string", "enum": [ "refund", "reduction", "repair", "exchange" ] }, "note": { "type": "string", "minLength": 0, "maxLength": 1000 }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "lineIndex": { "type": "integer", "minimum": 0, "maximum": 999 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 99 } }, "required": [ "lineIndex", "quantity" ], "additionalProperties": false } } }, "required": [ "reason", "remedy", "lines" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Current safe result; private, no-store", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "object", "required": [ "id", "version", "status", "lines", "maximumRefund", "currencyCode" ], "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "requested", "approved", "rejected", "withdrawn", "in_transit", "received", "refund_ready", "refund_confirmed", "repair_in_progress", "completed" ] }, "reason": { "type": "string", "enum": [ "withdrawal", "defect" ] }, "remedy": { "type": "string", "enum": [ "refund", "reduction", "repair", "exchange" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineIndex": { "type": "integer" }, "title": { "type": "string", "minLength": 0, "maxLength": 1000 }, "quantity": { "type": "integer" }, "maximumRefund": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "policy": { "type": "object", "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "mode": { "type": "string", "enum": [ "standard", "market_fluctuation", "custom_made", "sealed_hygiene" ] }, "description": { "type": "string", "minLength": 0, "maxLength": 1000 }, "defectRightsPreserved": { "type": "boolean", "enum": [ true ] } }, "required": [ "mode" ], "additionalProperties": false }, "eligibility": { "type": "string", "enum": [ "standard_withdrawal", "defect_rights_preserved", "seal_condition_review", "exception_review", "deadline_review" ] } } } }, "maximumRefund": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "currencyCode": { "type": "string", "minLength": 0, "maxLength": 20 }, "refundAmount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "nullable": true }, "shippingRefund": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "refundReference": { "type": "string", "minLength": 0, "maxLength": 200, "nullable": true } }, "additionalProperties": true } } } } } }, "400": { "description": "Invalid form or missing operation identity" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant, actor, branch, account or cashbox denied" }, "404": { "description": "Owned record unavailable" }, "409": { "description": "Revision, stage, quantity, amount, authority or identity conflict" }, "429": { "description": "Rate limit" }, "503": { "description": "Operation or storage unavailable; retry the same identity Shared rate-limit state outages also reject the request before its handler executes." } }, "operationId": "post_storefront_orders_publicId_returns", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/orders/{publicId}/returns/{returnId}/{action}": { "post": { "tags": [ "Merchant Commerce" ], "summary": "Advance a versioned return case; customers may only withdraw or submit shipping details", "security": [ { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "in": "path", "name": "returnId", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "in": "path", "name": "action", "required": true, "schema": { "type": "string", "enum": [ "withdraw", "approve", "reject", "shipping", "receive", "inspect", "inspect-reject", "confirm-refund", "complete-remedy" ] } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 } }, "required": [ "version" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "note": { "type": "string", "minLength": 0, "maxLength": 1000 }, "amount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "pieces": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "lineIndex": { "type": "integer", "minimum": 0, "maximum": 999 }, "unitIds": { "type": "array", "maxItems": 99, "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "lineIndex", "unitIds" ], "additionalProperties": false } } }, "required": [ "version" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "note": { "type": "string", "minLength": 3, "maxLength": 1000 } }, "required": [ "version", "note" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "carrier": { "type": "string", "minLength": 1, "maxLength": 100 }, "trackingNumber": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "version", "carrier", "trackingNumber" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "note": { "type": "string", "minLength": 0, "maxLength": 1000 } }, "required": [ "version" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "pieces": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "lineIndex": { "type": "integer", "minimum": 0, "maximum": 999 }, "unitIds": { "type": "array", "maxItems": 99, "items": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "required": [ "lineIndex", "unitIds" ], "additionalProperties": false } }, "disposition": { "type": "string", "enum": [ "restock", "retire", "hold" ] }, "confirmedReceived": { "type": "boolean", "enum": [ true ] }, "note": { "type": "string", "minLength": 3, "maxLength": 1000 } }, "required": [ "version", "disposition", "confirmedReceived", "note" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "note": { "type": "string", "minLength": 3, "maxLength": 1000 }, "carrier": { "type": "string", "minLength": 1, "maxLength": 100 }, "trackingNumber": { "type": "string", "minLength": 1, "maxLength": 100 }, "reference": { "type": "string", "minLength": 3, "maxLength": 200 } }, "required": [ "version", "note", "carrier", "trackingNumber", "reference" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "paymentId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "reference": { "type": "string", "minLength": 3, "maxLength": 200 } }, "required": [ "version", "paymentId", "reference" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "reference": { "type": "string", "minLength": 3, "maxLength": 200 }, "carrier": { "type": "string", "minLength": 1, "maxLength": 100 }, "trackingNumber": { "type": "string", "minLength": 1, "maxLength": 100 }, "replacementOrderNo": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "version", "reference" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Current safe result; private, no-store", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "object", "required": [ "id", "version", "status", "lines", "maximumRefund", "currencyCode" ], "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "requested", "approved", "rejected", "withdrawn", "in_transit", "received", "refund_ready", "refund_confirmed", "repair_in_progress", "completed" ] }, "reason": { "type": "string", "enum": [ "withdrawal", "defect" ] }, "remedy": { "type": "string", "enum": [ "refund", "reduction", "repair", "exchange" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineIndex": { "type": "integer" }, "title": { "type": "string", "minLength": 0, "maxLength": 1000 }, "quantity": { "type": "integer" }, "maximumRefund": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "policy": { "type": "object", "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "mode": { "type": "string", "enum": [ "standard", "market_fluctuation", "custom_made", "sealed_hygiene" ] }, "description": { "type": "string", "minLength": 0, "maxLength": 1000 }, "defectRightsPreserved": { "type": "boolean", "enum": [ true ] } }, "required": [ "mode" ], "additionalProperties": false }, "eligibility": { "type": "string", "enum": [ "standard_withdrawal", "defect_rights_preserved", "seal_condition_review", "exception_review", "deadline_review" ] } } } }, "maximumRefund": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "currencyCode": { "type": "string", "minLength": 0, "maxLength": 20 }, "refundAmount": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$", "nullable": true }, "shippingRefund": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,2})?$" }, "refundReference": { "type": "string", "minLength": 0, "maxLength": 200, "nullable": true } }, "additionalProperties": true } } } } } }, "400": { "description": "Invalid form or missing operation identity" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant, actor, branch, account or cashbox denied" }, "404": { "description": "Owned record unavailable" }, "409": { "description": "Revision, stage, quantity, amount, authority or identity conflict" }, "429": { "description": "Rate limit" }, "503": { "description": "Operation or storage unavailable; retry the same identity Shared rate-limit state outages also reject the request before its handler executes." } }, "description": "Action determines its strict body. Inspection requires received goods, explicit identity/quantity/condition confirmation and actual original unitIds when multiple pieces are tracked; reduction approval uses the same selection. Refund cents are recomputed from the selected original unit ordinals and prior reductions; stock stays unavailable until inspection. confirm-refund records an already completed external refund against an original payment, caps remaining paid cents and posts once atomically. Repair remains unavailable; exchange requires a paid, delivered replacement order number. No PSP call or automatic credit note issuance. Full order state changes only after all pieces and the paid total are returned.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "operationId": "post_storefront_orders_publicId_returns_returnId_action", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/orders/{publicId}/documents": { "get": { "tags": [ "Merchant Commerce" ], "summary": "List immutable external invoice/credit-note versions for the owned e-commerce order", "security": [ { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Current safe result; private, no-store", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "documentNumber", "issuedAt", "url" ], "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "version": { "type": "integer", "minimum": 1 }, "kind": { "type": "string", "enum": [ "invoice", "credit_note" ] }, "documentNumber": { "type": "string", "minLength": 0, "maxLength": 100 }, "issuedAt": { "type": "string", "format": "date" }, "url": { "type": "string", "minLength": 0, "maxLength": 500 } } } } } } } } }, "400": { "description": "Invalid form or missing operation identity" }, "401": { "description": "Authentication required" }, "403": { "description": "Tenant, actor, branch, account or cashbox denied" }, "404": { "description": "Owned record unavailable" }, "409": { "description": "Revision, stage, quantity, amount, authority or identity conflict" }, "429": { "description": "Rate limit" }, "503": { "description": "Operation or storage unavailable; retry the same identity Shared rate-limit state outages also reject the request before its handler executes." } }, "operationId": "get_storefront_orders_publicId_documents", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/orders/{publicId}/documents/{documentId}/file": { "get": { "tags": [ "Merchant Commerce" ], "summary": "Download owned private fiscal PDF; attachment, no-store, nosniff", "security": [ { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "publicId", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "in": "path", "name": "documentId", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Private attachment", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Ownership denied" }, "404": { "description": "Owned attachment unavailable" }, "503": { "description": "Storage unavailable Shared rate-limit state outages also reject the request before its handler executes." } }, "operationId": "get_storefront_orders_publicId_documents_documentId_file", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/i18n/codes": { "get": { "tags": [ "I18n" ], "summary": "List server message codes for client translation seed", "responses": { "200": { "description": "Message code list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/I18nMessageCode" } } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_i18n_codes", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/currencies": { "get": { "tags": [ "Currencies" ], "summary": "List currencies", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search code, title and parent code." }, { "name": "isManual", "in": "query", "schema": { "type": "boolean" }, "description": "Filter manual or automatic prices." }, { "$ref": "#/components/parameters/StatusParam" }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PageSizeParam" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Currency list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/Currency" } }, "paginate": { "type": "object" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_currencies", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true } }, "/settings/branches": { "get": { "tags": [ "Settings Branches" ], "summary": "List branches", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/StatusParam" }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PageSizeParam" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Literal branch title or code search" }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "createdAt", "title", "branchCode" ] } }, { "name": "sortDir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "List", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/SettingsBranch" } }, "paginate": { "type": "object" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_settings_branches", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true } }, "/settings/branches/{id}": { "get": { "tags": [ "Settings Branches" ], "summary": "branch detail", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/SettingsBranch" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_settings_branches_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true } }, "/catalog/products": { "get": { "tags": [ "Catalog Products" ], "summary": "List products", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PageSizeParam" }, { "$ref": "#/components/parameters/QParam" }, { "$ref": "#/components/parameters/DateFromParam" }, { "$ref": "#/components/parameters/DateToParam" }, { "$ref": "#/components/parameters/SortByParam" }, { "$ref": "#/components/parameters/SortDirParam" }, { "name": "priceMode", "in": "query", "schema": { "type": "string", "enum": [ "fixed", "source", "legacy" ] }, "description": "Selling price definition" }, { "name": "sourceStatus", "in": "query", "schema": { "type": "string", "enum": [ "available", "unavailable" ] } }, { "name": "operational", "in": "query", "schema": { "type": "boolean" }, "description": "Authorized operational POS catalogue view." }, { "name": "retailStockOrder", "in": "query", "schema": { "type": "string", "enum": [ "availableFirst" ] }, "description": "With operational=true, available stock sorts before other rows prior to pagination; requested sort is preserved within each group." }, { "name": "sortBy", "in": "query", "schema": { "type": "string" }, "description": "priceChangedAt sorts by the latest accepted change" }, { "name": "ids", "in": "query", "schema": { "type": "string" }, "description": "Hydrate 1–100 explicit comma-separated ObjectIds within the actor's shop, branch and category scope. Invalid or empty input returns 400." }, { "name": "retail", "in": "query", "schema": { "type": "boolean" }, "description": "Store selector: active catalog quantity products include zero/negative/reserved stock. Explicitly archived records stay excluded; serialized availability still applies." }, { "name": "status", "in": "query", "required": false, "description": "Filter by active status (true/false)", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "branchId", "in": "query", "required": false, "description": "Filter by branch", "schema": { "type": "string" } }, { "name": "currencyCode", "in": "query", "required": false, "description": "Filter by currency code (normalized)", "schema": { "type": "string" } }, { "name": "salesStatus", "in": "query", "required": false, "description": "Filter by sales status", "schema": { "type": "string", "enum": [ "available", "reserved", "sold" ] } }, { "name": "categoryId", "in": "query", "required": false, "description": "Filter by category (ObjectId, matches array)", "schema": { "type": "string" } }, { "name": "groupId", "in": "query", "required": false, "description": "Filter by group (ObjectId, matches array)", "schema": { "type": "string" } }, { "name": "salesChannel", "in": "query", "required": false, "description": "Filter by sales channel", "schema": { "type": "string", "enum": [ "b2b", "ecommerce", "store" ] } }, { "name": "label", "in": "query", "required": false, "description": "Search by label text (partial match in title and barcode)", "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort field", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "title", "barcode", "salesStatus", "selling", "buying" ] } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "List", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "paginate": { "type": "object" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_catalog_products", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true }, "post": { "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Persist before sending. Permanent product creation and opening-stock replay, bound to input and actor." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "tags": [ "Catalog Products" ], "summary": "Create products", "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/Product" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_catalog_products", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": false } }, "/catalog/products/{id}/price-history": { "get": { "tags": [ "Catalog Products" ], "summary": "Permanent accepted product price history", "description": "Scoped to product detail permissions and branch. Contains an honest baseline and accepted changes only; no raw ticks or automatic expiry. Product CAS and evidence are atomic. Monetary deltas are exact decimal strings.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PageSizeParam" }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Paginated history", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ProductPriceHistory" } }, "paginate": { "type": "object" } } } } } }, "404": { "description": "Product unavailable to actor" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_catalog_products_id_price_history", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true } }, "/catalog/products/{id}": { "put": { "tags": [ "Catalog Products" ], "summary": "Update product", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdateInput" } } } }, "responses": { "200": { "description": "Updated" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "put_catalog_products_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": false } }, "/catalog/products/{id}/management-detail": { "get": { "tags": [ "Catalog Products" ], "summary": "product management detail", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/ProductManagementDetail" } } } } } }, "403": { "description": "Product-detail scope denied" }, "404": { "description": "Invalid, missing or inaccessible product; older servers do not support this route" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "description": "Read-only management-v1 metadata and live-price/gallery envelope. Same product-detail scope, tenant, branch, category and cashbox authority. Mongo inclusion projection excludes unit, reservation, journal and cost arrays before reading. stockOnHand/reservedQuantity are stored scalar balances, not canonical available/held stock. Clients must validate presentation and exact product ID; old servers return 404 and must not fall back to unbounded product detail.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "operationId": "get_catalog_products_id_management_detail", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true } }, "/catalog/categories": { "get": { "tags": [ "Catalog Categories" ], "summary": "List categories", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PageSizeParam" }, { "$ref": "#/components/parameters/QParam" }, { "$ref": "#/components/parameters/DateFromParam" }, { "$ref": "#/components/parameters/DateToParam" }, { "$ref": "#/components/parameters/SortByParam" }, { "$ref": "#/components/parameters/SortDirParam" }, { "$ref": "#/components/parameters/StatusParam" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "List", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategory" } }, "paginate": { "type": "object" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_catalog_categories", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true } }, "/catalog/categories/{id}": { "get": { "tags": [ "Catalog Categories" ], "summary": "category detail", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/ProductCategory" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_catalog_categories_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true } }, "/storefront/analytics/events": { "post": { "tags": [ "Analytics" ], "summary": "Store non-authoritative anonymous storefront interaction events", "security": [ {} ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "object" } } } } } }, "400": { "description": "Invalid input" }, "403": { "description": "Staff/shop/branch/category/cashbox scope rejected" }, "409": { "description": "Code collision, changed version or pending reconciliation" }, "503": { "description": "Persistence/index/network unavailable; existing sales are retained Shared rate-limit state outages also reject the request before its handler executes." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsBatch" } } } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_analytics_events", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/sales/customers": { "get": { "tags": [ "Sales Customers" ], "summary": "List customers", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PageSizeParam" }, { "$ref": "#/components/parameters/QParam" }, { "$ref": "#/components/parameters/DateFromParam" }, { "$ref": "#/components/parameters/DateToParam" }, { "$ref": "#/components/parameters/SortByParam" }, { "$ref": "#/components/parameters/SortDirParam" }, { "name": "status", "in": "query", "required": false, "description": "Filter by active status (true/false)", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "type", "in": "query", "required": false, "description": "Filter by customer type", "schema": { "type": "string", "enum": [ "individual", "company" ] } }, { "name": "riskStatus", "in": "query", "required": false, "description": "Filter by risk status", "schema": { "type": "string", "enum": [ "default", "safe", "risky", "banned" ] } }, { "name": "phone", "in": "query", "required": false, "description": "Filter by phone (exact match)", "schema": { "type": "string" } }, { "name": "customerCode", "in": "query", "required": false, "description": "Filter by customer code (exact match, normalized)", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Filter by email (exact match, lowercased)", "schema": { "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort field", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "title", "customerCode", "riskStatus" ] } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "List", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "paginate": { "type": "object" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_sales_customers", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true }, "post": { "tags": [ "Sales Customers" ], "summary": "Create customers", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable operation key; reusing it with different input is rejected", "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "description": "Staff clients persist Idempotency-Key before sending. Same shop/actor/input returns the existing customer without repeating initial risk history or reactivating it. Identity has no TTL; changed input/actor returns 409. Keyed creation uses native transactions or the durable standalone journal.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" } } } }, "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/Customer" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_sales_customers", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": false } }, "/sales/customers/{id}": { "get": { "tags": [ "Sales Customers" ], "summary": "customer detail", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/Customer" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_sales_customers_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true }, "put": { "tags": [ "Sales Customers" ], "summary": "Update customer", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" } } } }, "responses": { "200": { "description": "Updated" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "put_sales_customers_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": false } }, "/sales/orders": { "get": { "tags": [ "Sales Orders" ], "summary": "List orders", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PageSizeParam" }, { "$ref": "#/components/parameters/QParam" }, { "$ref": "#/components/parameters/DateFromParam" }, { "$ref": "#/components/parameters/DateToParam" }, { "$ref": "#/components/parameters/SortByParam" }, { "$ref": "#/components/parameters/SortDirParam" }, { "name": "status", "in": "query", "required": false, "description": "Filter by order status", "schema": { "type": "string", "enum": [ "draft", "pendingApproval", "confirmed", "inProduction", "ready", "delivered", "cancelled", "returned" ] } }, { "name": "paymentStatus", "in": "query", "required": false, "description": "Filter by payment status", "schema": { "type": "string", "enum": [ "unpaid", "partial", "paid", "refunded" ] } }, { "name": "branchId", "in": "query", "required": false, "description": "Filter by branch", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "required": false, "description": "Filter by customer", "schema": { "type": "string" } }, { "name": "cartId", "in": "query", "required": false, "description": "Recover the order created from a retail cart", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "description": "Filter by order channel", "schema": { "type": "string", "enum": [ "retail", "ecommerce" ] } }, { "name": "source", "in": "query", "required": false, "description": "Filter by order source", "schema": { "type": "string", "enum": [ "storefront", "walk_in", "whatsapp", "phone", "instagram", "other" ] } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort field", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "orderNo", "status", "paymentStatus", "totals.grandTotal" ] } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "List", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "paginate": { "type": "object" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_sales_orders", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true } }, "/sales/orders/{id}": { "get": { "tags": [ "Sales Orders" ], "summary": "order detail", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/Order" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_sales_orders_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "api-key", "x-sarraf-mcp-read": true } }, "/site/sitemap": { "get": { "tags": [ "Site" ], "summary": "Get tenant-scoped published sitemap entries", "security": [ {}, {} ], "description": "Returns groups with page counts, or at most 1000 published paths and last modification times. Private accounts, orders and unavailable categories are excluded.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "group", "in": "query", "schema": { "type": "string", "enum": [ "index", "pages", "products", "categories", "articles" ], "default": "index" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 999999, "default": 1 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Sitemap data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "pages": { "type": "integer" } } } }, "urls": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "lastmod": { "type": "string", "format": "date-time" } } } } } } } } } } }, "400": { "description": "Invalid group or page" }, "404": { "description": "Page does not exist" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_site_sitemap", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/storefront-context": { "get": { "tags": [ "Site" ], "summary": "Resolve a storefront hostname", "description": "Returns the active shop and installed template for a verified custom domain or a one-label platform subdomain under STOREFRONT_ROOT_DOMAIN(S). This public response contains no credentials or private shop settings.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [], "parameters": [ { "name": "hostname", "in": "query", "required": true, "description": "Hostname only; ports, paths and URL credentials are rejected.", "schema": { "type": "string", "minLength": 1, "maxLength": 253, "example": "demo.storefront.example.com" } }, { "name": "purpose", "in": "query", "description": "api_origin explicitly includes operator-approved API origins for independently hosted SSR. Does not enable Sarraf hosting or change canonical domains.", "schema": { "type": "string", "enum": [ "api_origin" ] } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Resolved public storefront context", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean", "enum": [ true ] }, "result": { "type": "object", "required": [ "hostname", "shopCode", "templateKey" ], "properties": { "hostname": { "type": "string" }, "storefrontMaintenance": { "type": "boolean", "default": false }, "shopCode": { "type": "string", "description": "Requested platform hostname code; aliases remain compatible." }, "canonicalShopCode": { "type": "string" }, "storefrontOrigin": { "type": "string", "nullable": true, "format": "uri" }, "adminOrigin": { "type": "string", "nullable": true, "format": "uri" }, "templateKey": { "type": "string", "enum": [ "editorial", "catalog" ] } } } } } } } }, "400": { "description": "Malformed hostname" }, "403": { "description": "Shop is inactive (shop.inactive)" }, "404": { "description": "Hostname is not registered" }, "503": { "description": "Storefront context cannot be resolved Shared rate-limit state outages also reject the request before its handler executes." } }, "operationId": "get_storefront_context", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/site/theme": { "get": { "tags": [ "Site" ], "summary": "Get public site theme", "description": "Returns siteName, faviconUrl, colors, fonts, logo and template capabilities for the shop. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "Site theme", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/SiteTheme" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_site_theme", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/site/homepage": { "get": { "tags": [ "Site" ], "summary": "Get public site homepage", "description": "Returns published homepage data. Catalog product sections are resolved from source config. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "Published homepage data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "oneOf": [ { "$ref": "#/components/schemas/SiteHomepageEditorial" }, { "$ref": "#/components/schemas/SiteHomepageCatalog" } ] } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_site_homepage", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/site/articles": { "get": { "tags": [ "Site" ], "summary": "List published articles", "description": "Returns published articles for the shop. No bearer token required. Supports category, q, page, limit or pageSize query params. Invalid pagination normalizes to defaults, positive fractions are floored and pages clamp to totals. Equal publication times use stable identity ordering.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "pageSize", "in": "query", "description": "Preferred alias of limit when both are supplied.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Published articles list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/SiteArticleListItem" } }, "paginate": { "$ref": "#/components/schemas/Pagination" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_site_articles", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/site/articles/{slug}": { "get": { "tags": [ "Site" ], "summary": "Get published article detail by slug", "description": "Returns full article detail for a published article. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Article detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/SiteArticleDetail" } } } } } }, "404": { "description": "Article not found" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_site_articles_slug", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/site/header": { "get": { "tags": [ "Site" ], "summary": "Get site header navigation data", "description": "Returns top bar and navigation data for the shop. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "Site header data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/SiteHeader" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_site_header", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/site/gold-rate": { "get": { "tags": [ "Site" ], "summary": "Get the lightweight configured storefront gold rate", "description": "Reads the configured shop currency and price side with shared source-health rules. The response label follows the selected source title and sourceCode identifies that selection. The last structurally valid quote remains available with sourceStatus=stale while direct price operations still require a current source. Missing or invalid values are null; published CMS values never replace a missing quote.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "Current storefront gold rate", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "object", "properties": { "value": { "type": "number", "nullable": true }, "currency": { "type": "string", "nullable": true }, "sourceCode": { "type": "string" }, "sourceTitle": { "type": "string", "nullable": true }, "sourceReady": { "type": "boolean" }, "sourceStatus": { "type": "string" }, "unitCode": { "type": "string", "nullable": true }, "label": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_site_gold_rate", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/site/footer": { "get": { "tags": [ "Site" ], "summary": "Get site footer data", "description": "Returns footer and legal strip data for the shop. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "Site footer data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/SiteFooter" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_site_footer", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/pages/about-us": { "get": { "tags": [ "Site" ], "summary": "Get about us page data", "description": "Returns about us page content. Falls back to default if not configured. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "About us page data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "oneOf": [ { "$ref": "#/components/schemas/AboutUsEditorial" }, { "$ref": "#/components/schemas/AboutUsCatalog" } ] } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_pages_about_us", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/pages/campaigns": { "get": { "tags": [ "Site" ], "summary": "Get campaigns page data", "description": "Returns campaigns page content. Falls back to default if not configured. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "Campaigns page data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/CampaignPage" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_pages_campaigns", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/pages/search": { "get": { "tags": [ "Site" ], "summary": "Get search page static data", "description": "Returns search page static texts and popular search suggestions. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "Search page data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/SearchPage" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_pages_search", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/pages/faq": { "get": { "tags": [ "Site" ], "summary": "Get FAQ page data", "description": "Returns FAQ page content with categories and items. Falls back to default if not configured. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "FAQ page data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/FaqPage" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_pages_faq", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/search": { "get": { "tags": [ "Site" ], "summary": "Search products", "description": "Search active ecommerce products with optional text, category and exact label filters. Consignment stock requires explicit permission and matching canonical item/product/branch/party records in this shop. Ownership filtering precedes count, stable sorting and pagination. paginate.total is the flat visible count; legacy toPaginate aliases remain. Out-of-range pages clamp before slicing. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "q", "in": "query", "required": false, "description": "Search query text (optional)", "schema": { "type": "string" } }, { "name": "categorySlug", "in": "query", "required": false, "description": "Filter by category slug", "schema": { "type": "string" } }, { "name": "listingFilterKey", "in": "query", "required": false, "description": "Exact canonical listing chip key matched against the product labels field", "schema": { "type": "string", "minLength": 1, "maxLength": 50 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order: recommended, price-asc, price-desc, name-asc", "schema": { "type": "string", "enum": [ "recommended", "price-asc", "price-desc", "name-asc" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Items per page (default 24, max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultItem" } }, "paginate": { "$ref": "#/components/schemas/Pagination" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_search", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/site/categories": { "get": { "tags": [ "Site" ], "summary": "Get public category list", "description": "Returns the complete shop-scoped category tree with parentId and status. Clients hide status=false entries.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "Category list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/SiteCategory" } } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_site_categories", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/site/newsletter/subscribe": { "post": { "tags": [ "Site" ], "summary": "Subscribe an email address to the shop newsletter", "description": "Idempotently stores a shop-scoped encrypted subscription.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "source": { "type": "string", "enum": [ "footer", "blog", "other" ] } } } } } }, "responses": { "200": { "description": "Subscription accepted" }, "400": { "description": "Invalid email" }, "429": { "description": "Rate limited" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_site_newsletter_subscribe", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/products/{slug}": { "get": { "tags": [ "Site" ], "summary": "Get product detail by slug", "description": "Returns full product detail for a storefront product by its URL slug. No bearer token required.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "slug", "in": "path", "required": true, "description": "Product URL slug", "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Product detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/ProductDetail" } } } } } }, "404": { "description": "Product not found" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_products_slug", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/pages/blog": { "get": { "tags": [ "Pages Public" ], "summary": "Get blog page with posts", "security": [ {}, {} ], "responses": { "200": { "description": "Blog page data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/BlogPage" } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_pages_blog", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/pages/contact": { "get": { "tags": [ "Pages Public" ], "summary": "Get contact page data (catalog only)", "security": [ {}, {} ], "responses": { "200": { "description": "Contact page data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/ContactPageCatalog" } } } } } }, "404": { "description": "Not available for active template" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_pages_contact", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/pages/categories": { "get": { "tags": [ "Pages Public" ], "summary": "Get categories CMS page (catalog only)", "security": [ {}, {} ], "responses": { "200": { "description": "Categories page data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/CategoriesPageCatalog" } } } } } }, "404": { "description": "Not available for active template" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_pages_categories", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/pages/products": { "get": { "tags": [ "Pages Public" ], "summary": "Get the catalog product listing CMS shell", "description": "Returns CMS-managed hero and filter chips. Product rows continue to come from GET /search.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "categorySlug", "in": "query", "required": false, "description": "Apply the matching category-specific listing override", "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Product listing page shell", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/SiteProductsPage" } } } } } }, "400": { "description": "Invalid category slug" }, "404": { "description": "Resource unavailable or category not found" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_pages_products", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/storefront/auth/register": { "post": { "tags": [ "Storefront Customer Auth" ], "summary": "Register an individual customer account", "description": "Does not create a session. Returns the same accepted response for existing and new email addresses.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "displayName", "email", "password" ], "properties": { "displayName": { "type": "string", "minLength": 2, "maxLength": 160 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "password": { "type": "string", "format": "password", "minLength": 10, "maxLength": 128 }, "deviceLabel": { "type": "string" }, "platform": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_auth_register", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/auth/verify-email": { "post": { "tags": [ "Storefront Customer Auth" ], "summary": "Verify email and create the first customer session", "security": [ {}, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string" }, "remember": { "type": "boolean", "default": false }, "deviceLabel": { "type": "string" }, "platform": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthTokenResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_auth_verify_email", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/auth/resend-verification": { "post": { "tags": [ "Storefront Customer Auth" ], "summary": "Resend an email verification token", "description": "Returns the same accepted response whether or not an eligible pending account exists.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_auth_resend_verification", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/auth/login": { "post": { "tags": [ "Storefront Customer Auth" ], "summary": "Login with a verified customer email", "security": [ {}, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "remember": { "type": "boolean", "default": false }, "deviceLabel": { "type": "string" }, "platform": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthTokenResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_auth_login", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/auth/refresh": { "post": { "tags": [ "Storefront Customer Auth" ], "summary": "Rotate an opaque refresh token", "description": "Reads the HttpOnly refresh cookie first. Body fallback is feature-flagged. Reuse revokes the token family.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "refreshToken": { "type": "string" }, "deviceLabel": { "type": "string" }, "platform": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthTokenResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_auth_refresh", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/auth/logout": { "post": { "tags": [ "Storefront Customer Auth" ], "summary": "Revoke the current customer session", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_auth_logout", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/auth/logout-all": { "post": { "tags": [ "Storefront Customer Auth" ], "summary": "Revoke every customer session and increment token version", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_auth_logout_all", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/auth/forgot-password": { "post": { "tags": [ "Storefront Customer Auth" ], "summary": "Request password reset without account enumeration", "security": [ {}, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_auth_forgot_password", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/auth/reset-password": { "post": { "tags": [ "Storefront Customer Auth" ], "summary": "Consume a reset token, revoke sessions, and require login", "security": [ {}, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token", "password" ], "properties": { "token": { "type": "string" }, "password": { "type": "string", "format": "password", "minLength": 10, "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_auth_reset_password", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/me": { "get": { "tags": [ "Storefront Customer Auth" ], "summary": "Return the safe customer account projection", "description": "Never returns CRM financial, tax, identity, address, notes, risk, password, or token fields.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMeResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_storefront_me", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false }, "patch": { "tags": [ "Storefront Customer Profile" ], "summary": "Update the account-owned display name with optimistic concurrency", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerProfileUpdateRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMeResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "patch_storefront_me", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/addresses": { "get": { "tags": [ "Storefront Customer Address" ], "summary": "List active addresses owned by the authenticated account", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressListResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_storefront_me_addresses", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false }, "post": { "tags": [ "Storefront Customer Address" ], "summary": "Create an encrypted account-owned address", "description": "Supports Idempotency-Key. The first address for each usage becomes its default.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "required": false }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressInput" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_storefront_me_addresses", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/addresses/{id}": { "get": { "tags": [ "Storefront Customer Address" ], "summary": "Get an owned active address", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_storefront_me_addresses_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false }, "patch": { "tags": [ "Storefront Customer Address" ], "summary": "Update an owned address using its version", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressUpdateRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "patch_storefront_me_addresses_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false }, "delete": { "tags": [ "Storefront Customer Address" ], "summary": "Soft-delete an owned address idempotently", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "delete_storefront_me_addresses_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/addresses/{id}/default-shipping": { "post": { "tags": [ "Storefront Customer Address" ], "summary": "Set the one active default shipping address", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_storefront_me_addresses_id_default_shipping", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/addresses/{id}/default-billing": { "post": { "tags": [ "Storefront Customer Address" ], "summary": "Set the one active default billing address", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAddressResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_storefront_me_addresses_id_default_billing", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/password/change": { "post": { "tags": [ "Storefront Customer Lifecycle" ], "summary": "Change password and revoke all sessions", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "currentPassword", "newPassword" ], "properties": { "currentPassword": { "type": "string", "format": "password" }, "newPassword": { "type": "string", "format": "password", "minLength": 10, "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_me_password_change", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/sessions": { "get": { "tags": [ "Storefront Customer Lifecycle" ], "summary": "List the account's safe session projection", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSessionListResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_storefront_me_sessions", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/sessions/{id}": { "delete": { "tags": [ "Storefront Customer Lifecycle" ], "summary": "Revoke an owned customer session", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "delete_storefront_me_sessions_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/email-change/request": { "post": { "tags": [ "Storefront Customer Lifecycle" ], "summary": "Request a verified email change", "description": "Requires the current password and sends a one-time token through the notification outbox.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "password", "newEmail" ], "properties": { "password": { "type": "string", "format": "password" }, "newEmail": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_me_email_change_request", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/email-change/confirm": { "post": { "tags": [ "Storefront Customer Lifecycle" ], "summary": "Consume the email-change token", "description": "Changes the account identity, unlinks stale CRM ownership, moves the claim to manual review, and revokes sessions.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 32, "maxLength": 512 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_me_email_change_confirm", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/close-account": { "post": { "tags": [ "Storefront Customer Lifecycle" ], "summary": "Close an account after commerce guards", "description": "Fails closed while open orders exist; otherwise releases owned open carts/reservations and revokes sessions.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "password" ], "properties": { "password": { "type": "string", "format": "password" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_me_close_account", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/data-export": { "get": { "tags": [ "Storefront Customer Lifecycle" ], "summary": "Export account-owned safe commerce data", "description": "Returns owned profile, addresses, favorite product IDs, and orders; no password/token/ciphertext, product buying cost, or unrelated CRM data.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAuthAcceptedResponse" } } } }, "400": { "description": "Validation or token error" }, "401": { "description": "Authentication failed" }, "429": { "description": "Customer auth rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_storefront_me_data_export", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/favorites": { "get": { "tags": [ "Storefront Customer Favorites" ], "summary": "List the authenticated customer's product favorites", "description": "Favorites are isolated by resolved shop and customer account. Unavailable products remain removable and are returned with product=null.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Paginated favorite list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerFavoriteListResponse" } } } }, "401": { "description": "Customer authentication required" }, "403": { "description": "Verified customer or matching shop required" }, "429": { "description": "Customer profile rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_me_favorites", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/me/favorites/{productId}": { "post": { "tags": [ "Storefront Customer Favorites" ], "summary": "Add a storefront product to favorites", "description": "Idempotent. Repeating the same request returns created=false without creating a duplicate.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Storefront product ID" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Favorite added or already present", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerFavoriteMutationResponse" } } } }, "401": { "description": "Customer authentication required" }, "403": { "description": "Verified customer or matching shop required" }, "404": { "description": "Storefront-visible product not found in this shop" }, "429": { "description": "Customer profile rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_storefront_me_favorites_productId", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false }, "delete": { "tags": [ "Storefront Customer Favorites" ], "summary": "Remove a product from favorites", "description": "Idempotent. Removing an absent product returns removed=false.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Storefront product ID" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Favorite removed or already absent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerFavoriteMutationResponse" } } } }, "401": { "description": "Customer authentication required" }, "403": { "description": "Verified customer or matching shop required" }, "429": { "description": "Customer profile rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "delete_storefront_me_favorites_productId", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/cart": { "post": { "tags": [ "Storefront Cart" ], "summary": "Create or get current e-commerce cart", "description": "Returns the safe cart in result, with an opaque guestCartToken inside result for guest bootstrap/retrieval. Explicit branchId must be an active branch of this shop; absent/null/empty selects its first active branch. Idempotency replay reauthorizes the current cart owner; anonymous bootstrap recovery requires the original still-active guest grant. A different owner or revoked/merged/missing grant cannot recover the cached cart.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "x-guest-cart-token", "in": "header", "description": "Guest cart token bearer header for cross-origin storefronts. HttpOnly cookie is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "branchId": { "type": "string", "nullable": true, "description": "Trimmed owned active branch ObjectId; absent/null/empty uses first active owned branch." }, "guestCartToken": { "type": "string", "description": "Optional opaque guest capability body fallback." } } } } } }, "responses": { "200": { "description": "Cart created or retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartCreateResponse" } } } }, "400": { "description": "Missing, inactive, foreign or invalid branch; storefrontCart.branchRequired." }, "404": { "description": "Cached cart is unavailable to this owner; storefrontCart.notFound." }, "429": { "description": "Storefront cart rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_storefront_cart", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false }, "get": { "tags": [ "Storefront Cart" ], "summary": "Get current cart", "description": "Returns the current customer or guest cart with safe projection. Requires cart owner identification.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "x-guest-cart-token", "in": "header", "description": "Guest cart token bearer header for cross-origin storefronts. HttpOnly cookie is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Current owned cart in result", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean", "enum": [ true ] }, "result": { "$ref": "#/components/schemas/StorefrontCartSafe" }, "code": { "type": "string" }, "messageCode": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Cart owner identification required" }, "404": { "description": "Cart not found" }, "429": { "description": "Storefront cart rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_cart", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false }, "delete": { "tags": [ "Storefront Cart" ], "summary": "Clear current cart", "description": "Cancels the current e-commerce cart. Idempotent.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "x-guest-cart-token", "in": "header", "description": "Guest cart token bearer header for cross-origin storefronts. HttpOnly cookie is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean", "enum": [ true ] }, "result": { "$ref": "#/components/schemas/StorefrontCartSafe" }, "code": { "type": "string" }, "messageCode": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Validation or business rule error" }, "401": { "description": "Authentication or ownership required" }, "404": { "description": "Cart not found" }, "409": { "description": "Conflict (duplicate item, stale update, merge conflict)" }, "429": { "description": "Storefront cart rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "delete_storefront_cart", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/cart/items": { "post": { "tags": [ "Storefront Cart" ], "summary": "Add item to cart", "description": "Add quantity 1..99 (serialized products remain limited to 1). Products from different active branches of the same shop may share one cart; each item retains its stock-owning branch for reservation and fulfillment grouping. Idempotent receipts require the same current cart owner. Does NOT reserve product stock.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "x-guest-cart-token", "in": "header", "description": "Guest cart token bearer header for cross-origin storefronts. HttpOnly cookie is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartAddItemRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean", "enum": [ true ] }, "result": { "$ref": "#/components/schemas/StorefrontCartSafe" }, "code": { "type": "string" }, "messageCode": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Validation or business rule error" }, "401": { "description": "Authentication or ownership required" }, "404": { "description": "Cart not found" }, "409": { "description": "Conflict (duplicate item, stale update, merge conflict)" }, "429": { "description": "Storefront cart rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_storefront_cart_items", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/cart/items/{productId}": { "put": { "tags": [ "Storefront Cart" ], "summary": "Update cart item quantity", "description": "Update quantity 1..99 (serialized products remain limited to 1) and recompute server-owned totals. Idempotent receipts require the same current cart owner.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "x-guest-cart-token", "in": "header", "description": "Guest cart token bearer header for cross-origin storefronts. HttpOnly cookie is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartUpdateItemRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean", "enum": [ true ] }, "result": { "$ref": "#/components/schemas/StorefrontCartSafe" }, "code": { "type": "string" }, "messageCode": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Validation or business rule error" }, "401": { "description": "Authentication or ownership required" }, "404": { "description": "Cart not found" }, "409": { "description": "Conflict (duplicate item, stale update, merge conflict)" }, "429": { "description": "Storefront cart rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "put_storefront_cart_items_productId", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false }, "delete": { "tags": [ "Storefront Cart" ], "summary": "Remove item from cart", "description": "Remove a product from the current e-commerce cart. Idempotent (no-op if item not found). Does NOT release product reservation.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "x-guest-cart-token", "in": "header", "description": "Guest cart token bearer header for cross-origin storefronts. HttpOnly cookie is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product ID to remove" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean", "enum": [ true ] }, "result": { "$ref": "#/components/schemas/StorefrontCartSafe" }, "code": { "type": "string" }, "messageCode": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Validation or business rule error" }, "401": { "description": "Authentication or ownership required" }, "404": { "description": "Cart not found" }, "409": { "description": "Conflict (duplicate item, stale update, merge conflict)" }, "429": { "description": "Storefront cart rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "delete_storefront_cart_items_productId", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/cart/revalidate": { "post": { "tags": [ "Storefront Cart" ], "summary": "Revalidate cart server-side", "description": "Compare all cart items against current product state. Returns item-level results including price changes and availability. Does NOT modify cart items.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "x-guest-cart-token", "in": "header", "description": "Guest cart token bearer header for cross-origin storefronts. HttpOnly cookie is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Validation results in result", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean", "enum": [ true ] }, "result": { "$ref": "#/components/schemas/CartValidationResult" }, "code": { "type": "string" }, "messageCode": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Cart owner identification required" }, "429": { "description": "Storefront cart rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_storefront_cart_revalidate", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/cart/merge": { "post": { "tags": [ "Storefront Cart" ], "summary": "Merge guest cart into customer cart", "description": "Merge a guest cart (identified by cookie/token) into the authenticated customer's cart. Idempotent via mergeOperationId. Guest token is revoked after successful merge.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "x-guest-cart-token", "in": "header", "description": "Guest cart token bearer header for cross-origin storefronts. HttpOnly cookie is also supported.", "required": false, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartMergeRequest" } } } }, "responses": { "200": { "description": "Merge completed in result; cached receipt requires authenticated destination owner", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean", "enum": [ true ] }, "result": { "$ref": "#/components/schemas/CartMergeResult" }, "code": { "type": "string" }, "messageCode": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Guest token required" }, "401": { "description": "Guest session expired or invalid" }, "403": { "description": "Account not active" }, "404": { "description": "Cached destination cart is unavailable to this owner; storefrontCart.notFound." }, "409": { "description": "Merge conflict" }, "429": { "description": "Storefront cart merge rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_storefront_cart_merge", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/payments/config": { "get": { "tags": [ "Ecommerce Checkout" ], "summary": "Read shop online payment methods", "security": [ {}, {} ], "responses": { "200": { "description": "Runtime capability; mock never collects real money", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "mock", "manual", "disabled" ] }, "realCollection": { "type": "boolean", "enum": [ false ] }, "methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "credit-card", "bank-transfer" ] }, "provider": { "type": "string", "enum": [ "mock", "manual" ] }, "mode": { "type": "string", "enum": [ "mock", "manual" ] } } } } } } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_storefront_payments_config", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/payments/bank-accounts": { "get": { "tags": [ "Ecommerce Checkout" ], "summary": "List active shop recipient bank accounts", "description": "Returns only active shop-owned recipient accounts to a verified, linked customer. Historical receipt snapshots are unaffected when an account is disabled.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "responses": { "200": { "description": "Active recipient accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "bankName": { "type": "string" }, "iban": { "type": "string" }, "accountHolder": { "type": "string" } } } } } } } } }, "403": { "description": "Verified linked customer required" }, "429": { "description": "Rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_storefront_payments_bank_accounts", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/payments/orders/{orderId}/receipts": { "get": { "tags": [ "Ecommerce Checkout" ], "summary": "List bank-transfer receipt batches for an owned order", "description": "Lets the signed-in customer see review status and a rejection reason before uploading a replacement batch.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Receipt batches, newest first" }, "403": { "description": "Verified linked customer required" }, "404": { "description": "Owned order not found" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_payments_orders_orderId_receipts", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false }, "post": { "tags": [ "Ecommerce Checkout" ], "summary": "Submit bank-transfer receipt images for an owned order", "description": "Accepts 1–5 compressed JPG, PNG, or WebP files and exactly one active recipient account ID per file. Files are stored in media storage; MongoDB stores references and immutable bank-account snapshots. A pending receipt batch removes the admin approval timeout for the manual review.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "bankAccountIds", "receipts" ], "properties": { "bankAccountIds": { "type": "string", "description": "JSON array of 1–5 account IDs in file order" }, "receipts": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "format": "binary" } } } } } } }, "responses": { "200": { "description": "Receipt batch submitted or replayed" }, "400": { "description": "Count, MIME, size, or idempotency validation failed" }, "404": { "description": "Owned order not found" }, "409": { "description": "Account inactive, order not editable, or a batch is already pending" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_storefront_payments_orders_orderId_receipts", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/payments/orders/{orderId}/receipts/{receiptId}/image": { "get": { "tags": [ "Ecommerce Checkout" ], "summary": "Read an owned payment receipt image", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "receiptId", "required": true, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "description": "Verified linked customer, shop and order ownership are required. Image responses are private/no-store; the public media bucket contains only encrypted receipt objects.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "responses": { "200": { "description": "Receipt image", "content": { "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Customer authentication required" }, "404": { "description": "Owned receipt not found" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_payments_orders_orderId_receipts_receiptId_image", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/delivery-methods": { "get": { "tags": [ "E-commerce Checkout" ], "summary": "List active storefront delivery methods", "description": "Returns real same-shop delivery method IDs and active pickup branches without staff authentication.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ {}, {} ], "responses": { "200": { "description": "Active delivery methods", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontDeliveryMethod" } } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_storefront_delivery_methods", "x-sarraf-auth": "public", "x-sarraf-mcp-read": false } }, "/storefront/cart/checkout/prepare": { "post": { "tags": [ "E-commerce Checkout" ], "summary": "Prepare checkout session with quote and reservations", "description": "Revalidates the cart, computes product and delivery prices from same-shop server records, validates pickup or shipping requirements, acquires reservations, and creates a versioned quote. Quoted product prices are fixed until expiresAt (default 120 seconds); market-source ticks do not invalidate this lease. Explicit renewal prepares current prices. Client shipping cost, amount, and currency are not authoritative. Cache-Control: private, no-store.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutPrepareRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutPrepareResponse" } } } }, "400": { "description": "Validation error (empty cart, delivery required, missing address, missing idempotency key, missing sessionId)" }, "403": { "description": "Account inactive, email not verified, customer not linked, or cart ownership mismatch" }, "404": { "description": "Cart not found" }, "409": { "description": "Cart validation failed (unavailable item, branch conflict, currency conflict)" }, "429": { "description": "Checkout rate limit exceeded" }, "503": { "description": "Both storefront payment methods are disabled for this shop. Shared rate-limit state outages also reject the request before its handler executes." } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_cart_checkout_prepare", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/cart/checkout/renew": { "post": { "tags": [ "E-commerce Checkout" ], "summary": "Explicitly release an owned immutable quote before preparing a replacement", "description": "The quote CAS, stock reservation release and stock ledger commit atomically. A retry does not release a later quote. A submitting or consumed quote cannot be renewed. Cache-Control: private, no-store.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRenewRequest" } } } }, "responses": { "200": { "description": "Quote released (or idempotent replay)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "type": "object", "properties": { "renewed": { "type": "boolean" }, "replay": { "type": "boolean" } } } } } } } }, "400": { "description": "Invalid reference" }, "403": { "description": "Customer authentication required" }, "409": { "description": "Quote changed or submission in progress" }, "429": { "description": "Rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "post_storefront_cart_checkout_renew", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/cart/checkout/submit": { "post": { "tags": [ "E-commerce Checkout" ], "summary": "Submit checkout and create order", "description": "Revalidates current product availability/source health, price definitions, delivery rules, addresses and contracts while using the server-owned prices of the unexpired quote. Market-source ticks alone do not require renewal. Price-definition/manual-price, cart, address, delivery or contract changes still fail closed. Expiry is checked again at the atomic first order write. Idempotently converts the session into an order and payment attempt. Address snapshot failure creates no order. The Idempotency-Key header is required. Cache-Control: private, no-store.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "required": true, "description": "Unique idempotency key for at-most-once submission" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSubmitRequest" } } } }, "responses": { "200": { "description": "Order created or idempotent replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSubmitResponse" } } } }, "400": { "description": "Validation error (empty cart, delivery required, missing address, missing idempotency key, missing sessionId)" }, "403": { "description": "Account inactive, email not verified, customer not linked, or cart ownership mismatch" }, "404": { "description": "Cart not found" }, "409": { "description": "Cart validation failed (unavailable item, branch conflict, currency conflict)" }, "429": { "description": "Checkout rate limit exceeded" }, "503": { "description": "Both storefront payment methods are disabled for this shop. Shared rate-limit state outages also reject the request before its handler executes." } }, "operationId": "post_storefront_cart_checkout_submit", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/cart/checkout/status": { "get": { "tags": [ "E-commerce Checkout" ], "summary": "Get checkout session status", "description": "Returns the current status of an active or converted checkout session. Cache-Control: private, no-store.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "query", "name": "sessionId", "schema": { "type": "string" }, "description": "Owned checkout session ID; supply sessionId or cartId." }, { "in": "query", "name": "cartId", "schema": { "type": "string" }, "description": "Find the active owned quote for this cart; null when no active quote exists." }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Checkout session status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutStatusResponse" } } } }, "400": { "description": "Missing sessionId parameter" }, "403": { "description": "Session ownership mismatch" }, "404": { "description": "Session not found" }, "429": { "description": "Checkout rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_cart_checkout_status", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/payments/attempts": { "post": { "tags": [ "E-commerce Checkout" ], "summary": "Create an idempotent storefront payment attempt", "description": "Creates a durable attempt before provider invocation and reads amount/currency only from the owned order. A partial unique index permits one active payment-phase attempt per order; a different concurrent key returns payment.attemptAlreadyActive while the same key replays. Provider result is checkpointed for worker recovery. Enabled credit-card uses the fixed mock provider in every environment and records manually_confirmed/not_posted until admin approval posts one providerMode=mock cashbox movement; it never charges a real card. Enabled bank-transfer requires a submitted receipt batch and stays pending for admin review. Availability is controlled by shop settings; existing idempotent attempts remain recoverable after disabling the method. Cache-Control: private, no-store.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontPaymentAttemptCreate" } } } }, "responses": { "200": { "description": "Attempt created or replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontPaymentAttempt" } } } }, "400": { "description": "Invalid return URL or idempotency key" }, "404": { "description": "Owned order not found" }, "409": { "description": "Idempotency conflict, active attempt, or non-payable order" }, "503": { "description": "Selected payment method disabled for this shop Shared rate-limit state outages also reject the request before its handler executes." } }, "operationId": "post_storefront_payments_attempts", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/payments/orders/{orderId}": { "get": { "tags": [ "E-commerce Checkout" ], "summary": "Get the latest payment attempt of an owned order", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Customer-safe attempt or null; includes checkout/payment phase. Cache-Control: private, no-store.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "result": { "allOf": [ { "$ref": "#/components/schemas/StorefrontPaymentAttempt" } ], "nullable": true } } } } } }, "403": { "description": "Customer authentication required" }, "404": { "description": "Owned order not found" }, "429": { "description": "Rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_payments_orders_orderId", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/payments/attempts/{id}": { "get": { "tags": [ "E-commerce Checkout" ], "summary": "Get an owned storefront payment attempt", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Payment attempt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontPaymentAttempt" } } } }, "404": { "description": "Attempt not found or not owned" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_payments_attempts_id", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/orders": { "get": { "tags": [ "Storefront Customer Orders" ], "summary": "List authenticated customer's e-commerce orders", "description": "Returns a paginated list of orders belonging to the authenticated customer. Only e-commerce orders are visible. Cache-Control: private, no-store.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "in": "query", "name": "q", "schema": { "type": "string", "maxLength": 128 }, "description": "Literal search in own order number and item title." }, { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "required": false, "description": "Page number" }, { "in": "query", "name": "pageSize", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "description": "Items per page" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "pendingApproval", "confirmed", "cancellationPendingRefund", "cancelled", "expired", "completed", "returned" ] }, "required": false, "description": "Filter by canonical e-commerce order status" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Paginated order list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerOrderListResponse" } } } }, "400": { "description": "Validation error (cancellation not allowed for current status)" }, "401": { "description": "Authentication failed" }, "403": { "description": "Account not verified or not linked to a customer" }, "404": { "description": "Order not found" }, "429": { "description": "Order detail rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_orders", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/orders/{publicId}": { "get": { "tags": [ "Storefront Customer Orders" ], "summary": "Get order detail for authenticated customer", "description": "Returns the full safe projection of an e-commerce order. Ownership is verified. Cache-Control: private, no-store.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public-facing order number (e.g., ECO-xxx-xxxx)" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Order detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerOrderDetailResponse" } } } }, "400": { "description": "Validation error (cancellation not allowed for current status)" }, "401": { "description": "Authentication failed" }, "403": { "description": "Account not verified or not linked to a customer" }, "404": { "description": "Order not found" }, "429": { "description": "Order detail rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_orders_publicId", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/orders/{publicId}/shipments": { "get": { "tags": [ "Storefront Customer Orders" ], "summary": "List order shipments", "description": "Returns safe shipment summaries for an owned order. Tracking URLs are HTTPS-only. Cache-Control: private, no-store.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public-facing order number (e.g., ECO-xxx-xxxx)" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Shipment list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerShipmentListResponse" } } } }, "400": { "description": "Validation error (cancellation not allowed for current status)" }, "401": { "description": "Authentication failed" }, "403": { "description": "Account not verified or not linked to a customer" }, "404": { "description": "Order not found" }, "429": { "description": "Order detail rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_orders_publicId_shipments", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/orders/{publicId}/timeline": { "get": { "tags": [ "Storefront Customer Orders" ], "summary": "Get order timeline", "description": "Returns a chronological timeline of order lifecycle events. Cache-Control: private, no-store.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public-facing order number (e.g., ECO-xxx-xxxx)" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Timeline entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerOrderTimelineResponse" } } } }, "400": { "description": "Validation error (cancellation not allowed for current status)" }, "401": { "description": "Authentication failed" }, "403": { "description": "Account not verified or not linked to a customer" }, "404": { "description": "Order not found" }, "429": { "description": "Order detail rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_storefront_orders_publicId_timeline", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/storefront/orders/{publicId}/cancellation-requests": { "post": { "tags": [ "Storefront Customer Orders" ], "summary": "Request order cancellation", "description": "Creates a cancellation request for an owned order. Idempotent — duplicate requests return the existing pending request. Only allowed for cancellable statuses. Cache-Control: private, no-store.\nShop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "security": [ { "customerBearerAuth": [] }, { "customerBearerAuth": [] } ], "parameters": [ { "name": "shop-code", "in": "header", "required": false, "schema": { "type": "string" }, "example": "magaza-kodunuz", "description": "Registered HTTPS Origin can select the shop automatically; server/local requests select it explicitly. This is tenant context, not authentication." }, { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Public-facing order number (e.g., ECO-xxx-xxxx)" }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancellationRequestCreate" } } } }, "responses": { "200": { "description": "Cancellation request created or existing request returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancellationRequestCreateResponse" } } } }, "400": { "description": "Cancellation not allowed for current order status" }, "401": { "description": "Authentication failed" }, "403": { "description": "Account not verified or not linked" }, "404": { "description": "Order not found" }, "429": { "description": "Order cancellation rate limit exceeded" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "post_storefront_orders_publicId_cancellation_requests", "x-sarraf-auth": "customer", "x-sarraf-mcp-read": false } }, "/geo/cities": { "get": { "tags": [ "Geo" ], "summary": "List Turkey provinces", "security": [], "responses": { "200": { "description": "Location list", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/GeoCity" } } } } } } }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "parameters": [ { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "operationId": "get_geo_cities", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } }, "/geo/districts": { "get": { "tags": [ "Geo" ], "summary": "List districts for a Turkey province", "security": [], "parameters": [ { "name": "cityId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{2}$" } }, { "name": "X-App-Locale", "in": "header", "required": false, "description": "Explicit application language. Missing or unsupported values use Turkish; Accept-Language is ignored. URLs and business data are unchanged.", "schema": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" } } ], "responses": { "200": { "description": "Location list", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/GeoDistrict" } } } } } } }, "400": { "description": "cityId is required" }, "404": { "description": "City not found" }, "503": { "$ref": "#/components/responses/RateLimitStoreUnavailable" } }, "operationId": "get_geo_districts", "description": "Shop context: a registered HTTPS Origin or an explicit shop-code header is required. Domain matching never grants account permissions.", "x-sarraf-auth": "public", "x-sarraf-mcp-read": true } } }, "components": { "schemas": { "I18nMessageCode": { "type": "object", "properties": { "messageCode": { "type": "string", "example": "common.notFound" }, "code": { "type": "string", "example": "common.notFound" }, "module": { "type": "string", "example": "common" }, "type": { "type": "string", "example": "error" }, "prop": { "type": "string", "example": "record" }, "fallbackMessage": { "type": "string", "example": "Record not found." } } }, "ApiError": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "code": { "type": "string", "example": "common.notFound" }, "messageCode": { "type": "string", "example": "common.notFound" }, "messageParams": { "type": "object", "additionalProperties": true, "description": "Interpolation parameters for the stable message code" }, "detailCode": { "type": "string", "description": "Optional stable operation validation reason" }, "prop": { "type": "string", "example": "record" }, "message": { "type": "string", "example": "Record not found." }, "details": {} } }, "Currency": { "type": "object", "properties": { "id": { "type": "string" }, "shopId": { "type": "string", "description": "Shop-wide price shared by every branch." }, "isSystem": { "type": "boolean", "readOnly": true, "description": "System definitions cannot be deleted or renamed; manual prices remain editable." }, "catalogUnavailable": { "type": "boolean", "readOnly": true, "description": "No observed provider quote; omitted from active automatic price display." }, "code": { "type": "string" }, "order": { "type": "number", "description": "List sort order. Lower values are listed first." }, "icon": { "type": "string", "nullable": true, "description": "Client-side icon code. Server stores it as a plain string." }, "title": { "type": "string" }, "quoteCurrency": { "type": "string", "nullable": true }, "unitCode": { "type": "string", "nullable": true }, "priceEligible": { "type": "boolean" }, "sourceReady": { "type": "boolean" }, "sourceUpdatedAt": { "type": "string", "format": "date-time", "nullable": true }, "parentCode": { "type": "string", "enum": [ "HAS", "GRAM", "XAUUSD", "AYAR22", "AYAR18", "AYAR14", "YCEYREK", "YYARIM", "YTAM", "YATA", "YGREMSE", "YATA5", "XAG", "TRY", "USD", "EUR", "AUD", "DKK", "GBP", "CHF", "SEK", "CAD", "KWD", "NOK", "SAR", "JPY", "BGN", "RON", "RUB", "CNY", "PKR", "QAR", "KRW", "AZN", "AED", "CEYREK", "YARIM", "TAM", "ATA", "ATA5", "GREMSE", "USDCHF", "AUDUSD", "USDJPY", "GBPUSD", "EURUSD", "EURKG", "USDCAD", "JODTRY", "USDPURE", "USDKG", "XAUXAG", "XAGUSD", "GUMUSUSD", "XPTUSD", "PLATIN", "XPDUSD", "PALADYUM", "USDSAR", "KWDUSD", "USDQAR", "JODUSD" ] }, "isManual": { "type": "boolean" }, "buyingKarat": { "type": "number" }, "sellingKarat": { "type": "number" }, "buying": { "type": "number" }, "selling": { "type": "number" }, "calcPiece": { "type": "number" }, "calcStep": { "type": "number" }, "calcPeriod": { "type": "number" }, "calcDecimal": { "type": "number" }, "minProfit": { "type": "number" }, "calcUpdateAt": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "boolean" }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableField" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "VariableField": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string" }, "value": {} } }, "SettingsBranch": { "type": "object", "properties": { "id": { "type": "string" }, "shopId": { "type": "string" }, "branchCode": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "boolean" }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableField" } } } }, "Product": { "type": "object", "properties": { "inventoryUnits": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/InventoryUnit" } }, "unitPendingLinks": { "type": "array", "readOnly": true, "items": { "type": "object" } }, "unitUnresolvedRevision": { "type": "integer", "readOnly": true }, "lastPriceChange": { "type": "object", "nullable": true, "description": "Latest accepted revision, occurredAt, reason and exact per-side changes" }, "priceHistoryRevision": { "type": "integer" }, "priceObservation": { "type": "object", "readOnly": true, "properties": { "state": { "type": "string", "enum": [ "current", "held", "unavailable" ] }, "buying": { "type": "object", "description": "Read-only rounded candidate unitPrice and lineLabour decimal strings" }, "selling": { "type": "object", "description": "Read-only rounded candidate unitPrice and lineLabour decimal strings" } } }, "pricing": { "$ref": "#/components/schemas/ProductPricing" }, "acceptedPricing": { "type": "object", "readOnly": true, "description": "Accepted revision, timestamp, independent unit/line prices, component breakdowns and source-rate witnesses. Reads never bypass configured thresholds." }, "id": { "type": "string" }, "shopId": { "type": "string" }, "branchId": { "type": "string" }, "cashboxId": { "type": "string", "nullable": true, "description": "Optional whole-stock location; same branch or shared cashbox. Does not post a metal balance." }, "currencyId": { "type": "string", "nullable": true }, "currencyCode": { "type": "string", "enum": [ "HAS", "GRAM", "XAUUSD", "AYAR22", "AYAR18", "AYAR14", "YCEYREK", "YYARIM", "YTAM", "YATA", "YGREMSE", "YATA5", "XAG", "TRY", "USD", "EUR", "AUD", "DKK", "GBP", "CHF", "SEK", "CAD", "KWD", "NOK", "SAR", "JPY", "BGN", "RON", "RUB", "CNY", "PKR", "QAR", "KRW", "AZN", "AED" ] }, "categoryIds": { "type": "array", "items": { "type": "string" } }, "groupIds": { "type": "array", "items": { "type": "string" } }, "imageIds": { "type": "array", "items": { "type": "string" } }, "coverImageId": { "type": "string" }, "images": { "type": "array", "readOnly": true, "description": "Product-detail gallery media in imageIds order.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" } } } }, "barcode": { "type": "string" }, "rfidEpc": { "type": "string", "nullable": true, "maxLength": 124, "pattern": "^(?!0+$)(?:[0-9A-F]{2}){1,62}$", "description": "Optional full UHF EPC, uppercase and unique per shop. Separate from barcode; leading zeroes retained." }, "title": { "type": "string" }, "status": { "type": "boolean" }, "salesStatus": { "type": "string", "enum": [ "available", "reserved", "sold", "transit" ] }, "inventoryMode": { "type": "string", "enum": [ "serialized", "quantity" ] }, "stockQuantityBasis": { "type": "string", "enum": [ "count", "net_weight" ] }, "physicalAssetCode": { "type": "string", "description": "Immutable physical metal type used only by net-weight inventory." }, "metalPricing": { "type": "string", "enum": [ "fine_gold", "net_gram" ] }, "stockOnHand": { "type": "number", "description": "Physical quantity balance; negative values are allowed for store operations and must be shown as warnings." }, "catalogActive": { "type": "boolean", "description": "Explicit catalog lifecycle, independent of physical stock availability." }, "reservedQuantity": { "type": "integer", "minimum": 0 }, "retailQuantityReservations": { "type": "array", "items": { "type": "object", "properties": { "cartId": { "type": "string", "nullable": true }, "orderId": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "minimum": 1, "maximum": 99 }, "status": { "type": "string", "enum": [ "active", "transferred" ] } } } }, "cartId": { "type": "string", "nullable": true }, "orderId": { "type": "string", "nullable": true }, "isManual": { "type": "boolean" }, "shortDescription": { "type": "string", "maxLength": 500 }, "description": { "type": "string", "maxLength": 20000, "description": "Newline characters are preserved." }, "labels": { "type": "array", "items": { "type": "string" } }, "unitCode": { "type": "string", "enum": [ "C62", "PR", "DAY", "WEE", "MON", "ANN", "MIN", "SEC", "HUR", "CMQ", "MMQ", "CMT", "CMK", "KTM", "MLT", "MMT", "B32", "CCT", "D30", "D40", "GRM", "GT", "KGM", "KWH", "LPA", "LTR", "MTK", "MTQ", "MTR", "NCL", "R9", "SET", "T3", "MGM", "TNE", "KJO", "CLT", "BX", "PA", "FTK", "DMK", "RO", "SA", "BJ", "PK", "LK", "DR", "CG", "CS", "JR", "NPL", "M43", "PF", "BG", "BK", "BO", "H87", "TN", "26", "TU", "G52", "K51", "J39", "SM3", "CT" ] }, "piece": { "type": "number" }, "buying": { "type": "number" }, "selling": { "type": "number", "nullable": true, "description": "Null only for a consignment product whose selling price has not been set." }, "buyingKarat": { "type": "number" }, "sellingKarat": { "type": "number" }, "compareAtPrice": { "type": "number", "nullable": true, "minimum": 0 }, "taxRate": { "type": "number", "minimum": 0, "maximum": 1 }, "calcStep": { "type": "number" }, "calcPeriod": { "type": "number" }, "calcDecimal": { "type": "number" }, "calcUpdateAt": { "type": "string", "format": "date-time", "nullable": true }, "salesChannel": { "type": "string", "enum": [ "b2b", "ecommerce", "store" ] }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableField" } } } }, "InventoryUnit": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Stable physical identity, including preserved legacy unit identifiers. RFID/TID/read count is not this identity." }, "barcode": { "type": "string", "nullable": true, "maxLength": 128 }, "rfidEpc": { "type": "string", "nullable": true, "pattern": "^(?:[0-9A-F]{2}){1,62}$" }, "state": { "type": "string", "enum": [ "in_stock", "sold", "transit", "retired", "missing" ] }, "revision": { "type": "integer", "minimum": 1 }, "branchId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "nullable": true }, "weightGrams": { "type": "string" }, "karat": { "type": "integer", "minimum": 1, "maximum": 24 }, "purityMilli": { "type": "string" }, "receivedAt": { "type": "string", "format": "date-time" }, "operationId": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "id", "state", "revision" ] }, "ProductPricing": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "purityMilli": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" }, "netWeight": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" }, "saleStrategy": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "manual_price" ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "minimum_profit" ] }, "kind": { "type": "string", "enum": [ "percent", "amount" ] }, "value": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "mode", "kind", "value" ], "additionalProperties": false } ] }, "buying": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "fixed", "source" ] }, "amount": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" }, "sourceId": { "type": "string", "minLength": 1 }, "multiplier": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" }, "workmanship": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "millesimal" ] }, "chargedPurityMilli": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "kind", "chargedPurityMilli" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "percentage" ] }, "percent": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" }, "included": { "type": "boolean" } }, "required": [ "kind", "percent", "included" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "fixed" ] }, "amount": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "kind", "amount" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "asset" ] }, "sourceId": { "type": "string", "minLength": 1 }, "quantity": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "kind", "sourceId", "quantity" ], "additionalProperties": false } ] }, "threshold": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "amount", "percent" ] }, "value": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "mode" ], "additionalProperties": false }, "rounding": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "off", "nearest", "up", "down" ] }, "step": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "direction" ], "additionalProperties": false } }, "required": [ "mode", "workmanship", "threshold", "rounding" ], "additionalProperties": false }, "selling": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "fixed", "source" ] }, "amount": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" }, "sourceId": { "type": "string", "minLength": 1 }, "multiplier": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" }, "workmanship": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "millesimal" ] }, "chargedPurityMilli": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "kind", "chargedPurityMilli" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "percentage" ] }, "percent": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" }, "included": { "type": "boolean" } }, "required": [ "kind", "percent", "included" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "fixed" ] }, "amount": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "kind", "amount" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "asset" ] }, "sourceId": { "type": "string", "minLength": 1 }, "quantity": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "kind", "sourceId", "quantity" ], "additionalProperties": false } ] }, "threshold": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "amount", "percent" ] }, "value": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "mode" ], "additionalProperties": false }, "rounding": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "off", "nearest", "up", "down" ] }, "step": { "type": "string", "pattern": "^\\d{1,16}(\\.\\d{1,8})?$" } }, "required": [ "direction" ], "additionalProperties": false } }, "required": [ "mode", "workmanship", "threshold", "rounding" ], "additionalProperties": false } }, "required": [ "version", "buying", "selling" ], "additionalProperties": false, "description": "Version 1: backwards-compatible independent buying/selling rules plus an optional manual-price or minimum-profit sale strategy. Workmanship may be millesimal, percentage, fixed TRY per unit, or an advanced asset amount. Decimal values are strings; physical purity is distinct from charged purity." }, "ProductInput": { "type": "object", "required": [ "branchId", "barcode", "title" ], "properties": { "pricing": { "$ref": "#/components/schemas/ProductPricing" }, "branchId": { "type": "string" }, "cashboxId": { "type": "string", "nullable": true, "description": "Optional whole-stock location; same branch or shared cashbox. Does not post a metal balance." }, "currencyId": { "type": "string", "nullable": true }, "currencyCode": { "type": "string", "enum": [ "HAS", "GRAM", "XAUUSD", "AYAR22", "AYAR18", "AYAR14", "YCEYREK", "YYARIM", "YTAM", "YATA", "YGREMSE", "YATA5", "XAG", "TRY", "USD", "EUR", "AUD", "DKK", "GBP", "CHF", "SEK", "CAD", "KWD", "NOK", "SAR", "JPY", "BGN", "RON", "RUB", "CNY", "PKR", "QAR", "KRW", "AZN", "AED" ] }, "categoryIds": { "type": "array", "items": { "type": "string" } }, "groupIds": { "type": "array", "items": { "type": "string" } }, "imageIds": { "type": "array", "items": { "type": "string" } }, "coverImageId": { "type": "string" }, "barcode": { "type": "string", "minLength": 1, "maxLength": 15, "description": "Unique per shop (`shopId + barcode` unique index). Letters, digits and hyphens are accepted." }, "rfidEpc": { "type": "string", "nullable": true, "maxLength": 124, "pattern": "^(?!0+$)(?:[0-9A-Fa-f]{2}){1,62}$", "description": "Full UHF EPC; trimmed and uppercased. Unique per shop. Null removes mapping; never substitutes the barcode or a TID." }, "title": { "type": "string" }, "status": { "type": "boolean" }, "inventoryMode": { "type": "string", "enum": [ "serialized", "quantity" ], "default": "serialized" }, "stockQuantityBasis": { "type": "string", "enum": [ "count", "net_weight" ], "description": "Immutable after creation. Net weight requires quantity inventory and store channel." }, "physicalAssetCode": { "type": "string", "enum": [ "HAS", "GRAM", "XAUUSD", "AYAR22", "AYAR18", "AYAR14", "YCEYREK", "YYARIM", "YTAM", "YATA", "YGREMSE", "YATA5", "XAG", "TRY", "USD", "EUR", "AUD", "DKK", "GBP", "CHF", "SEK", "CAD", "KWD", "NOK", "SAR", "JPY", "BGN", "RON", "RUB", "CNY", "PKR", "QAR", "KRW", "AZN", "AED" ], "description": "Required and accepted only for net-weight stock; physical metal and price source are independent." }, "metalPricing": { "type": "string", "enum": [ "fine_gold", "net_gram" ], "description": "Net gram uses manual prices; fine gold uses frozen HAS price and actual assay." }, "stockOnHand": { "type": "number", "description": "Initial quantity stock, including a reported shortage. Later changes require the stock-adjustments endpoint." }, "isManual": { "type": "boolean" }, "shortDescription": { "type": "string", "maxLength": 500 }, "description": { "type": "string", "maxLength": 20000, "description": "Newline characters are preserved." }, "labels": { "type": "array", "items": { "type": "string" } }, "unitCode": { "type": "string", "enum": [ "C62", "PR", "DAY", "WEE", "MON", "ANN", "MIN", "SEC", "HUR", "CMQ", "MMQ", "CMT", "CMK", "KTM", "MLT", "MMT", "B32", "CCT", "D30", "D40", "GRM", "GT", "KGM", "KWH", "LPA", "LTR", "MTK", "MTQ", "MTR", "NCL", "R9", "SET", "T3", "MGM", "TNE", "KJO", "CLT", "BX", "PA", "FTK", "DMK", "RO", "SA", "BJ", "PK", "LK", "DR", "CG", "CS", "JR", "NPL", "M43", "PF", "BG", "BK", "BO", "H87", "TN", "26", "TU", "G52", "K51", "J39", "SM3", "CT" ] }, "piece": { "type": "number" }, "buying": { "type": "number" }, "selling": { "type": "number" }, "buyingKarat": { "type": "number" }, "sellingKarat": { "type": "number" }, "compareAtPrice": { "type": "number", "nullable": true, "minimum": 0 }, "taxRate": { "type": "number", "minimum": 0, "maximum": 1 }, "calcStep": { "type": "number" }, "calcPeriod": { "type": "number" }, "calcDecimal": { "type": "number" }, "salesChannel": { "type": "string", "enum": [ "b2b", "ecommerce", "store" ] }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableField" } } } }, "ProductPriceHistory": { "type": "object", "properties": { "id": { "type": "string" }, "shopId": { "type": "string" }, "productId": { "type": "string" }, "branchId": { "type": "string" }, "cashboxId": { "type": "string", "nullable": true, "description": "Optional whole-stock location; same branch or shared cashbox. Does not post a metal balance." }, "revision": { "type": "integer" }, "occurredAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "enum": [ "baseline", "settings", "source" ] }, "userId": { "type": "string", "nullable": true }, "before": { "type": "object", "nullable": true, "description": "Previous exact prices, definition and accepted component/rate witnesses" }, "after": { "type": "object", "description": "Accepted exact buying/selling prices, weighted flag, pricing and acceptedPricing" }, "changes": { "type": "object", "nullable": true, "description": "Per-side before/after/delta/percent decimal strings and independent line labour" } } }, "ProductUpdateInput": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "pricing": { "$ref": "#/components/schemas/ProductPricing" }, "cashboxId": { "type": "string", "nullable": true, "description": "Optional whole-stock location; same branch or shared cashbox. Does not post a metal balance." }, "currencyId": { "type": "string", "nullable": true }, "currencyCode": { "type": "string", "enum": [ "HAS", "GRAM", "XAUUSD", "AYAR22", "AYAR18", "AYAR14", "YCEYREK", "YYARIM", "YTAM", "YATA", "YGREMSE", "YATA5", "XAG", "TRY", "USD", "EUR", "AUD", "DKK", "GBP", "CHF", "SEK", "CAD", "KWD", "NOK", "SAR", "JPY", "BGN", "RON", "RUB", "CNY", "PKR", "QAR", "KRW", "AZN", "AED" ] }, "categoryIds": { "type": "array", "items": { "type": "string" } }, "groupIds": { "type": "array", "items": { "type": "string" } }, "imageIds": { "type": "array", "items": { "type": "string" } }, "coverImageId": { "type": "string" }, "barcode": { "type": "string", "minLength": 1, "maxLength": 15, "description": "Unique per shop (`shopId + barcode` unique index). Letters, digits and hyphens are accepted." }, "rfidEpc": { "type": "string", "nullable": true, "maxLength": 124, "pattern": "^(?!0+$)(?:[0-9A-Fa-f]{2}){1,62}$", "description": "Full UHF EPC; trimmed and uppercased. Unique per shop. Null removes mapping; never substitutes the barcode or a TID." }, "title": { "type": "string" }, "status": { "type": "boolean" }, "metalPricing": { "type": "string", "enum": [ "fine_gold", "net_gram" ], "description": "Net gram uses manual prices; fine gold uses frozen HAS price and actual assay." }, "isManual": { "type": "boolean" }, "shortDescription": { "type": "string", "maxLength": 500 }, "description": { "type": "string", "maxLength": 20000, "description": "Newline characters are preserved." }, "labels": { "type": "array", "items": { "type": "string" } }, "unitCode": { "type": "string", "enum": [ "C62", "PR", "DAY", "WEE", "MON", "ANN", "MIN", "SEC", "HUR", "CMQ", "MMQ", "CMT", "CMK", "KTM", "MLT", "MMT", "B32", "CCT", "D30", "D40", "GRM", "GT", "KGM", "KWH", "LPA", "LTR", "MTK", "MTQ", "MTR", "NCL", "R9", "SET", "T3", "MGM", "TNE", "KJO", "CLT", "BX", "PA", "FTK", "DMK", "RO", "SA", "BJ", "PK", "LK", "DR", "CG", "CS", "JR", "NPL", "M43", "PF", "BG", "BK", "BO", "H87", "TN", "26", "TU", "G52", "K51", "J39", "SM3", "CT" ] }, "piece": { "type": "number" }, "buying": { "type": "number" }, "selling": { "type": "number" }, "buyingKarat": { "type": "number" }, "sellingKarat": { "type": "number" }, "compareAtPrice": { "type": "number", "nullable": true, "minimum": 0 }, "taxRate": { "type": "number", "minimum": 0, "maximum": 1 }, "calcStep": { "type": "number" }, "calcPeriod": { "type": "number" }, "calcDecimal": { "type": "number" }, "salesChannel": { "type": "string", "enum": [ "b2b", "ecommerce", "store" ] }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableField" } } } }, "ProductManagementDetail": { "type": "object", "required": [ "presentation", "product" ], "properties": { "presentation": { "type": "string", "enum": [ "management-v1" ] }, "product": { "type": "object", "required": [ "id" ], "description": "Projected editable metadata and resolved prices/gallery, excluding inventory units, reservations, internal journals and unit costs. Stored stock scalars are not canonical availability.", "properties": { "priceObservation": { "type": "object", "readOnly": true, "properties": { "state": { "type": "string", "enum": [ "current", "held", "unavailable" ] }, "buying": { "type": "object", "description": "Read-only rounded candidate unitPrice and lineLabour decimal strings" }, "selling": { "type": "object", "description": "Read-only rounded candidate unitPrice and lineLabour decimal strings" } } }, "pricing": { "$ref": "#/components/schemas/ProductPricing" }, "acceptedPricing": { "type": "object", "readOnly": true, "description": "Accepted revision, timestamp, independent unit/line prices, component breakdowns and source-rate witnesses. Reads never bypass configured thresholds." }, "id": { "type": "string" }, "shopId": { "type": "string" }, "branchId": { "type": "string" }, "cashboxId": { "type": "string", "nullable": true, "description": "Optional whole-stock location; same branch or shared cashbox. Does not post a metal balance." }, "currencyId": { "type": "string", "nullable": true }, "currencyCode": { "type": "string", "enum": [ "HAS", "GRAM", "XAUUSD", "AYAR22", "AYAR18", "AYAR14", "YCEYREK", "YYARIM", "YTAM", "YATA", "YGREMSE", "YATA5", "XAG", "TRY", "USD", "EUR", "AUD", "DKK", "GBP", "CHF", "SEK", "CAD", "KWD", "NOK", "SAR", "JPY", "BGN", "RON", "RUB", "CNY", "PKR", "QAR", "KRW", "AZN", "AED" ] }, "categoryIds": { "type": "array", "items": { "type": "string" } }, "groupIds": { "type": "array", "items": { "type": "string" } }, "imageIds": { "type": "array", "items": { "type": "string" } }, "coverImageId": { "type": "string" }, "images": { "type": "array", "readOnly": true, "description": "Product-detail gallery media in imageIds order.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" } } } }, "barcode": { "type": "string" }, "rfidEpc": { "type": "string", "nullable": true, "maxLength": 124, "pattern": "^(?!0+$)(?:[0-9A-F]{2}){1,62}$", "description": "Optional full UHF EPC, uppercase and unique per shop. Separate from barcode; leading zeroes retained." }, "title": { "type": "string" }, "status": { "type": "boolean" }, "salesStatus": { "type": "string", "enum": [ "available", "reserved", "sold", "transit" ] }, "inventoryMode": { "type": "string", "enum": [ "serialized", "quantity" ] }, "stockQuantityBasis": { "type": "string", "enum": [ "count", "net_weight" ] }, "physicalAssetCode": { "type": "string", "description": "Immutable physical metal type used only by net-weight inventory." }, "metalPricing": { "type": "string", "enum": [ "fine_gold", "net_gram" ] }, "stockOnHand": { "type": "number", "description": "Physical quantity balance; negative values are allowed for store operations and must be shown as warnings." }, "catalogActive": { "type": "boolean", "description": "Explicit catalog lifecycle, independent of physical stock availability." }, "reservedQuantity": { "type": "integer", "minimum": 0 }, "isManual": { "type": "boolean" }, "shortDescription": { "type": "string", "maxLength": 500 }, "description": { "type": "string", "maxLength": 20000, "description": "Newline characters are preserved." }, "labels": { "type": "array", "items": { "type": "string" } }, "unitCode": { "type": "string", "enum": [ "C62", "PR", "DAY", "WEE", "MON", "ANN", "MIN", "SEC", "HUR", "CMQ", "MMQ", "CMT", "CMK", "KTM", "MLT", "MMT", "B32", "CCT", "D30", "D40", "GRM", "GT", "KGM", "KWH", "LPA", "LTR", "MTK", "MTQ", "MTR", "NCL", "R9", "SET", "T3", "MGM", "TNE", "KJO", "CLT", "BX", "PA", "FTK", "DMK", "RO", "SA", "BJ", "PK", "LK", "DR", "CG", "CS", "JR", "NPL", "M43", "PF", "BG", "BK", "BO", "H87", "TN", "26", "TU", "G52", "K51", "J39", "SM3", "CT" ] }, "piece": { "type": "number" }, "buying": { "type": "number" }, "selling": { "type": "number", "nullable": true, "description": "Null only for a consignment product whose selling price has not been set." }, "buyingKarat": { "type": "number" }, "sellingKarat": { "type": "number" }, "compareAtPrice": { "type": "number", "nullable": true, "minimum": 0 }, "taxRate": { "type": "number", "minimum": 0, "maximum": 1 }, "calcStep": { "type": "number" }, "calcPeriod": { "type": "number" }, "calcDecimal": { "type": "number" }, "calcUpdateAt": { "type": "string", "format": "date-time", "nullable": true }, "salesChannel": { "type": "string", "enum": [ "b2b", "ecommerce", "store" ] }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableField" } }, "companyDefinitionId": { "type": "string" }, "companyPositionId": { "type": "string" }, "companyDefinitionRevision": { "type": "integer" }, "companyPricingStatus": { "type": "string", "enum": [ "priced", "unpriced", "legacy_preserved" ] }, "consignment": { "type": "object", "description": "Only version/item/party/terms/lot/supplier/ecommerceEnabled and agreement currency/unitAmount/hasRateSide metadata; no cost arrays." }, "coverImageUrl": { "type": "string", "nullable": true }, "slug": { "type": "string" }, "inventoryVersion": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "ProductCategory": { "type": "object", "properties": { "id": { "type": "string" }, "shopId": { "type": "string" }, "parentIds": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "status": { "type": "boolean" }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableField" } } } }, "AnalyticsBatch": { "type": "object", "properties": { "events": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/AnalyticsEvent" } } }, "required": [ "events" ] }, "AnalyticsEvent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100 }, "kind": { "type": "string", "enum": [ "search", "impression", "view", "scan", "cart_add", "cart_remove", "cart_bind", "customer_display" ] }, "interactionId": { "type": "string", "minLength": 1, "maxLength": 100 }, "occurredAt": { "type": "string", "format": "date-time" }, "productId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "branchId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "cartId": { "type": "string", "minLength": 1, "maxLength": 100 }, "query": { "type": "string", "maxLength": 120 }, "resultCount": { "type": "integer", "minimum": 0 }, "method": { "type": "string", "enum": [ "barcode", "rfid", "camera", "manual" ] }, "purpose": { "type": "string", "enum": [ "sales", "count", "assignment" ] } }, "required": [ "id", "kind", "interactionId", "occurredAt" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "string" }, "shopId": { "type": "string" }, "branchId": { "type": "array", "items": { "type": "string" } }, "customerCode": { "type": "string", "description": "Unique per shop (`shopId + customerCode` unique index)." }, "type": { "type": "string", "enum": [ "individual", "company", "supplier" ] }, "title": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "taxNo": { "type": "string", "pattern": "^[0-9]{10}$", "description": "Ten-digit VKN; customer type is inferred as company." }, "identityNo": { "type": "string", "pattern": "^[0-9]{11}$", "description": "Eleven-digit TCKN; customer type is inferred as individual." }, "address": { "type": "string" }, "notes": { "type": "string" }, "riskStatus": { "type": "string", "enum": [ "default", "safe", "risky", "banned" ] }, "riskReason": { "type": "string", "nullable": true }, "riskUpdatedAt": { "type": "string", "format": "date-time", "nullable": true }, "riskUpdatedBy": { "type": "string", "nullable": true }, "status": { "type": "boolean" }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableField" } } } }, "CustomerInput": { "type": "object", "required": [ "title" ], "properties": { "branchId": { "type": "array", "items": { "type": "string" } }, "customerCode": { "type": "string", "description": "Optional for customer creation; generated by the server when omitted." }, "type": { "type": "string", "enum": [ "individual", "company", "supplier" ] }, "title": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "taxNo": { "type": "string", "pattern": "^[0-9]{10}$", "description": "Ten-digit VKN; do not send together with identityNo." }, "identityNo": { "type": "string", "pattern": "^[0-9]{11}$", "description": "Eleven-digit TCKN; do not send together with taxNo." }, "address": { "type": "string" }, "notes": { "type": "string" }, "riskStatus": { "type": "string", "enum": [ "default", "safe", "risky", "banned" ] }, "riskReason": { "type": "string", "nullable": true }, "status": { "type": "boolean" }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableField" } } } }, "Order": { "type": "object", "properties": { "id": { "type": "string" }, "shopId": { "type": "string" }, "branchId": { "type": "string" }, "customerId": { "type": "string", "nullable": true }, "cartId": { "type": "string", "nullable": true }, "nativeOperationId": { "type": "string", "description": "Permanent native financial receipt. Legacy order status, payment, edit, shipment, cancellation and return mutations are rejected for this read model." }, "nativeRetailCartId": { "type": "string", "description": "Optional first-product retail cart, distinct from legacy/storefront carts" }, "occurredAt": { "type": "string", "format": "date-time", "description": "Original sale time; createdAt is server publication time." }, "nativeSettlement": { "type": "object", "description": "Versioned exact original sale items, physical quantities, prices, payments, discount, rounding and deferred agreement. Current claims remain in their agreed unit. Linked return selections update only the read model; original financial history stays immutable." }, "orderNo": { "type": "string" }, "channel": { "type": "string", "enum": [ "retail", "ecommerce" ] }, "source": { "type": "string", "enum": [ "storefront", "walk_in", "whatsapp", "phone", "instagram", "other" ], "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pendingApproval", "confirmed", "inProduction", "ready", "delivered", "cancelled", "returned" ] }, "paymentStatus": { "type": "string", "enum": [ "unpaid", "partial", "paid", "refunded" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SalesItem" } }, "totals": { "$ref": "#/components/schemas/SalesTotals" }, "notes": { "type": "string" }, "processNotes": { "type": "string" }, "approvedAt": { "type": "string", "format": "date-time", "nullable": true }, "productionStartedAt": { "type": "string", "format": "date-time", "nullable": true }, "readyAt": { "type": "string", "format": "date-time", "nullable": true }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true }, "returnedAt": { "type": "string", "format": "date-time", "nullable": true }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/VariableField" } } } }, "SalesItem": { "type": "object", "properties": { "productId": { "type": "string" }, "barcode": { "type": "string" }, "title": { "type": "string" }, "currencyCode": { "type": "string" }, "unitCode": { "type": "string" }, "piece": { "type": "number" }, "quantity": { "type": "integer", "minimum": 1 }, "buying": { "type": "number" }, "selling": { "type": "number" }, "discount": { "type": "number" }, "lineTotal": { "type": "number" } } }, "SalesTotals": { "type": "object", "properties": { "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "shippingCost": { "type": "number" }, "grandTotal": { "type": "number" }, "taxAmount": { "type": "number" }, "grandTotalWithTax": { "type": "number" }, "baseTotal": { "type": "number" }, "manualDiscountAmount": { "type": "number" } } }, "SiteTheme": { "type": "object", "required": [ "templateKey", "manifestVersion", "resources", "siteName", "faviconUrl", "colors", "fonts", "logo" ], "additionalProperties": false, "properties": { "templateKey": { "type": "string", "enum": [ "editorial", "catalog" ] }, "manifestVersion": { "type": "integer", "minimum": 1 }, "resources": { "type": "array", "items": { "type": "string", "pattern": "^(site|pages)\\." }, "uniqueItems": true }, "siteName": { "type": "string" }, "faviconUrl": { "type": "string" }, "colors": { "type": "object", "additionalProperties": { "type": "string" } }, "fonts": { "type": "object", "additionalProperties": { "type": "string" } }, "logo": { "type": "object", "additionalProperties": { "type": "string" } } } }, "SiteHomepageEditorial": { "allOf": [ { "$ref": "#/components/schemas/SiteHomepage" } ] }, "SiteHomepage": { "type": "object", "properties": { "hero": { "type": "object", "properties": { "slides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "href": { "type": "string" }, "contentMode": { "type": "string", "enum": [ "image", "overlay" ] }, "title": { "type": "string" }, "titleLines": { "type": "array", "items": { "type": "string" } }, "subtitle": { "type": "string", "maxLength": 500, "description": "Optional supporting copy below the hero heading; editable in both template manifests." }, "ctaLabel": { "type": "string", "maxLength": 60, "description": "Optional hero link label; requires href to render." }, "variant": { "type": "string", "enum": [ "product", "delivery" ] }, "promoText": { "type": "string" }, "footnotes": { "type": "string" }, "badge": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "string" } } } } } } }, "sideBanners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "href": { "type": "string" }, "contentMode": { "type": "string", "enum": [ "image", "overlay" ] }, "aspectRatio": { "type": "string" }, "objectPosition": { "type": "string" }, "titleLines": { "type": "array", "items": { "type": "string" } }, "ctaLabel": { "type": "string" }, "variant": { "type": "string", "enum": [ "investment", "assurance" ] }, "align": { "type": "string", "enum": [ "left", "right" ] } } } } } }, "trustFeatures": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "mediaType": { "type": "string", "enum": [ "video", "image" ] }, "mediaAlt": { "type": "string" }, "videoSrc": { "type": "string" }, "imageSrc": { "type": "string" }, "mediaWidth": { "type": "string" }, "aspectRatio": { "type": "string" } } } } } }, "featuredCategories": { "type": "object", "properties": { "title": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "linkLabel": { "type": "string" }, "href": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" } } } }, "footerText": { "type": "string" }, "footerLinkLabel": { "type": "string" }, "footerLinkHref": { "type": "string" }, "backgroundColor": { "type": "string" } } }, "brandManifesto": { "type": "object", "properties": { "title": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } } } }, "featuredProducts": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCard" } }, "footerLinkLabel": { "type": "string" }, "footerLinkHref": { "type": "string" }, "installmentBadgeImage": { "type": "string" } } }, "goldPriceChart": { "type": "object", "properties": { "title": { "type": "string" }, "descriptionLines": { "type": "array", "items": { "type": "string" } }, "productLabel": { "type": "string" }, "currentPrice": { "type": "number", "nullable": true }, "sourceReady": { "type": "boolean" }, "sourceStatus": { "type": "string", "enum": [ "current", "manual", "stale", "unavailable" ] }, "sourceUpdatedAt": { "type": "string", "format": "date-time", "nullable": true }, "unitCode": { "type": "string", "nullable": true }, "currency": { "type": "string" }, "backgroundImage": { "type": "string" }, "chart": { "type": "object", "properties": { "lineColor": { "type": "string" }, "height": { "type": "integer" }, "points": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "number" } } } } } } } }, "investmentProducts": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCard" } }, "footerLinkLabel": { "type": "string" }, "footerLinkHref": { "type": "string" }, "installmentBadgeImage": { "type": "string" } } }, "investmentPromo": { "type": "object", "properties": { "backgroundColor": { "type": "string" }, "iconImage": { "type": "string" }, "iconAlt": { "type": "string" }, "heroImage": { "type": "string" }, "heroAlt": { "type": "string" }, "title": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } } } }, "experience": { "type": "object", "properties": { "title": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string", "description": "Optional Lucide icon name." }, "image": { "type": "string" }, "imageAlt": { "type": "string" } } } }, "ctaLabel": { "type": "string" }, "ctaHref": { "type": "string" } } }, "storeShowcaseImage": { "type": "object", "properties": { "image": { "type": "string" }, "imageAlt": { "type": "string" } } }, "storeBannerTicker": { "type": "object", "properties": { "backgroundColor": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } } } }, "separatorImage": { "type": "string" }, "borderTopColor": { "type": "string" } } }, "testimonialQuote": { "type": "object", "properties": { "backgroundColor": { "type": "string" }, "ratingValue": { "type": "number" }, "ratingStarColor": { "type": "string" }, "ratingTextColor": { "type": "string" }, "quote": { "type": "string" }, "quoteColor": { "type": "string" } } }, "customerReviews": { "type": "object", "properties": { "backgroundColor": { "type": "string" }, "ratingValue": { "type": "number" }, "ratingStarColor": { "type": "string" }, "ratingTextColor": { "type": "string" }, "titleLines": { "type": "array", "items": { "type": "string" } }, "titleColor": { "type": "string" }, "description": { "type": "string" }, "descriptionColor": { "type": "string" } } }, "goldCoinBridge": { "type": "object", "properties": { "image": { "type": "string" }, "imageAlt": { "type": "string" } } }, "deliverySteps": { "type": "object", "properties": { "title": { "type": "string" }, "steps": { "type": "array", "minItems": 3, "maxItems": 5, "items": { "type": "object", "properties": { "id": { "type": "string" }, "stepNumber": { "type": "integer" }, "description": { "type": "string" }, "icon": { "type": "string", "description": "Optional Lucide icon name." }, "iconImage": { "type": "string" }, "iconAlt": { "type": "string" }, "overlayIconImage": { "type": "string" }, "overlayIconAlt": { "type": "string" } } } } } }, "whiteBannerTicker": { "type": "object", "properties": { "backgroundColor": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } } } }, "separatorImage": { "type": "string" }, "borderTopColor": { "type": "string" } } }, "goldBuyingWay": { "type": "object", "properties": { "backgroundColor": { "type": "string" }, "title": { "type": "string" }, "heroImage": { "type": "string" }, "heroAlt": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaHref": { "type": "string" }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "title": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } } } } } } }, "brandPrivileges": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" } } } } } }, "newsArticles": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "date": { "type": "string" }, "href": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "category": { "type": "string" } } } } } } } }, "ProductCard": { "type": "object", "required": [ "id", "slug", "categoryId", "categorySlug", "name", "href", "image", "imageAlt", "salePrice", "listPrice", "inStock", "inventoryMode", "maxOrderQuantity" ], "properties": { "id": { "type": "string", "minLength": 1 }, "companyDefinitionId": { "type": "string", "description": "Optional common company product identity; id is still the chosen real fulfillment product." }, "slug": { "type": "string", "minLength": 1 }, "categoryId": { "type": "string", "description": "Empty for an uncategorized company product." }, "categorySlug": { "type": "string", "description": "Empty for an uncategorized company product." }, "name": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "originalPrice": { "type": "number", "nullable": true }, "listPrice": { "type": "number", "nullable": true }, "salePrice": { "type": "number", "nullable": true }, "priceAvailable": { "type": "boolean" }, "priceStatus": { "type": "string", "enum": [ "current", "held", "unavailable" ] }, "priceAmount": { "type": "string", "nullable": true, "description": "Exact accepted selling amount; null when source/price is unavailable." }, "priceUpdatedAt": { "type": "string", "format": "date-time", "nullable": true }, "priceRevision": { "type": "integer", "nullable": true }, "currencyCode": { "type": "string" }, "weightLabel": { "type": "string" }, "discountPercent": { "type": "number" }, "hoverImage": { "type": "string" }, "listingFilterKeys": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "uniqueItems": true }, "inStock": { "type": "boolean" }, "inventoryMode": { "type": "string", "enum": [ "serialized", "quantity" ] }, "maxOrderQuantity": { "type": "integer", "minimum": 0, "maximum": 99 } } }, "SiteHomepageCatalog": { "allOf": [ { "$ref": "#/components/schemas/SiteHomepage" }, { "type": "object", "required": [ "brandManifesto", "featuredProducts", "investmentProducts", "goldPriceChart", "investmentPromo", "experience", "deliverySteps", "brandPrivileges", "newsArticles" ], "properties": { "brandManifesto": { "$ref": "#/components/schemas/SiteBrandManifestoCatalog" }, "featuredProducts": { "$ref": "#/components/schemas/FeaturedProductsSection" }, "investmentProducts": { "$ref": "#/components/schemas/FeaturedProductsSection" }, "goldPriceChart": { "$ref": "#/components/schemas/SiteGoldPriceChartCatalog" }, "investmentPromo": { "$ref": "#/components/schemas/SiteInvestmentPromoCatalog" }, "experience": { "$ref": "#/components/schemas/SiteExperienceCatalog" }, "deliverySteps": { "$ref": "#/components/schemas/SiteDeliveryStepsCatalog" }, "brandPrivileges": { "$ref": "#/components/schemas/SiteBrandPrivilegesCatalog" }, "newsArticles": { "$ref": "#/components/schemas/SiteNewsArticlesCatalog" } } } ], "description": "Catalog homepage response, including catalog-specific section extensions." }, "SiteBrandManifestoCatalog": { "type": "object", "required": [ "title", "paragraphs", "partnerLogos" ], "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } }, "partnerLogos": { "type": "array", "items": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "image": { "type": "string" } } } }, "ctaLabel": { "type": "string" }, "ctaHref": { "type": "string" } } }, "FeaturedProductsSection": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCard" } }, "footerLinkLabel": { "type": "string" }, "footerLinkHref": { "type": "string" }, "installmentBadgeImage": { "type": "string" } } }, "SiteGoldPriceChartCatalog": { "type": "object", "required": [ "title", "subtitle", "descriptionLines", "productLabel", "currentPrice", "currency", "backgroundImage", "salesTitle", "salesRows", "fxTitle", "fxNote", "fxRows", "chartTitle", "chartRanges", "chart", "chartWeekly" ], "properties": { "title": { "type": "string" }, "subtitle": { "type": "string" }, "descriptionLines": { "type": "array", "items": { "type": "string" } }, "productLabel": { "type": "string" }, "currentPrice": { "type": "number" }, "currency": { "type": "string" }, "backgroundImage": { "type": "string" }, "salesTitle": { "type": "string" }, "salesRows": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "label", "price" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "price": { "type": "number" } } } }, "fxTitle": { "type": "string" }, "fxNote": { "type": "string" }, "fxRows": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "pair", "buy", "sell" ], "properties": { "id": { "type": "string" }, "pair": { "type": "string" }, "buy": { "type": "number" }, "sell": { "type": "number" } } } }, "chartTitle": { "type": "string" }, "chartRanges": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" } } } }, "chart": { "$ref": "#/components/schemas/SitePriceChart" }, "chartWeekly": { "$ref": "#/components/schemas/SitePriceChartPoints" } } }, "SitePriceChart": { "type": "object", "required": [ "lineColor", "height", "points" ], "properties": { "lineColor": { "type": "string" }, "height": { "type": "integer" }, "points": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/SitePriceChartPoint" } } } }, "SitePriceChartPoint": { "type": "object", "required": [ "label", "value" ], "properties": { "label": { "type": "string" }, "value": { "type": "number" } } }, "SitePriceChartPoints": { "type": "object", "required": [ "points" ], "properties": { "points": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/SitePriceChartPoint" } } } }, "SiteInvestmentPromoCatalog": { "type": "object", "required": [ "title", "paragraphs", "appStoreLinks" ], "properties": { "backgroundColor": { "type": "string" }, "iconImage": { "type": "string" }, "iconAlt": { "type": "string" }, "heroImage": { "type": "string" }, "heroAlt": { "type": "string" }, "eyebrow": { "type": "string" }, "title": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } }, "appStoreLinks": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/SiteAppStoreLink" } } } }, "SiteAppStoreLink": { "type": "object", "required": [ "id", "label", "storeLabel", "href", "icon" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "storeLabel": { "type": "string" }, "href": { "type": "string" }, "icon": { "type": "string" } } }, "SiteExperienceCatalog": { "type": "object", "required": [ "title", "paragraphs", "collageImages" ], "properties": { "title": { "type": "string" }, "paragraphs": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "collageImages": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "image", "imageAlt" ], "properties": { "id": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" } } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" } } } }, "ctaLabel": { "type": "string" }, "ctaHref": { "type": "string" } } }, "SiteDeliveryStepsCatalog": { "type": "object", "required": [ "title", "description", "highlights", "heroImage", "heroAlt", "badgeTitle", "badgeSubtitle" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "highlights": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" } } } }, "heroImage": { "type": "string" }, "heroAlt": { "type": "string" }, "badgeTitle": { "type": "string" }, "badgeSubtitle": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "stepNumber": { "type": "number" }, "description": { "type": "string" }, "icon": { "type": "string" }, "iconImage": { "type": "string" }, "iconAlt": { "type": "string" }, "overlayIconImage": { "type": "string" }, "overlayIconAlt": { "type": "string" } } } } } }, "SiteBrandPrivilegesCatalog": { "type": "object", "required": [ "title", "footerLinkLabel", "footerLinkHref", "items" ], "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "footerLinkLabel": { "type": "string" }, "footerLinkHref": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "description", "image", "imageAlt" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "category": { "type": "string" }, "href": { "type": "string" } } } } } }, "SiteNewsArticlesCatalog": { "type": "object", "required": [ "title", "footerLinkLabel", "footerLinkHref", "items" ], "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "description": { "type": "string" }, "footerLinkLabel": { "type": "string" }, "footerLinkHref": { "type": "string" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/SiteNewsArticleItem" } } } }, "SiteNewsArticleItem": { "type": "object", "required": [ "id", "slug", "title", "category", "categorySlug", "href", "image", "imageAlt", "mediaType" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "date": { "type": "string" }, "category": { "type": "string" }, "categorySlug": { "type": "string" }, "href": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "mediaType": { "type": "string", "enum": [ "article", "video" ] }, "videoSrc": { "type": "string" }, "featured": { "type": "boolean" }, "readingTime": { "type": "string" } } }, "SiteArticleListItem": { "type": "object", "required": [ "id", "slug", "title", "category", "categorySlug", "href", "image", "imageAlt", "mediaType" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "date": { "type": "string" }, "category": { "type": "string" }, "categorySlug": { "type": "string" }, "href": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "mediaType": { "type": "string", "enum": [ "article", "video" ] }, "videoSrc": { "type": "string" }, "featured": { "type": "boolean" }, "readingTime": { "type": "string" } } }, "Pagination": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Flat visible total returned by product search; legacy toPaginate remains available." }, "size": { "type": "integer", "minimum": 1 }, "page": { "type": "integer", "minimum": 1 }, "totalPage": { "type": "integer", "minimum": 0 }, "pageSize": { "type": "integer" }, "currentPage": { "type": "integer" }, "totalPages": { "type": "integer" }, "toPaginate": { "type": "object", "properties": { "total": { "type": "integer" }, "size": { "type": "integer" }, "page": { "type": "integer" }, "totalPage": { "type": "integer" } } } } }, "SiteArticleDetail": { "type": "object", "required": [ "id", "slug", "title", "content", "category", "categorySlug", "href", "image", "imageAlt", "mediaType" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "content": { "type": "string" }, "date": { "type": "string" }, "category": { "type": "string" }, "categorySlug": { "type": "string" }, "href": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "mediaType": { "type": "string", "enum": [ "article", "video" ] }, "videoSrc": { "type": "string" }, "featured": { "type": "boolean" }, "readingTime": { "type": "string" } } }, "SiteHeader": { "type": "object", "properties": { "id": { "type": "string" }, "topBar": { "type": "object", "properties": { "announcement": { "type": "string" }, "goldRateLabel": { "type": "string" }, "goldRateValue": { "type": "number" }, "goldRateCurrency": { "type": "string" }, "goldRateSource": { "type": "object", "properties": { "currencyCode": { "type": "string", "example": "HAS" }, "priceSide": { "type": "string", "enum": [ "buying", "selling" ] } } }, "contactLabel": { "type": "string" }, "contactHref": { "type": "string" }, "contactPhone": { "type": "string" }, "contactEmail": { "type": "string", "format": "email" } } }, "navigation": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" }, "lines": { "type": "array", "items": { "type": "string" } }, "highlight": { "type": "boolean" } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "SiteFooter": { "type": "object", "properties": { "footer": { "type": "object", "properties": { "company": { "type": "object", "properties": { "legalName": { "type": "string" }, "lines": { "type": "array", "items": { "type": "string" } } } }, "support": { "type": "object", "properties": { "phone": { "type": "string" }, "phoneHref": { "type": "string" }, "email": { "type": "string" }, "emailHref": { "type": "string" }, "hours": { "type": "array", "items": { "type": "string" } } } }, "contracts": { "$ref": "#/components/schemas/FooterContracts" }, "socialLinks": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" }, "image": { "type": "string" } } } }, "newsletter": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "emailPlaceholder": { "type": "string" }, "submitLabel": { "type": "string" } } }, "paymentBadges": { "type": "array", "items": { "type": "object" } } } }, "legalStrip": { "type": "object", "properties": { "copyright": { "type": "string" }, "logoImage": { "type": "string" }, "logoAlt": { "type": "string" } } } } }, "FooterContracts": { "type": "object", "properties": { "title": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "string", "enum": [ "richtext", "pdf" ] }, "content": { "type": "string" }, "document": { "type": "string" }, "placements": { "type": "array", "items": { "type": "object", "required": [ "placement", "required", "sortOrder" ], "properties": { "placement": { "type": "string", "enum": [ "footer", "register", "checkout" ] }, "required": { "type": "boolean" }, "sortOrder": { "type": "integer" } } } } } } } } }, "AboutUsEditorial": { "allOf": [ { "$ref": "#/components/schemas/SiteAboutUs" } ] }, "SiteAboutUs": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "eyebrow": { "type": "string" }, "brandTitle": { "type": "string" }, "introParagraphs": { "type": "array", "items": { "type": "string" } }, "storyItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" } } } }, "trustSection": { "type": "object", "properties": { "title": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } }, "image": { "type": "object", "properties": { "image": { "type": "string" }, "imageAlt": { "type": "string" } } } } }, "milestoneSection": { "type": "object", "properties": { "title": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } }, "footnote": { "type": "string" } } }, "confidenceSection": { "type": "object", "properties": { "title": { "type": "string" }, "paragraph": { "type": "string" } } }, "contactSection": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "image": { "type": "object", "properties": { "image": { "type": "string" }, "imageAlt": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "href": { "type": "string" }, "icon": { "type": "string" } } } } } }, "partners": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "image": { "type": "string" }, "href": { "type": "string" } } } } } }, "AboutUsCatalog": { "type": "object", "properties": { "title": { "type": "string" }, "hero": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" } } }, "vision": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" } } }, "video": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "videoSrc": { "type": "string" }, "posterImage": { "type": "string" }, "posterAlt": { "type": "string" } } }, "values": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "items": { "type": "array", "minItems": 2, "maxItems": 4, "items": { "type": "object", "properties": { "id": { "type": "string" }, "icon": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } } } } } }, "accreditations": { "type": "object", "properties": { "title": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "mark": { "type": "string" }, "image": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } } } }, "primaryCtaLabel": { "type": "string" }, "primaryCtaHref": { "type": "string" }, "secondaryCtaLabel": { "type": "string" }, "secondaryCtaHref": { "type": "string" } } }, "heritage": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "stats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "string" }, "label": { "type": "string" } } } } } }, "message": { "type": "object", "properties": { "brandLabel": { "type": "string" }, "roleLabel": { "type": "string" }, "name": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } }, "closing": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" } } } } }, "CampaignPage": { "allOf": [ { "$ref": "#/components/schemas/SiteCampaigns" } ] }, "SiteCampaigns": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "variant": { "type": "string", "enum": [ "brand", "cream", "light" ] }, "layout": { "type": "string", "enum": [ "split", "promo" ] }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "eyebrow": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "highlight": { "type": "string" }, "highlightSuffix": { "type": "string" }, "footnote": { "type": "string" }, "badges": { "type": "array", "items": { "type": "string" } }, "ctaLabel": { "type": "string" }, "ctaHref": { "type": "string" } } } } } }, "SearchPage": { "allOf": [ { "$ref": "#/components/schemas/SiteSearchPage" } ] }, "SiteSearchPage": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "breadcrumbLabel": { "type": "string" }, "resultsBreadcrumbLabel": { "type": "string" }, "placeholder": { "type": "string" }, "emptyQueryTitle": { "type": "string" }, "emptyQueryDescription": { "type": "string" }, "noResultsTitle": { "type": "string" }, "noResultsDescription": { "type": "string" }, "popularSearches": { "type": "array", "items": { "type": "string" } }, "minQueryLength": { "type": "integer" } } }, "FaqPage": { "allOf": [ { "$ref": "#/components/schemas/SiteFaqPage" } ] }, "SiteFaqPage": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" } } } } } } } } }, "SearchResultItem": { "allOf": [ { "$ref": "#/components/schemas/ProductCard" } ] }, "SiteCategory": { "type": "object", "required": [ "id", "slug", "title", "parentId", "status" ], "properties": { "id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "parentId": { "type": "string", "nullable": true }, "status": { "type": "boolean" } } }, "ProductDetail": { "allOf": [ { "$ref": "#/components/schemas/ProductCard" }, { "type": "object", "properties": { "returnPolicy": { "type": "object", "additionalProperties": false, "required": [ "version", "mode", "description", "defectRightsPreserved" ], "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "mode": { "type": "string", "enum": [ "standard", "market_fluctuation", "custom_made", "sealed_hygiene" ] }, "description": { "type": "string", "maxLength": 1000 }, "defectRightsPreserved": { "type": "boolean", "enum": [ true ] } } }, "categoryLabel": { "type": "string" }, "title": { "type": "string" }, "shortDescription": { "type": "string" }, "description": { "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "src": { "type": "string" }, "alt": { "type": "string" } } } }, "badges": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" } } } }, "attributeGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } } } } } } }, "delivery": { "type": "object", "properties": { "label": { "type": "string" }, "isFree": { "type": "boolean" }, "description": { "type": "string" } } }, "specs": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } } } } ] }, "BlogPage": { "type": "object", "required": [ "title", "description", "newsletter", "posts" ], "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "featuredTitle": { "type": "string" }, "latestTitle": { "type": "string" }, "categoriesTitle": { "type": "string" }, "newsletter": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "placeholder": { "type": "string" }, "submitLabel": { "type": "string" }, "disclaimer": { "type": "string" } } }, "posts": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "title", "category", "categorySlug", "href", "image", "imageAlt", "mediaType" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "category": { "type": "string" }, "categorySlug": { "type": "string" }, "readingTime": { "type": "string" }, "href": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "featured": { "type": "boolean" }, "mediaType": { "type": "string", "enum": [ "article", "video" ] }, "videoSrc": { "type": "string" } } } } } }, "ContactPageCatalog": { "type": "object", "properties": { "title": { "type": "string" }, "card": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "phone": { "type": "string" }, "phoneHref": { "type": "string" }, "email": { "type": "string" }, "emailHref": { "type": "string" }, "address": { "type": "string" } } }, "form": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "submitLabel": { "type": "string" }, "privacyLinkLabel": { "type": "string" }, "privacyContractId": { "type": "string" }, "successTitle": { "type": "string" }, "successDescription": { "type": "string" } } } } }, "CategoriesPageCatalog": { "type": "object", "properties": { "title": { "type": "string" }, "hero": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "videoSrc": { "type": "string" }, "posterImage": { "type": "string" }, "posterAlt": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "linkLabel": { "type": "string" }, "href": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" } } } } } }, "SiteProductsPage": { "type": "object", "required": [ "title", "category", "hero", "filterChips" ], "properties": { "title": { "type": "string", "minLength": 1 }, "category": { "type": "object", "required": [ "id", "slug", "title" ], "properties": { "id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 } }, "nullable": true }, "hero": { "$ref": "#/components/schemas/SiteListingHero" }, "filterChips": { "type": "array", "items": { "$ref": "#/components/schemas/SiteListingFilterChip" } } } }, "SiteListingHero": { "type": "object", "required": [ "eyebrow", "title", "subtitle", "videoSrc", "posterImage", "posterAlt" ], "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "videoSrc": { "type": "string" }, "posterImage": { "type": "string" }, "posterAlt": { "type": "string" } } }, "SiteListingFilterChip": { "type": "object", "required": [ "id", "label", "key" ], "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "key": { "type": "string", "nullable": true, "maxLength": 50 } } }, "CustomerAuthAcceptedResponse": { "type": "object", "required": [ "status", "messageCode" ], "properties": { "status": { "type": "boolean" }, "messageCode": { "type": "string", "example": "customerAuth.requestAccepted" }, "message": { "type": "string" } } }, "CustomerAuthTokenResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/CustomerAuthTokenPair" } } }, "CustomerAuthTokenPair": { "type": "object", "required": [ "account", "accessToken", "accessTokenExpiresIn", "refreshTokenExpiresAt" ], "properties": { "account": { "$ref": "#/components/schemas/CustomerAuthAccount" }, "accessToken": { "type": "string" }, "accessTokenExpiresIn": { "type": "integer", "example": 900 }, "refreshToken": { "type": "string", "description": "Present only when CUSTOMER_REFRESH_TOKEN_BODY_ENABLED=true; prefer the HttpOnly cookie." }, "refreshTokenExpiresAt": { "type": "string", "format": "date-time" } } }, "CustomerAuthAccount": { "type": "object", "additionalProperties": false, "required": [ "id", "displayName", "email", "status", "claimStatus", "emailVerified" ], "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "preferredLocale": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ], "default": "tr" }, "email": { "type": "string", "description": "Masked email address." }, "phone": { "type": "string", "nullable": true, "description": "Masked phone number." }, "status": { "type": "string", "enum": [ "active", "locked", "disabled", "deleted" ] }, "claimStatus": { "type": "string", "enum": [ "unmatched", "linked", "manual_review", "company_review", "rejected" ] }, "emailVerified": { "type": "boolean" }, "phoneVerified": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastLoginAt": { "type": "string", "format": "date-time", "nullable": true }, "lastPasswordChangedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "CustomerMeResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/CustomerAuthAccount" } } }, "CustomerProfileUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "updatedAt" ], "anyOf": [ { "required": [ "displayName" ] }, { "required": [ "preferredLocale" ] } ], "properties": { "displayName": { "type": "string", "minLength": 2, "maxLength": 160 }, "preferredLocale": { "type": "string", "enum": [ "tr", "en", "de", "fr", "ar", "zh-Hans" ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "CAS value from the latest profile response." } } }, "CustomerAddressListResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAddress" } } } }, "CustomerAddress": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "usageTypes", "fullName", "phone", "countryCode", "city", "district", "addressLine", "isDefaultShipping", "isDefaultBilling", "version" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "usageTypes": { "type": "array", "items": { "type": "string", "enum": [ "shipping", "billing" ] } }, "fullName": { "type": "string" }, "phone": { "type": "string", "description": "Decrypted only for the authenticated owning account." }, "countryCode": { "type": "string" }, "city": { "type": "string" }, "district": { "type": "string" }, "neighborhood": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "addressLine": { "type": "string" }, "companyName": { "type": "string", "nullable": true }, "taxOffice": { "type": "string", "nullable": true }, "taxNumber": { "type": "string", "nullable": true, "description": "Masked tax number." }, "hasTaxNumber": { "type": "boolean" }, "isDefaultShipping": { "type": "boolean" }, "isDefaultBilling": { "type": "boolean" }, "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CustomerAddressInput": { "type": "object", "additionalProperties": false, "required": [ "label", "usageTypes", "fullName", "phone", "city", "district", "addressLine" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 50 }, "usageTypes": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "shipping", "billing" ] } }, "fullName": { "type": "string", "minLength": 2, "maxLength": 120 }, "phone": { "type": "string" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "default": "TR" }, "city": { "type": "string", "maxLength": 100 }, "district": { "type": "string", "maxLength": 100 }, "neighborhood": { "type": "string", "nullable": true, "maxLength": 120 }, "postalCode": { "type": "string", "nullable": true, "maxLength": 20 }, "addressLine": { "type": "string", "minLength": 5, "maxLength": 500 }, "companyName": { "type": "string", "nullable": true, "maxLength": 160, "description": "Optional for billing addresses." }, "taxOffice": { "type": "string", "nullable": true, "maxLength": 120, "description": "Allowed only when usageTypes includes billing." }, "taxNumber": { "type": "string", "nullable": true, "maxLength": 32, "description": "Allowed only when usageTypes includes billing; returned masked after storage." } } }, "CustomerAddressResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "messageCode": { "type": "string" }, "result": { "$ref": "#/components/schemas/CustomerAddress" } } }, "CustomerAddressUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "version" ], "properties": { "version": { "type": "integer", "minimum": 1, "description": "CAS value from the latest address response." }, "label": { "type": "string", "minLength": 1, "maxLength": 50 }, "usageTypes": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "shipping", "billing" ] } }, "fullName": { "type": "string", "minLength": 2, "maxLength": 120 }, "phone": { "type": "string" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "city": { "type": "string", "maxLength": 100 }, "district": { "type": "string", "maxLength": 100 }, "neighborhood": { "type": "string", "nullable": true, "maxLength": 120 }, "postalCode": { "type": "string", "nullable": true, "maxLength": 20 }, "addressLine": { "type": "string", "minLength": 5, "maxLength": 500 }, "companyName": { "type": "string", "nullable": true, "maxLength": 160, "description": "Optional for billing addresses." }, "taxOffice": { "type": "string", "nullable": true, "maxLength": 120, "description": "Allowed only when the resulting usageTypes includes billing." }, "taxNumber": { "type": "string", "nullable": true, "maxLength": 32, "description": "Allowed only when the resulting usageTypes includes billing; returned masked after storage." } } }, "CustomerSessionListResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerSession" } } } }, "CustomerSession": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "current", "lastUsedAt", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string" }, "deviceLabel": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "rotated" ] }, "current": { "type": "boolean" }, "lastUsedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "CustomerFavoriteListResponse": { "type": "object", "required": [ "status", "result", "paginate" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerFavorite" } }, "paginate": { "$ref": "#/components/schemas/Paginate" } } }, "CustomerFavorite": { "type": "object", "additionalProperties": false, "required": [ "id", "productId", "createdAt", "available", "product" ], "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "available": { "type": "boolean", "description": "False when the saved product is no longer storefront-visible." }, "product": { "allOf": [ { "$ref": "#/components/schemas/ProductCard" } ], "nullable": true } } }, "Paginate": { "type": "object", "properties": { "total": { "type": "integer" }, "size": { "type": "integer" }, "page": { "type": "integer" }, "totalPage": { "type": "integer", "description": "Legacy alias for totalPages" }, "pageSize": { "type": "integer" }, "currentPage": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "CustomerFavoriteMutationResponse": { "type": "object", "required": [ "status", "messageCode" ], "properties": { "status": { "type": "boolean" }, "messageCode": { "type": "string", "enum": [ "customerFavorite.added", "customerFavorite.alreadyAdded", "customerFavorite.removed" ] }, "created": { "type": "boolean", "description": "Present for add requests; false on an idempotent replay." }, "removed": { "type": "boolean", "description": "Present for delete requests; false when it was already absent." }, "result": { "$ref": "#/components/schemas/CustomerFavorite" } } }, "CartCreateResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean", "enum": [ true ] }, "code": { "type": "string" }, "messageCode": { "type": "string" }, "message": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Cart ID" }, "channel": { "type": "string", "enum": [ "retail", "ecommerce" ] }, "ownerType": { "type": "string", "enum": [ "staff", "customer", "guest" ] }, "status": { "type": "string", "enum": [ "open", "checking_out", "converted", "cancelled", "merged", "expired" ] }, "currencyCode": { "type": "string", "nullable": true, "description": "Cart currency code" }, "branchId": { "type": "string", "description": "Legacy/primary cart branch ID; individual items may belong to other branches in the same shop" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontCartItem" } }, "totals": { "$ref": "#/components/schemas/StorefrontCartTotals" }, "itemCount": { "type": "integer", "description": "Number of individually tracked product lines in cart" }, "version": { "type": "integer", "description": "Cart version for concurrency" }, "lastValidatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Guest cart expiry" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "guestCartToken": { "type": "string", "description": "Opaque capability returned for guest bootstrap/retrieval; absent for authenticated customers." } }, "required": [ "id", "channel", "ownerType", "status", "branchId", "items", "totals", "version" ] } } }, "StorefrontCartItem": { "type": "object", "additionalProperties": false, "properties": { "productId": { "type": "string", "description": "Product ID" }, "companyDefinitionId": { "type": "string", "description": "Optional common company product identity. productId remains the real fulfillment projection; adding a sibling increases the existing line within that original location's stock limit." }, "branchId": { "type": "string", "nullable": true, "description": "Stock-owning branch used for reservation and fulfillment grouping" }, "barcode": { "type": "string", "description": "Product barcode" }, "title": { "type": "string", "description": "Product title" }, "slug": { "type": "string", "description": "Product storefront slug" }, "href": { "type": "string", "description": "Canonical product detail path" }, "image": { "type": "string", "description": "Sanitized public product image URL" }, "imageAlt": { "type": "string", "description": "Product image alternative text" }, "weightLabel": { "type": "string", "description": "Storefront weight/unit label" }, "originalPrice": { "type": "number", "description": "Compare-at/list price at time of add" }, "maxOrderQuantity": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Maximum selectable quantity captured from public inventory availability" }, "currencyCode": { "type": "string", "description": "Item currency code" }, "unitCode": { "type": "string", "description": "Item unit code" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Quantity product amount; serialized products remain limited to 1." }, "selling": { "type": "number", "description": "Selling price at time of add" }, "discount": { "type": "number", "description": "Item discount" }, "taxRate": { "type": "number", "description": "Tax rate" }, "taxAmount": { "type": "number", "description": "Tax amount" }, "lineTotal": { "type": "number", "description": "Line total" } } }, "StorefrontCartTotals": { "type": "object", "additionalProperties": false, "properties": { "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "grandTotal": { "type": "number" }, "taxAmount": { "type": "number" }, "grandTotalWithTax": { "type": "number" } } }, "StorefrontCartSafe": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Cart ID" }, "channel": { "type": "string", "enum": [ "retail", "ecommerce" ] }, "ownerType": { "type": "string", "enum": [ "staff", "customer", "guest" ] }, "status": { "type": "string", "enum": [ "open", "checking_out", "converted", "cancelled", "merged", "expired" ] }, "currencyCode": { "type": "string", "nullable": true, "description": "Cart currency code" }, "branchId": { "type": "string", "description": "Legacy/primary cart branch ID; individual items may belong to other branches in the same shop" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontCartItem" } }, "totals": { "$ref": "#/components/schemas/StorefrontCartTotals" }, "itemCount": { "type": "integer", "description": "Number of individually tracked product lines in cart" }, "version": { "type": "integer", "description": "Cart version for concurrency" }, "lastValidatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "expiresAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Guest cart expiry" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CartAddItemRequest": { "type": "object", "additionalProperties": false, "required": [ "productId" ], "properties": { "productId": { "type": "string", "description": "Product ID to add" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 99, "default": 1 }, "guestCartToken": { "type": "string", "description": "Optional cross-origin guest cart token fallback." } } }, "CartUpdateItemRequest": { "type": "object", "additionalProperties": false, "required": [ "quantity" ], "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 99 }, "guestCartToken": { "type": "string", "description": "Optional cross-origin guest cart token fallback." } } }, "CartValidationResult": { "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/StorefrontCartSafe" }, "results": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "status": { "type": "string", "enum": [ "available", "unavailable", "price_changed", "branch_conflict", "currency_conflict", "reserved_elsewhere", "inactive" ] }, "currentPrice": { "type": "number" }, "snapshotPrice": { "type": "number" }, "priceChanged": { "type": "boolean" }, "reason": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "object" } } } }, "CartMergeRequest": { "type": "object", "additionalProperties": false, "required": [ "mergeOperationId" ], "properties": { "mergeOperationId": { "type": "string", "description": "Unique merge operation ID for idempotency" } } }, "CartMergeResult": { "type": "object", "properties": { "cart": { "$ref": "#/components/schemas/StorefrontCartSafe" }, "transfer": { "type": "boolean", "description": "True if guest cart ownership was transferred (no merge needed)" }, "replay": { "type": "boolean", "description": "True if this is an idempotent replay" }, "acceptedCount": { "type": "integer" }, "rejectedCount": { "type": "integer" }, "itemResults": { "type": "array", "items": { "$ref": "#/components/schemas/CartMergeItemResult" } } } }, "CartMergeItemResult": { "type": "object", "properties": { "productId": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "already_present", "price_changed", "unavailable", "branch_conflict", "currency_conflict", "inactive" ] }, "currentPrice": { "type": "number" }, "snapshotPrice": { "type": "number" } } }, "StorefrontDeliveryMethod": { "type": "object", "additionalProperties": false, "required": [ "id", "code", "title", "label", "type", "price", "branches" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "shipping", "pickup" ] }, "price": { "type": "number" }, "currencyCode": { "type": "string", "nullable": true }, "freeShippingThreshold": { "type": "number", "nullable": true }, "pricingVersion": { "type": "integer" }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontDeliveryBranch" } } } }, "StorefrontDeliveryBranch": { "type": "object", "additionalProperties": false, "required": [ "id", "code", "title" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" } } }, "CheckoutPrepareRequest": { "type": "object", "additionalProperties": false, "required": [ "cartId", "deliveryMethodId", "deliveryType" ], "properties": { "cartId": { "type": "string", "description": "Current e-commerce cart ID" }, "shippingAddressId": { "type": "string", "nullable": true, "description": "Shipping address ID (required for shipping delivery type)" }, "billingAddressId": { "type": "string", "nullable": true, "description": "Billing address ID (optional)" }, "deliveryMethodId": { "type": "string", "description": "Delivery method ID" }, "deliveryType": { "type": "string", "enum": [ "shipping", "pickup" ], "description": "Delivery type" }, "pickupBranchId": { "type": "string", "nullable": true, "description": "Required for pickup; must be an active branch in the same shop" }, "sameAsShipping": { "type": "boolean", "default": false, "description": "Build the billing snapshot from the owned shipping address" } } }, "CheckoutPrepareResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/CheckoutPrepareSession" }, "code": { "type": "string", "example": "checkout.prepared" }, "messageCode": { "type": "string", "example": "checkout.prepared" } } }, "CheckoutPrepareSession": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutPriceLine" }, "description": "Frozen public quote prices; excludes internal cost and pricing definitions." }, "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutContract" }, "description": "Both published documents that must be read and accepted with submit." }, "id": { "type": "string", "description": "Checkout session ID" }, "quoteHash": { "type": "string", "description": "Quote hash for submit verification" }, "deliveryMethodId": { "type": "string", "nullable": true, "description": "Selected delivery method ID" }, "deliveryType": { "type": "string", "enum": [ "pickup", "shipping" ], "nullable": true }, "pickupBranchId": { "type": "string", "nullable": true, "description": "Selected pickup branch ID" }, "shippingAddressId": { "type": "string", "nullable": true, "description": "Selected shipping address ID" }, "billingAddressId": { "type": "string", "nullable": true, "description": "Selected billing address ID" }, "sameAsShipping": { "type": "boolean", "description": "Whether billing uses the shipping address" }, "totals": { "type": "object", "properties": { "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "shippingCost": { "type": "number" }, "grandTotal": { "type": "number" }, "taxAmount": { "type": "number" }, "grandTotalWithTax": { "type": "number" }, "currencyCode": { "type": "string" } } }, "reservationIds": { "type": "array", "items": { "type": "string" }, "description": "Acquired reservation IDs" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Session expiry" }, "itemResults": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "reservationId": { "type": "string" }, "status": { "type": "string", "enum": [ "available", "reserved_by_same_cart" ] }, "quantity": { "type": "integer" } } } }, "replay": { "type": "boolean", "description": "True when an identical prepare request replays the active immutable session" } } }, "CheckoutPriceLine": { "type": "object", "additionalProperties": false, "required": [ "productId", "quantity", "price", "discount", "lineTotal", "currencyCode" ], "properties": { "returnPolicy": { "type": "object", "additionalProperties": false, "required": [ "version", "mode", "description", "defectRightsPreserved" ], "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "mode": { "type": "string", "enum": [ "standard", "market_fluctuation", "custom_made", "sealed_hygiene" ] }, "description": { "type": "string", "maxLength": 1000 }, "defectRightsPreserved": { "type": "boolean", "enum": [ true ] } } }, "title": { "type": "string" }, "productId": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "number" }, "discount": { "type": "number" }, "lineTotal": { "type": "number" }, "currencyCode": { "type": "string" } } }, "CheckoutContract": { "type": "object", "required": [ "id", "title", "source", "content", "documentUrl", "version", "hash" ], "properties": { "id": { "type": "string", "enum": [ "distance-sales", "pre-info" ] }, "title": { "type": "string" }, "source": { "type": "string", "enum": [ "richtext", "pdf" ] }, "content": { "type": "string", "description": "Sanitized HTML from the published shop footer, frozen in this quote." }, "documentUrl": { "type": "string", "description": "Published PDF URL when source is PDF, frozen in this quote." }, "version": { "type": "string" }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "CheckoutRenewRequest": { "type": "object", "additionalProperties": false, "required": [ "sessionId", "quoteHash" ], "properties": { "sessionId": { "type": "string" }, "quoteHash": { "type": "string" } } }, "CheckoutSubmitRequest": { "type": "object", "additionalProperties": false, "required": [ "sessionId", "quoteHash", "consents" ], "properties": { "sessionId": { "type": "string" }, "quoteHash": { "type": "string" }, "consents": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/components/schemas/CheckoutConsent" } } } }, "CheckoutConsent": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "hash", "accepted" ], "properties": { "id": { "type": "string", "enum": [ "distance-sales", "pre-info" ] }, "version": { "type": "string" }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "accepted": { "type": "boolean", "enum": [ true ] } } }, "CheckoutSubmitResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/CheckoutSubmitResult" }, "code": { "type": "string", "example": "checkout.orderCreated" }, "messageCode": { "type": "string", "example": "checkout.orderCreated" } } }, "CheckoutSubmitResult": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/CustomerOrderDetail" }, "payment": { "$ref": "#/components/schemas/PaymentAttemptSafe" }, "replay": { "type": "boolean", "description": "True if this is an idempotent replay" } } }, "CustomerOrderDetail": { "type": "object", "additionalProperties": false, "properties": { "paymentProvider": { "type": "string", "nullable": true }, "pickupBranch": { "type": "object", "nullable": true, "properties": { "title": { "type": "string" }, "code": { "type": "string" } } }, "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutContract" } }, "contractAcceptedAt": { "type": "string", "format": "date-time", "nullable": true }, "id": { "type": "string", "description": "Order ID" }, "publicOrderNo": { "type": "string", "description": "Public-facing order number" }, "status": { "type": "string", "enum": [ "pendingApproval", "confirmed", "cancellationPendingRefund", "cancelled", "expired", "completed", "returned" ], "description": "Order status" }, "onlinePaymentMode": { "type": "string", "nullable": true, "enum": [ "mock", null ], "description": "Display-only mock attempt evidence; no real money collected." }, "paymentStatus": { "type": "string", "enum": [ "unpaid", "partial", "authorized", "manually_confirmed", "paid", "refund_pending", "manual_refund_required", "refunded" ], "description": "Payment status" }, "returnsState": { "type": "object", "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "status": { "type": "string", "enum": [ "none", "requested", "partial", "returned" ] }, "returnedQuantity": { "type": "integer", "minimum": 0 }, "refundedAmount": { "type": "string" }, "caseCount": { "type": "integer", "minimum": 0 } } }, "financialPostingStatus": { "type": "string", "enum": [ "not_posted", "posted", "reversed", "not_required" ], "nullable": true, "description": "Financial posting state" }, "fulfillmentType": { "type": "string", "enum": [ "pickup", "shipping" ], "description": "Pickup or physical shipping" }, "fulfillmentStatus": { "type": "string", "enum": [ "not_started", "waiting_payment", "preparing", "ready_for_pickup", "picked_up", "ready_to_ship", "shipped", "in_transit", "delivered", "returned", "cancelled" ], "description": "Fulfillment state" }, "paymentMethod": { "type": "string", "nullable": true, "description": "Payment method identifier" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOrderItem" }, "description": "Order items" }, "totals": { "$ref": "#/components/schemas/CustomerOrderTotals" }, "shippingAddress": { "$ref": "#/components/schemas/CustomerShippingAddress" }, "billingSummary": { "type": "object", "nullable": true, "properties": { "hasBillingAddress": { "type": "boolean" } } }, "approvalExpiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Approval hold expiry" }, "paymentDueAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Confirmed unpaid payment deadline" }, "autoCancelAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Automatic cancellation deadline for unsettled orders" }, "submittedAt": { "type": "string", "format": "date-time", "description": "When the order was submitted" }, "cancellationRequestedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When cancellation was requested" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the order was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the order was last updated" } } }, "CustomerOrderItem": { "type": "object", "additionalProperties": false, "properties": { "returnPolicy": { "type": "object", "additionalProperties": false, "required": [ "version", "mode", "description", "defectRightsPreserved" ], "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "mode": { "type": "string", "enum": [ "standard", "market_fluctuation", "custom_made", "sealed_hygiene" ] }, "description": { "type": "string", "maxLength": 1000 }, "defectRightsPreserved": { "type": "boolean", "enum": [ true ] } } }, "productHref": { "type": "string", "nullable": true, "description": "Current public product path when the product and its category remain published." }, "productId": { "type": "string", "description": "Product ID" }, "barcode": { "type": "string", "description": "Product barcode" }, "title": { "type": "string", "description": "Product title" }, "currencyCode": { "type": "string", "description": "Item currency code" }, "unitCode": { "type": "string", "description": "Item unit code" }, "quantity": { "type": "integer", "minimum": 1, "description": "Item quantity" }, "selling": { "type": "number", "description": "Selling price at time of order" }, "unitPrice": { "type": "number", "description": "Unit price" }, "discount": { "type": "number", "description": "Item discount" }, "taxRate": { "type": "number", "description": "Tax rate" }, "taxAmount": { "type": "number", "description": "Tax amount" }, "lineTotal": { "type": "number", "description": "Line total" } } }, "CustomerOrderTotals": { "type": "object", "additionalProperties": false, "properties": { "subtotal": { "type": "number" }, "discountTotal": { "type": "number" }, "shippingCost": { "type": "number" }, "grandTotal": { "type": "number" }, "taxAmount": { "type": "number" }, "grandTotalWithTax": { "type": "number" }, "currencyCode": { "type": "string" } } }, "CustomerShippingAddress": { "type": "object", "nullable": true, "properties": { "city": { "type": "string" }, "district": { "type": "string" }, "postalCode": { "type": "string" } } }, "PaymentAttemptSafe": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Payment attempt ID" }, "provider": { "type": "string", "description": "Payment provider name" }, "status": { "type": "string", "enum": [ "pending", "authorized", "manually_confirmed", "paid", "failed", "cancelled", "expired", "refund_pending", "manual_refund_required", "refunded" ], "description": "Payment attempt status" }, "amount": { "type": "number", "description": "Payment amount" }, "currencyCode": { "type": "string", "description": "Payment currency code" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the payment attempt was created" } } }, "CheckoutStatusResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "object", "properties": { "session": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutPrepareSession" } ], "properties": { "status": { "type": "string", "enum": [ "active", "submitting", "consumed", "expired", "cancelled" ] } } }, "order": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "publicOrderNo": { "type": "string" }, "status": { "type": "string" }, "paymentStatus": { "type": "string" } } }, "payment": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PaymentAttemptSafe" } ] } } } } }, "StorefrontPaymentAttemptCreate": { "type": "object", "additionalProperties": false, "required": [ "orderId", "paymentMethod", "returnUrl" ], "properties": { "orderId": { "type": "string" }, "paymentMethod": { "type": "string", "enum": [ "credit-card", "bank-transfer" ] }, "returnUrl": { "type": "string", "format": "uri", "description": "URL on a verified domain belonging to the current shop." }, "testOutcome": { "type": "string", "enum": [ "paid", "failed", "pending" ], "description": "Development/test-only mock outcome." } } }, "StorefrontPaymentAttempt": { "type": "object", "additionalProperties": false, "required": [ "id", "orderId", "provider", "paymentMethod", "status", "amount", "currency" ], "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "provider": { "type": "string" }, "phase": { "type": "string", "enum": [ "checkout", "payment" ] }, "paymentMethod": { "type": "string", "enum": [ "credit-card", "bank-transfer", "manual" ] }, "status": { "type": "string", "enum": [ "pending", "paid", "failed", "cancelled", "expired" ] }, "amount": { "type": "number", "description": "Server-owned order amount." }, "currency": { "type": "string", "description": "Server-owned order currency." }, "returnUrl": { "type": "string", "nullable": true }, "redirectUrl": { "type": "string", "nullable": true }, "supersedesAttemptId": { "type": "string", "nullable": true }, "failureCode": { "type": "string", "nullable": true }, "failureMessage": { "type": "string", "nullable": true }, "replay": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CustomerOrderListResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOrderListItem" } }, "paginate": { "type": "object", "properties": { "total": { "type": "integer" }, "pageSize": { "type": "integer" }, "currentPage": { "type": "integer" }, "totalPages": { "type": "integer" } } } } }, "CustomerOrderListItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Order ID" }, "publicOrderNo": { "type": "string", "description": "Public-facing order number" }, "status": { "type": "string", "enum": [ "pendingApproval", "confirmed", "cancellationPendingRefund", "cancelled", "expired", "completed", "returned" ], "description": "Order status" }, "onlinePaymentMode": { "type": "string", "nullable": true, "enum": [ "mock", null ], "description": "Display-only mock attempt evidence; no real money collected." }, "paymentStatus": { "type": "string", "enum": [ "unpaid", "partial", "authorized", "manually_confirmed", "paid", "refund_pending", "manual_refund_required", "refunded" ], "description": "Payment status" }, "returnsState": { "type": "object", "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "status": { "type": "string", "enum": [ "none", "requested", "partial", "returned" ] }, "returnedQuantity": { "type": "integer", "minimum": 0 }, "refundedAmount": { "type": "string" }, "caseCount": { "type": "integer", "minimum": 0 } } }, "financialPostingStatus": { "type": "string", "enum": [ "not_posted", "posted", "reversed", "not_required" ], "nullable": true, "description": "Financial posting state" }, "fulfillmentType": { "type": "string", "enum": [ "pickup", "shipping" ], "description": "Pickup or physical shipping" }, "fulfillmentStatus": { "type": "string", "enum": [ "not_started", "waiting_payment", "preparing", "ready_for_pickup", "picked_up", "ready_to_ship", "shipped", "in_transit", "delivered", "returned", "cancelled" ], "description": "Fulfillment state" }, "paymentMethod": { "type": "string", "nullable": true, "description": "Payment method identifier" }, "itemCount": { "type": "integer", "description": "Number of items in the order" }, "totals": { "$ref": "#/components/schemas/CustomerOrderTotals" }, "submittedAt": { "type": "string", "format": "date-time", "description": "When the order was submitted" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the order was created" } } }, "CustomerOrderDetailResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/CustomerOrderDetail" } } }, "CustomerShipmentListResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerShipmentSafe" } } } }, "CustomerShipmentSafe": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Shipment ID" }, "carrierName": { "type": "string", "nullable": true }, "trackingNumber": { "type": "string", "nullable": true, "description": "Tracking number" }, "carrier": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" } }, "description": "Carrier information" }, "deliveryType": { "type": "string", "enum": [ "shipping" ], "description": "Physical shipping only; pickup has no shipment record" }, "status": { "type": "string", "enum": [ "pending", "preparing", "ready_to_ship", "shipped", "in_transit", "delivered", "failed", "returned", "cancelled" ], "description": "Shipment status" }, "trackingUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Normalized public HTTPS tracking URL; credentialed, custom-port, fragment, IP and local/internal host values are suppressed." }, "estimatedDelivery": { "type": "string", "format": "date-time", "nullable": true, "description": "Estimated delivery date (not available in V1)" }, "shippedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the shipment was dispatched" }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the shipment was delivered" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the shipment record was created" } } }, "CustomerOrderTimelineResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOrderTimelineEntry" } } } }, "CustomerOrderTimelineEntry": { "type": "object", "additionalProperties": false, "properties": { "event": { "type": "string", "enum": [ "order_placed", "order_approved", "order_rejected", "order_expired", "order_cancelled", "order_delivered", "refund_started", "refund_confirmed" ], "description": "Timeline event type" }, "at": { "type": "string", "format": "date-time", "description": "When the event occurred" } } }, "CancellationRequestCreate": { "type": "object", "additionalProperties": false, "required": [ "reasonCode" ], "properties": { "reasonCode": { "type": "string", "enum": [ "customer_requested", "changed_mind", "found_cheaper", "duplicate_order", "other" ], "description": "Cancellation reason code" }, "customerNote": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Optional customer note for the cancellation request" } } }, "CancellationRequestCreateResponse": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "boolean" }, "result": { "$ref": "#/components/schemas/CancellationRequestSafe" }, "code": { "type": "string", "example": "order.cancellationRequested" }, "messageCode": { "type": "string", "example": "order.cancellationRequested" } } }, "CancellationRequestSafe": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Cancellation request ID" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn", "completed" ], "description": "Request status" }, "reasonCode": { "type": "string", "description": "Cancellation reason code" }, "customerNote": { "type": "string", "nullable": true, "description": "Customer note" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the request was created" }, "reviewedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the request was reviewed" }, "duplicate": { "type": "boolean", "description": "True if this is an idempotent replay of the same request" } } }, "GeoCity": { "type": "object", "additionalProperties": false, "required": [ "id", "code", "name" ], "properties": { "id": { "type": "string", "pattern": "^\\d{2}$", "example": "34" }, "code": { "type": "string", "pattern": "^\\d{2}$", "example": "34" }, "name": { "type": "string", "example": "İstanbul" } } }, "GeoDistrict": { "type": "object", "additionalProperties": false, "required": [ "id", "code", "name" ], "properties": { "id": { "type": "string", "example": "34-01" }, "code": { "type": "string", "example": "34-01" }, "name": { "type": "string", "example": "Adalar" } } } }, "responses": { "RateLimitStoreUnavailable": { "description": "Shared rate-limit state is unavailable; the protected operation was not executed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "status": false, "code": "rateLimit.storeUnavailable", "messageCode": "rateLimit.storeUnavailable", "prop": "rateLimit", "message": "Request capacity checks are temporarily unavailable. Please try again later." } } } } }, "parameters": { "StatusParam": { "name": "status", "in": "query", "required": false, "description": "Filter by active status (true/false)", "schema": { "type": "string", "enum": [ "true", "false" ] } }, "PageParam": { "name": "page", "in": "query", "required": false, "description": "Page number (default: 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PageSizeParam": { "name": "pageSize", "in": "query", "required": false, "description": "Items per page (default: 25, max: 250)", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 25 } }, "IdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, "QParam": { "name": "q", "in": "query", "required": false, "description": "Free-text search across relevant fields (trimmed, regex-escaped, Turkish-aware)", "schema": { "type": "string" } }, "DateFromParam": { "name": "dateFrom", "in": "query", "required": false, "description": "Inclusive range start. A calendar date uses midnight in the active shop profile timeZone (default Europe/Istanbul); an offset-bearing ISO datetime preserves its instant.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-01-01" }, "DateToParam": { "name": "dateTo", "in": "query", "required": false, "description": "Inclusive range end. A calendar date expands to the end of that day in the active shop profile timeZone, including daylight-saving changes. Offset-bearing ISO datetimes preserve their instant.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-12-31" }, "SortByParam": { "name": "sortBy", "in": "query", "required": false, "description": "Sort field (allowlist-gated; invalid values fall back to default)", "schema": { "type": "string" } }, "SortDirParam": { "name": "sortDir", "in": "query", "required": false, "description": "Sort direction: asc or desc (invalid values fall back to default)", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } }, "securitySchemes": { "customerBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Customer-only access JWT. Staff tokens and API keys are rejected." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Scoped staff/integration API key. Its credential shop is authoritative; a supplied shop header must match." } } }, "x-sarraf-contract-revision": "e524be11b197d719e83478019f1700a6b2e08506e06c151db19529b7303ddf6c" }