{ "openapi": "3.0.3", "info": { "title": "Socrate Store Reseller API", "version": "1.1.0", "description": "Server-to-server API for registered Telegram users. Create a personal key in the bot profile; blocked or revoked access cannot self-reactivate. RUB amounts are integer kopecks. Never expose API keys in browser code. Documentation: https://api.socrate.store/" }, "servers": [ { "url": "https://api.socrate.store" } ], "security": [ { "ApiKey": [] } ], "paths": { "/v1/account": { "get": { "operationId": "getAccount", "summary": "Balance and account limits", "parameters": [], "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "description": "INVALID_API_KEY", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API_ACCESS_INACTIVE", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" }, "Retry-After": { "schema": { "type": "string" }, "description": "Wait this many seconds before retrying" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR; reconcile order before retrying", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account/settings": { "patch": { "operationId": "setAccountSettings", "summary": "Enable or disable new preorders for your own account", "parameters": [], "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSettings" } } } }, "400": { "description": "INVALID_REQUEST", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_API_KEY", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API_ACCESS_INACTIVE", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" }, "Retry-After": { "schema": { "type": "string" }, "description": "Wait this many seconds before retrying" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR; reconcile order before retrying", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSettings" } } } } } }, "/v1/products": { "get": { "operationId": "listProducts", "summary": "Text products, including zero stock", "parameters": [ { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ru", "en" ], "default": "ru" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } }, "400": { "description": "INVALID_REQUEST", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_API_KEY", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API_ACCESS_INACTIVE", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" }, "Retry-After": { "schema": { "type": "string" }, "description": "Wait this many seconds before retrying" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR; reconcile order before retrying", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/products/{sku}": { "get": { "operationId": "getProduct", "summary": "Product details", "parameters": [ { "name": "sku", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^g-[1-9][0-9]*$", "maxLength": 21, "example": "g-7" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ru", "en" ], "default": "ru" } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "INVALID_REQUEST", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_API_KEY", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API_ACCESS_INACTIVE", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" }, "Retry-After": { "schema": { "type": "string" }, "description": "Wait this many seconds before retrying" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR; reconcile order before retrying", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders": { "get": { "operationId": "getOrderByExternalId", "summary": "Read own API order by external ID", "parameters": [ { "name": "external_order_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "INVALID_REQUEST", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_API_KEY", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API_ACCESS_INACTIVE", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" }, "Retry-After": { "schema": { "type": "string" }, "description": "Wait this many seconds before retrying" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR; reconcile order before retrying", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createOrder", "summary": "Purchase stock using reseller balance", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Existing order replay; idempotency_replayed=true", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "INVALID_REQUEST", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_API_KEY", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "INSUFFICIENT_BALANCE", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API_ACCESS_INACTIVE", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "OUT_OF_STOCK, PREORDER_DISABLED, PRICE_LIMIT_REQUIRED, PRICE_CHANGED or IDEMPOTENCY_CONFLICT", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" }, "Retry-After": { "schema": { "type": "string" }, "description": "Wait this many seconds before retrying" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR; reconcile order before retrying", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "New purchase committed; idempotency_replayed=false", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "413": { "description": "Request body too large. Proxy response may be non-JSON." } }, "description": "Real funds are charged. Persist external_order_id, Idempotency-Key and payload before sending. For recovery reuse BOTH identifiers and all payload fields unchanged. A successful replay does not charge again. After timeout or 5xx look up the order by external_order_id. For pending preorders, poll GET order for delivery; replay returns current delivery state without a new charge. Preorders require product permission, account accept_preorders=true and request allow_preorder=true plus max_unit_price_minor. The full price is charged immediately and remains fixed for the paid order. Disabling preorders only blocks new ones. No sandbox or webhooks. JSON body limit: 8192 bytes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" }, "example": { "external_order_id": "1001", "sku": "g-7", "quantity": 2, "max_unit_price_minor": 7900 } } } } } }, "/v1/orders/recent": { "get": { "operationId": "listRecentOrders", "summary": "Own API orders, newest first", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "before_id", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9223372036854775807 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderHistory" } } } }, "400": { "description": "INVALID_REQUEST", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_API_KEY", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API_ACCESS_INACTIVE", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" }, "Retry-After": { "schema": { "type": "string" }, "description": "Wait this many seconds before retrying" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR; reconcile order before retrying", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/{order_id}": { "get": { "operationId": "getOrderById", "summary": "Read own API order by shop ID", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9223372036854775807 } } ], "responses": { "200": { "description": "Success", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "INVALID_REQUEST", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_API_KEY", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API_ACCESS_INACTIVE", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" }, "Retry-After": { "schema": { "type": "string" }, "description": "Wait this many seconds before retrying" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR; reconcile order before retrying", "headers": { "X-Request-ID": { "schema": { "type": "string" }, "description": "Support correlation ID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Account": { "type": "object", "properties": { "user_id": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9223372036854775807 }, "active": { "type": "boolean" }, "currency": { "type": "string", "enum": [ "RUB" ] }, "balance_minor": { "type": "integer" }, "max_quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "rate_limit_per_minute": { "type": "integer", "minimum": 1 }, "accept_preorders": { "type": "boolean", "default": false } }, "required": [ "user_id", "active", "currency", "balance_minor", "max_quantity", "rate_limit_per_minute", "accept_preorders" ] }, "Product": { "type": "object", "properties": { "sku": { "type": "string", "pattern": "^g-[1-9][0-9]*$", "maxLength": 21, "example": "g-7" }, "name": { "type": "string" }, "description": { "type": "string" }, "currency": { "type": "string", "enum": [ "RUB" ] }, "unit_price_minor": { "type": "integer", "minimum": 0 }, "available_quantity": { "type": "integer", "minimum": 0 }, "min_quantity": { "type": "integer", "enum": [ 1 ] }, "max_quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "bulk_discounts": { "type": "array", "items": { "type": "object", "properties": { "min_quantity": { "type": "integer", "minimum": 1 }, "percent": { "type": "string" } }, "required": [ "min_quantity", "percent" ] } }, "personal_discounts": { "type": "array", "items": { "type": "object", "properties": { "min_quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "percent": { "type": "string" } }, "required": [ "min_quantity", "percent" ] } }, "shop_unit_price_minor": { "type": "integer", "minimum": 0 }, "pricing_mode": { "type": "string", "enum": [ "public", "personal_fixed", "personal_discount" ] }, "fixed_price_expired": { "type": "boolean" }, "preorder_enabled": { "type": "boolean", "description": "Product permits preorders." }, "preorder_available": { "type": "boolean", "description": "Both product and account permit preorders; explicit request opt-in is still required." }, "delivery_type": { "type": "string", "enum": [ "text" ] } }, "required": [ "sku", "name", "description", "currency", "unit_price_minor", "available_quantity", "min_quantity", "max_quantity", "bulk_discounts", "personal_discounts", "shop_unit_price_minor", "pricing_mode", "fixed_price_expired", "preorder_enabled", "preorder_available", "delivery_type" ] }, "OrderRequest": { "type": "object", "properties": { "external_order_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "sku": { "type": "string", "pattern": "^g-[1-9][0-9]*$", "maxLength": 21, "example": "g-7" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "allow_preorder": { "type": "boolean", "default": false, "description": "Explicit consent to immediate full charge and delayed delivery if stock is insufficient." }, "max_unit_price_minor": { "type": "integer", "minimum": 0, "nullable": true, "description": "Maximum unit_price_minor before percentage discounts, or active personal fixed price. Required for preorders and after fixed-price expiry." } }, "required": [ "external_order_id", "sku", "quantity" ] }, "Order": { "type": "object", "properties": { "order_id": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9223372036854775807 }, "external_order_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "completed", "pending", "cancelled" ] }, "sku": { "type": "string", "pattern": "^g-[1-9][0-9]*$", "maxLength": 21, "example": "g-7" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "delivered_quantity": { "type": "integer", "minimum": 0 }, "pending_quantity": { "type": "integer", "minimum": 0 }, "refunded_minor": { "type": "integer", "minimum": 0 }, "is_preorder": { "type": "boolean" }, "pricing": { "type": "object", "nullable": true, "description": "Original pricing snapshot; null for legacy orders.", "properties": { "unit_price_minor": { "type": "integer", "minimum": 0 }, "charged_minor": { "type": "integer", "minimum": 0 }, "source": { "type": "string" }, "discount_percent": { "type": "string" } } }, "charged_minor": { "type": "integer", "minimum": 0 }, "balance_minor": { "type": "integer", "description": "Balance snapshot after this order, not current balance on replay." }, "items": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1 }, "content": { "type": "string" } }, "required": [ "position", "content" ] } }, "idempotency_replayed": { "type": "boolean" } }, "required": [ "order_id", "external_order_id", "status", "sku", "quantity", "delivered_quantity", "pending_quantity", "refunded_minor", "is_preorder", "pricing", "charged_minor", "balance_minor", "items", "idempotency_replayed" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "request_id", "retryable", "details" ] } }, "required": [ "error" ] }, "ProductList": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } }, "required": [ "products" ] }, "AccountSettings": { "type": "object", "properties": { "accept_preorders": { "type": "boolean" } }, "required": [ "accept_preorders" ], "additionalProperties": false }, "OrderHistory": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "next_before_id": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 9223372036854775807, "nullable": true } }, "required": [ "orders", "next_before_id" ] } } } }