{ "openapi": "3.1.0", "info": { "title": "GMXAZ Bot Public API", "version": "v1", "description": "Полное описание OpenAPI 3.1 для Public API GMXAZ Bot, включая подписанные webhook заказов." }, "servers": [ { "url": "https://gmx.az/api/v1" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/getMe": { "get": { "tags": [ "Аккаунт" ], "operationId": "get_me", "summary": "Проверить API аккаунт", "description": "Возвращает API пользователя, баланс и валюту.\n\nИспользуйте этот адрес для проверки API ключа и статуса аккаунта.", "parameters": [], "responses": { "200": { "description": "Возвращает API пользователя, баланс и валюту.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "user_id": { "type": "integer", "example": 579365494 }, "username": { "type": "string", "example": "reseller_pro" }, "balance": { "type": "string", "example": "1250.5000" }, "currency": { "type": "string", "example": "USD" }, "webhook_secret_configured": { "type": "boolean", "example": true } }, "example": { "user_id": 579365494, "username": "reseller_pro", "balance": "1250.5000", "currency": "USD", "webhook_secret_configured": true }, "additionalProperties": true } }, "example": { "success": true, "data": { "user_id": 579365494, "username": "reseller_pro", "balance": "1250.5000", "currency": "USD", "webhook_secret_configured": true } }, "additionalProperties": true }, "example": { "success": true, "data": { "user_id": 579365494, "username": "reseller_pro", "balance": "1250.5000", "currency": "USD", "webhook_secret_configured": true } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } } } } }, "/games": { "get": { "tags": [ "Каталог" ], "operationId": "games", "summary": "Список игр", "description": "Возвращает активные игры и категории.\n\nИгры можно фильтровать по типу и искать по названию.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Фильтр типа товара.", "schema": { "type": "string", "enum": [ "voucher", "topup" ], "example": "topup" } }, { "name": "q", "in": "query", "required": false, "description": "Поиск по названию игры.", "schema": { "type": "string", "example": "pubg" } } ], "responses": { "200": { "description": "Возвращает активные игры и категории.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "PUBG Mobile" }, "type": { "type": "string", "example": "TOPUP" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Global" }, "per_page_count": { "type": "integer", "example": 12 } }, "example": { "id": 10, "name": "Global", "per_page_count": 12 }, "additionalProperties": true }, "example": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } }, "example": { "id": 1, "name": "PUBG Mobile", "type": "TOPUP", "categories": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] }, "additionalProperties": true }, "example": [ { "id": 1, "name": "PUBG Mobile", "type": "TOPUP", "categories": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } ] } }, "example": { "success": true, "data": [ { "id": 1, "name": "PUBG Mobile", "type": "TOPUP", "categories": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } ] }, "additionalProperties": true }, "example": { "success": true, "data": [ { "id": 1, "name": "PUBG Mobile", "type": "TOPUP", "categories": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } ] } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "422": { "description": "Параметр type или q имеет неверный формат.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Параметр type или q имеет неверный формат." } } } } } } } } } }, "/categories": { "get": { "tags": [ "Каталог" ], "operationId": "categories", "summary": "Список категорий", "description": "Возвращает активные категории выбранной игры.\n\ngame_id обязателен и берётся из ответа /games.", "parameters": [ { "name": "game_id", "in": "query", "required": true, "description": "ID активной игры.", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Возвращает активные категории выбранной игры.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Global" }, "per_page_count": { "type": "integer", "example": 12 } }, "example": { "id": 10, "name": "Global", "per_page_count": 12 }, "additionalProperties": true }, "example": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } }, "example": { "success": true, "data": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] }, "additionalProperties": true }, "example": { "success": true, "data": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "422": { "description": "game_id не передан или не является целым числом.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "game_id не передан или не является целым числом." } } } } } } }, "404": { "description": "Игра не найдена или неактивна.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "GAME_NOT_FOUND": { "value": { "success": false, "error": { "code": "GAME_NOT_FOUND", "message": "Игра не найдена или неактивна." } } } } } } } } } }, "/products": { "get": { "tags": [ "Каталог" ], "operationId": "products", "summary": "Список товаров", "description": "Возвращает товары, цены, остатки, поля и пагинацию.\n\nФильтры можно использовать вместе. Возвращаются товары активных игр и категорий.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "voucher или topup.", "schema": { "type": "string", "enum": [ "voucher", "topup" ], "example": "topup" } }, { "name": "game", "in": "query", "required": false, "description": "Частичный поиск по названию игры.", "schema": { "type": "string", "example": "PUBG" } }, { "name": "category", "in": "query", "required": false, "description": "Частичный поиск по названию категории.", "schema": { "type": "string", "example": "Global" } }, { "name": "game_id", "in": "query", "required": false, "description": "ID игры.", "schema": { "type": "integer", "example": 1 } }, { "name": "category_id", "in": "query", "required": false, "description": "ID категории.", "schema": { "type": "integer", "example": 10 } }, { "name": "q", "in": "query", "required": false, "description": "Поиск по названию товара.", "schema": { "type": "string", "example": "60 UC" } }, { "name": "page", "in": "query", "required": false, "description": "Номер страницы.", "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Размер страницы. Текущий максимум: 100.", "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "Возвращает товары, цены, остатки, поля и пагинацию.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 91 }, "name": { "type": "string", "example": "PUBG Mobile 60 UC" }, "game_id": { "type": "integer", "example": 1 }, "game": { "type": "string", "example": "PUBG Mobile" }, "category_id": { "type": "integer", "example": 10 }, "category": { "type": "string", "example": "Global" }, "type": { "type": "string", "example": "TOPUP" }, "fulfillment_type": { "type": "string", "example": "standard" }, "is_qr_login": { "type": "boolean", "example": false }, "price": { "type": "string", "example": "0.8800" }, "currency": { "type": "string", "example": "USD" }, "stock_status": { "type": "string", "example": "INFINITE" }, "stock_count": { "type": [ "string", "null" ] }, "min_qty": { "type": "integer", "example": 1 }, "max_qty": { "type": "integer", "example": 1 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "player_id" }, "label": { "type": "string", "example": "ID игрока" }, "required": { "type": "boolean", "example": true } }, "example": { "key": "player_id", "label": "ID игрока", "required": true }, "additionalProperties": true }, "example": [ { "key": "player_id", "label": "ID игрока", "required": true } ] }, "supports_player_validation": { "type": "boolean", "example": true } }, "example": { "id": 91, "name": "PUBG Mobile 60 UC", "game_id": 1, "game": "PUBG Mobile", "category_id": 10, "category": "Global", "type": "TOPUP", "fulfillment_type": "standard", "is_qr_login": false, "price": "0.8800", "currency": "USD", "stock_status": "INFINITE", "stock_count": null, "min_qty": 1, "max_qty": 1, "fields": [ { "key": "player_id", "label": "ID игрока", "required": true } ], "supports_player_validation": true }, "additionalProperties": true }, "example": [ { "id": 91, "name": "PUBG Mobile 60 UC", "game_id": 1, "game": "PUBG Mobile", "category_id": 10, "category": "Global", "type": "TOPUP", "fulfillment_type": "standard", "is_qr_login": false, "price": "0.8800", "currency": "USD", "stock_status": "INFINITE", "stock_count": null, "min_qty": 1, "max_qty": 1, "fields": [ { "key": "player_id", "label": "ID игрока", "required": true } ], "supports_player_validation": true } ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 1 } }, "example": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }, "additionalProperties": true } }, "example": { "success": true, "data": [ { "id": 91, "name": "PUBG Mobile 60 UC", "game_id": 1, "game": "PUBG Mobile", "category_id": 10, "category": "Global", "type": "TOPUP", "fulfillment_type": "standard", "is_qr_login": false, "price": "0.8800", "currency": "USD", "stock_status": "INFINITE", "stock_count": null, "min_qty": 1, "max_qty": 1, "fields": [ { "key": "player_id", "label": "ID игрока", "required": true } ], "supports_player_validation": true } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 } }, "additionalProperties": true }, "example": { "success": true, "data": [ { "id": 91, "name": "PUBG Mobile 60 UC", "game_id": 1, "game": "PUBG Mobile", "category_id": 10, "category": "Global", "type": "TOPUP", "fulfillment_type": "standard", "is_qr_login": false, "price": "0.8800", "currency": "USD", "stock_status": "INFINITE", "stock_count": null, "min_qty": 1, "max_qty": 1, "fields": [ { "key": "player_id", "label": "ID игрока", "required": true } ], "supports_player_validation": true } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "422": { "description": "Неверный фильтр или параметр пагинации.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Неверный фильтр или параметр пагинации." } } } } } } } } } }, "/validate-player": { "post": { "tags": [ "Проверка" ], "operationId": "validate_player", "summary": "Проверить игрока", "description": "Проверяет ID игрока и при необходимости ID сервера.\n\nЕсли проверка необязательна, может вернуться validation_optional=true.", "parameters": [], "responses": { "200": { "description": "Проверяет ID игрока и при необходимости ID сервера.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "nickname": { "type": "string", "example": "PlayerOne" }, "player_name": { "type": "string", "example": "PlayerOne" }, "region": { "type": "string", "example": "TR" }, "country": { "type": "string", "example": "TR" }, "server": { "type": "string", "example": "1234" }, "nickname_verified": { "type": "boolean", "example": true }, "validation_optional": { "type": "boolean", "example": false } }, "example": { "nickname": "PlayerOne", "player_name": "PlayerOne", "region": "TR", "country": "TR", "server": "1234", "nickname_verified": true, "validation_optional": false }, "additionalProperties": true } }, "example": { "success": true, "data": { "nickname": "PlayerOne", "player_name": "PlayerOne", "region": "TR", "country": "TR", "server": "1234", "nickname_verified": true, "validation_optional": false } }, "additionalProperties": true }, "example": { "success": true, "data": { "nickname": "PlayerOne", "player_name": "PlayerOne", "region": "TR", "country": "TR", "server": "1234", "nickname_verified": true, "validation_optional": false } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "422": { "description": "Обязательное поле тела отсутствует или имеет неверный формат.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Обязательное поле тела отсутствует или имеет неверный формат." } } } } } } }, "404": { "description": "Товар пополнения не найден или неактивен.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PRODUCT_NOT_FOUND": { "value": { "success": false, "error": { "code": "PRODUCT_NOT_FOUND", "message": "Товар пополнения не найден или неактивен." } } }, "PLAYER_NOT_FOUND": { "value": { "success": false, "error": { "code": "PLAYER_NOT_FOUND", "message": "Игрок не прошёл обязательную проверку." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "example": 91, "description": "ID товара пополнения." }, "player_id": { "type": "string", "example": "51515969536", "description": "ID игрока." }, "server_id": { "type": "string", "example": "1234", "description": "ID сервера или зоны, если требуется." }, "input_2": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_3": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_4": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_5": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_6": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_7": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_8": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." } }, "additionalProperties": false, "required": [ "product_id", "player_id" ] }, "example": { "product_id": 91, "player_id": "51515969536", "server_id": "1234", "input_3": "CharacterName" } } } } } }, "/order": { "post": { "tags": [ "Заказы" ], "operationId": "place_order", "summary": "Создать заказ", "description": "Создаёт ваучерный заказ или пополнение и списывает сумму с баланса.\n\nЭтот адрес создаёт реальную финансовую операцию. Используйте X-Idempotency-Key для повторных запросов.", "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Уникальный ключ повтора. Обязателен для операций, меняющих баланс; для POST /order client_order_id может использоваться как резервный ключ.", "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Создаёт ваучерный заказ или пополнение и списывает сумму с баланса.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 8821 }, "order_uuid": { "type": "string", "example": "a80f63d7-cabb-4e1d-a177-045f6467e7b2" }, "client_order_id": { "type": "string", "example": "order-10001" }, "product_id": { "type": "integer", "example": 91 }, "product_name": { "type": "string", "example": "PUBG Mobile 60 UC" }, "product_type": { "type": "string", "example": "TOPUP" }, "qty": { "type": "integer", "example": 1 }, "player_id": { "type": "string", "example": "51515969536" }, "server_id": { "type": "string", "example": "1234" }, "player_name": { "type": "string", "example": "PlayerOne" }, "region": { "type": "string", "example": "TR" }, "status": { "type": "string", "example": "PROCESSING" }, "price": { "type": "string", "example": "0.8800" }, "currency": { "type": "string", "example": "USD" }, "delivery": { "type": [ "string", "null" ] }, "manual_action_required": { "type": "boolean", "example": false }, "delivery_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "example": "2026-07-25T13:30:00+04:00" }, "completed_at": { "type": [ "string", "null" ] } }, "example": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 91, "product_name": "PUBG Mobile 60 UC", "product_type": "TOPUP", "qty": 1, "player_id": "51515969536", "server_id": "1234", "player_name": "PlayerOne", "region": "TR", "status": "PROCESSING", "price": "0.8800", "currency": "USD", "delivery": null, "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": null }, "additionalProperties": true } }, "example": { "success": true, "data": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 91, "product_name": "PUBG Mobile 60 UC", "product_type": "TOPUP", "qty": 1, "player_id": "51515969536", "server_id": "1234", "player_name": "PlayerOne", "region": "TR", "status": "PROCESSING", "price": "0.8800", "currency": "USD", "delivery": null, "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": null } }, "additionalProperties": true }, "example": { "success": true, "data": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 91, "product_name": "PUBG Mobile 60 UC", "product_type": "TOPUP", "qty": 1, "player_id": "51515969536", "server_id": "1234", "player_name": "PlayerOne", "region": "TR", "status": "PROCESSING", "price": "0.8800", "currency": "USD", "delivery": null, "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": null } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "422": { "description": "Одно из полей тела запроса неверно.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Одно из полей тела запроса неверно." } } }, "INVALID_QUANTITY": { "value": { "success": false, "error": { "code": "INVALID_QUANTITY", "message": "Количество превышает лимит товара или API." } } }, "PLAYER_ID_REQUIRED": { "value": { "success": false, "error": { "code": "PLAYER_ID_REQUIRED", "message": "Для пополнения требуется player_id." } } }, "SERVER_ID_REQUIRED": { "value": { "success": false, "error": { "code": "SERVER_ID_REQUIRED", "message": "Для товара требуется server_id." } } }, "IDEMPOTENCY_KEY_REQUIRED": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REQUIRED", "message": "Для этой операции требуется стабильный ключ идемпотентности." } } }, "IDEMPOTENCY_KEY_INVALID": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_INVALID", "message": "Ключ идемпотентности недействителен или длиннее 128 символов." } } } } } } }, "404": { "description": "Товар не найден или неактивен.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PRODUCT_NOT_FOUND": { "value": { "success": false, "error": { "code": "PRODUCT_NOT_FOUND", "message": "Товар не найден или неактивен." } } }, "PLAYER_NOT_FOUND": { "value": { "success": false, "error": { "code": "PLAYER_NOT_FOUND", "message": "Обязательная проверка игрока не пройдена." } } } } } } }, "400": { "description": "Недостаточно средств для заказа.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "INSUFFICIENT_FUNDS": { "value": { "success": false, "error": { "code": "INSUFFICIENT_FUNDS", "message": "Недостаточно средств для заказа." } } }, "SECURITY_ERROR": { "value": { "success": false, "error": { "code": "SECURITY_ERROR", "message": "URL обратного вызова не соответствует требованиям безопасности." } } } } } } }, "409": { "description": "Не удалось создать или обработать заказ.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "OUT_OF_STOCK": { "value": { "success": false, "error": { "code": "OUT_OF_STOCK", "message": "Не удалось создать или обработать заказ." } } }, "IDEMPOTENCY_CONFLICT": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Один ключ использован с другим содержимым запроса." } } }, "CLIENT_ORDER_ID_CONFLICT": { "value": { "success": false, "error": { "code": "CLIENT_ORDER_ID_CONFLICT", "message": "Этот client_order_id уже назначен другому заказу." } } }, "ORDER_FAILED": { "value": { "success": false, "error": { "code": "ORDER_FAILED", "message": "Не удалось создать или обработать заказ." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "example": 91, "description": "ID активного товара." }, "qty": { "type": "integer", "example": 1, "description": "Максимум ваучеров: 500; максимум пополнений: 1." }, "player_id": { "type": "string", "example": "51515969536", "description": "Обязательно для пополнения." }, "server_id": { "type": "string", "example": "1234", "description": "ID сервера или зоны, если требуется." }, "input_2": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_3": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_4": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_5": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_6": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_7": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "input_8": { "type": "string", "example": "Additional mapped values", "description": "Дополнительные значения input_2...input_8 согласно списку fields продукта." }, "client_order_id": { "type": "string", "example": "client-order-10001", "description": "Ваш собственный идентификатор заказа. Если в POST /order нет X-Idempotency-Key, это значение также используется как ключ повтора." }, "callback_url": { "type": "string", "example": "https://customer.example/webhooks/bot-manager", "description": "Безопасный HTTPS URL обратного вызова." }, "callback_mode": { "type": "string", "enum": [ "legacy", "events" ], "example": "legacy", "description": "Формат обратного вызова. По умолчанию: legacy." } }, "additionalProperties": false, "required": [ "product_id" ] }, "example": { "product_id": 91, "qty": 1, "player_id": "51515969536", "server_id": "1234", "input_3": "CharacterName", "client_order_id": "client-order-10001", "callback_url": "https://customer.example/webhooks/bot-manager", "callback_mode": "events" } } } } } }, "/order/{id}/qr-login/status": { "get": { "tags": [ "Заказы" ], "operationId": "qr_login_status", "summary": "Статус QR Login", "description": "Получить текущее состояние QR Login для своего заказа.\n\nВозвращает наличие QR, версию, состояние оператора, срок действия и разрешённые действия.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid или client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Получить текущее состояние QR Login для своего заказа.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 8821 }, "order_status": { "type": "string", "example": "PROCESSING" }, "session_status": { "type": "string", "example": "QR_READY" }, "status_label": { "type": "string", "example": "QR code is ready." }, "has_qr": { "type": "boolean", "example": true }, "qr_version": { "type": "integer", "example": 1 }, "qr_image_url": { "type": "string", "example": "https://gmx.az/api/v1/order/8821/qr-login/preview?v=1" }, "expires_at": { "type": "string", "example": "2026-08-17T16:30:00+04:00" }, "can_mark_scanned": { "type": "boolean", "example": true }, "can_request_new_qr": { "type": "boolean", "example": true }, "can_submit_otp": { "type": "boolean", "example": false }, "is_final": { "type": "boolean", "example": false } }, "example": { "order_id": 8821, "order_status": "PROCESSING", "session_status": "QR_READY", "status_label": "QR code is ready.", "has_qr": true, "qr_version": 1, "qr_image_url": "https://gmx.az/api/v1/order/8821/qr-login/preview?v=1", "expires_at": "2026-08-17T16:30:00+04:00", "can_mark_scanned": true, "can_request_new_qr": true, "can_submit_otp": false, "is_final": false }, "additionalProperties": true } }, "example": { "success": true, "data": { "order_id": 8821, "order_status": "PROCESSING", "session_status": "QR_READY", "status_label": "QR code is ready.", "has_qr": true, "qr_version": 1, "qr_image_url": "https://gmx.az/api/v1/order/8821/qr-login/preview?v=1", "expires_at": "2026-08-17T16:30:00+04:00", "can_mark_scanned": true, "can_request_new_qr": true, "can_submit_otp": false, "is_final": false } }, "additionalProperties": true }, "example": { "success": true, "data": { "order_id": 8821, "order_status": "PROCESSING", "session_status": "QR_READY", "status_label": "QR code is ready.", "has_qr": true, "qr_version": 1, "qr_image_url": "https://gmx.az/api/v1/order/8821/qr-login/preview?v=1", "expires_at": "2026-08-17T16:30:00+04:00", "can_mark_scanned": true, "can_request_new_qr": true, "can_submit_otp": false, "is_final": false } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "404": { "description": "Заказ не найден или принадлежит другому API пользователю.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "Заказ не найден или принадлежит другому API пользователю." } } } } } } } } } }, "/order/{id}/qr-login/preview": { "get": { "tags": [ "Заказы" ], "operationId": "qr_login_preview", "summary": "QR Login изображение", "description": "Получить текущее активное QR-изображение.\n\nВозвращает приватный JPEG только пока QR активен. Используйте тот же API-ключ. Обычный тег не может отправить X-API-KEY, поэтому загрузите изображение авторизованным binary/blob-запросом и покажите полученный object URL.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid или client_order_id.", "schema": { "type": "string", "example": "8821" } }, { "name": "v", "in": "query", "required": false, "description": "Необязательная версия QR для обхода кеша.", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Получить текущее активное QR-изображение.", "content": { "application/json": { "schema": { "type": "string", "example": "Бинарный ответ image/jpeg." }, "example": "Бинарный ответ image/jpeg." } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "404": { "description": "Заказ не найден или принадлежит другому API пользователю.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "Заказ не найден или принадлежит другому API пользователю." } } } } } } } } } }, "/order/{id}/qr-login/scanned": { "post": { "tags": [ "Заказы" ], "operationId": "qr_login_scanned", "summary": "Подтвердить сканирование QR", "description": "Сообщить назначенному оператору, что клиент отсканировал активный QR.\n\nИспользуйте только после реального сканирования QR клиентом. Это не завершает заказ автоматически.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid или client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Сообщить назначенному оператору, что клиент отсканировал активный QR.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "session_status": { "type": "string", "example": "customer_scanned" }, "has_qr": { "type": "boolean", "example": true } }, "example": { "session_status": "customer_scanned", "has_qr": true }, "additionalProperties": true } }, "example": { "success": true, "data": { "session_status": "customer_scanned", "has_qr": true } }, "additionalProperties": true }, "example": { "success": true, "data": { "session_status": "customer_scanned", "has_qr": true } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "404": { "description": "Заказ не найден или принадлежит другому API пользователю.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "Заказ не найден или принадлежит другому API пользователю." } } } } } } } } } }, "/order/{id}/qr-login/new-qr": { "post": { "tags": [ "Заказы" ], "operationId": "qr_login_new_qr", "summary": "Запросить новый QR", "description": "Сделать текущий QR недействительным и запросить замену.\n\nИспользуйте если QR истёк или не сканируется.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid или client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Сделать текущий QR недействительным и запросить замену.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "session_status": { "type": "string", "example": "awaiting_new_qr" }, "has_qr": { "type": "boolean", "example": false } }, "example": { "session_status": "awaiting_new_qr", "has_qr": false }, "additionalProperties": true } }, "example": { "success": true, "data": { "session_status": "awaiting_new_qr", "has_qr": false } }, "additionalProperties": true }, "example": { "success": true, "data": { "session_status": "awaiting_new_qr", "has_qr": false } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "404": { "description": "Заказ не найден или принадлежит другому API пользователю.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "Заказ не найден или принадлежит другому API пользователю." } } } } } } } } } }, "/order/{id}/qr-login/otp": { "post": { "tags": [ "Заказы" ], "operationId": "qr_login_otp", "summary": "Отправить OTP для QR Login", "description": "Отправить одноразовый код, запрошенный назначенным оператором.\n\nOTP принимается только на этапе awaiting_otp и передаётся оператору без сохранения в базе.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid или client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Отправить одноразовый код, запрошенный назначенным оператором.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "session_status": { "type": "string", "example": "customer_scanned" }, "has_qr": { "type": "boolean", "example": true } }, "example": { "session_status": "customer_scanned", "has_qr": true }, "additionalProperties": true } }, "example": { "success": true, "data": { "session_status": "customer_scanned", "has_qr": true } }, "additionalProperties": true }, "example": { "success": true, "data": { "session_status": "customer_scanned", "has_qr": true } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "422": { "description": "OTP должен содержать 4-10 цифр.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "OTP должен содержать 4-10 цифр." } } } } } } }, "404": { "description": "Заказ не найден или принадлежит другому API пользователю.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "Заказ не найден или принадлежит другому API пользователю." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "otp": { "type": "string", "example": "123456", "description": "Одноразовый код из 4-10 цифр." } }, "additionalProperties": false, "required": [ "otp" ] }, "example": { "otp": "123456" } } } } } }, "/order/{id}": { "get": { "tags": [ "Заказы" ], "operationId": "order_status", "summary": "Получить статус заказа", "description": "Находит заказ по ID, UUID или client_order_id.\n\nВозвращает текущий статус и коды выдачи ваучера, если они доступны.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid или client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Находит заказ по ID, UUID или client_order_id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 8821 }, "order_uuid": { "type": "string", "example": "a80f63d7-cabb-4e1d-a177-045f6467e7b2" }, "client_order_id": { "type": "string", "example": "order-10001" }, "product_id": { "type": "integer", "example": 17 }, "product_name": { "type": "string", "example": "Steam Wallet 10 USD" }, "product_type": { "type": "string", "example": "VOUCHER" }, "qty": { "type": "integer", "example": 2 }, "player_id": { "type": [ "string", "null" ] }, "server_id": { "type": [ "string", "null" ] }, "player_name": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "status": { "type": "string", "example": "COMPLETED" }, "price": { "type": "string", "example": "19.9800" }, "currency": { "type": "string", "example": "USD" }, "delivery": { "type": "array", "items": { "type": "string", "example": "CODE-ONE-XXXX" }, "example": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ] }, "manual_action_required": { "type": "boolean", "example": false }, "delivery_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "example": "2026-07-25T13:30:00+04:00" }, "completed_at": { "type": "string", "example": "2026-07-25T13:31:10+04:00" } }, "example": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 17, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 2, "player_id": null, "server_id": null, "player_name": null, "region": null, "status": "COMPLETED", "price": "19.9800", "currency": "USD", "delivery": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ], "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": "2026-07-25T13:31:10+04:00" }, "additionalProperties": true } }, "example": { "success": true, "data": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 17, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 2, "player_id": null, "server_id": null, "player_name": null, "region": null, "status": "COMPLETED", "price": "19.9800", "currency": "USD", "delivery": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ], "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": "2026-07-25T13:31:10+04:00" } }, "additionalProperties": true }, "example": { "success": true, "data": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 17, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 2, "player_id": null, "server_id": null, "player_name": null, "region": null, "status": "COMPLETED", "price": "19.9800", "currency": "USD", "delivery": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ], "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": "2026-07-25T13:31:10+04:00" } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "404": { "description": "Заказ не найден или принадлежит другому API пользователю.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "Заказ не найден или принадлежит другому API пользователю." } } } } } } } } } }, "/order-status/{id}": { "get": { "tags": [ "Заказы" ], "operationId": "order_status_legacy", "summary": "Старый адрес статуса", "description": "Совместимый адрес для /order/{id}.\n\nДля новых интеграций используйте /order/{id}.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid или client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Совместимый адрес для /order/{id}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 8821 }, "status": { "type": "string", "example": "COMPLETED" }, "delivery": { "type": "array", "items": { "type": "string", "example": "CODE-ONE-XXXX" }, "example": [ "CODE-ONE-XXXX" ] }, "manual_action_required": { "type": "boolean", "example": false }, "delivery_message": { "type": [ "string", "null" ] } }, "example": { "order_id": 8821, "status": "COMPLETED", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null }, "additionalProperties": true } }, "example": { "success": true, "data": { "order_id": 8821, "status": "COMPLETED", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } }, "additionalProperties": true }, "example": { "success": true, "data": { "order_id": 8821, "status": "COMPLETED", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "404": { "description": "Заказ не найден.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "Заказ не найден." } } } } } } } } } }, "/orders": { "get": { "tags": [ "Заказы" ], "operationId": "orders", "summary": "История заказов", "description": "Возвращает заказы текущего API пользователя с фильтрами и пагинацией.\n\nКлиент может видеть только свои заказы. Максимум per_page — 100.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Статус заказа.", "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "canceled", "cancelled", "refunded" ], "example": "completed" } }, { "name": "type", "in": "query", "required": false, "description": "Тип товара.", "schema": { "type": "string", "enum": [ "voucher", "topup" ], "example": "voucher" } }, { "name": "page", "in": "query", "required": false, "description": "Номер страницы.", "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Размер страницы. Максимум 100.", "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "Возвращает заказы текущего API пользователя с фильтрами и пагинацией.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 8821 }, "product_name": { "type": "string", "example": "Steam Wallet 10 USD" }, "product_type": { "type": "string", "example": "VOUCHER" }, "qty": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "COMPLETED" }, "price": { "type": "string", "example": "9.9900" }, "currency": { "type": "string", "example": "USD" }, "delivery": { "type": "array", "items": { "type": "string", "example": "CODE-ONE-XXXX" }, "example": [ "CODE-ONE-XXXX" ] }, "manual_action_required": { "type": "boolean", "example": false }, "delivery_message": { "type": [ "string", "null" ] } }, "example": { "order_id": 8821, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 1, "status": "COMPLETED", "price": "9.9900", "currency": "USD", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null }, "additionalProperties": true }, "example": [ { "order_id": 8821, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 1, "status": "COMPLETED", "price": "9.9900", "currency": "USD", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 1 } }, "example": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }, "additionalProperties": true } }, "example": { "success": true, "data": [ { "order_id": 8821, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 1, "status": "COMPLETED", "price": "9.9900", "currency": "USD", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 } }, "additionalProperties": true }, "example": { "success": true, "data": [ { "order_id": 8821, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 1, "status": "COMPLETED", "price": "9.9900", "currency": "USD", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "422": { "description": "Неверный фильтр или параметр пагинации.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Неверный фильтр или параметр пагинации." } } } } } } } } } }, "/redeem-check": { "post": { "tags": [ "Проверка кода" ], "operationId": "redeem_check", "summary": "Проверить данные кода", "description": "Проверяет код и списывает сумму, соответствующую результату.\n\nЭтот адрес создаёт реальную операцию с балансом. Неиспользованная часть резерва возвращается.", "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "description": "Обязательный уникальный ключ повтора. Повтор с тем же кодом возвращает исходный результат без повторного списания и повторной внешней проверки.", "schema": { "type": "string", "example": "4d83ae61-b98b-4d4d-bf11-58f3bc028a71" } } ], "responses": { "200": { "description": "Проверяет код и списывает сумму, соответствующую результату.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 142 }, "status": { "type": "string", "example": "found" }, "code_masked": { "type": "string", "example": "REDE********MPLE" }, "charged_amount": { "type": "string", "example": "0.0500" }, "charged_amount_text": { "type": "string", "example": "$ 0.05" }, "balance": { "type": "string", "example": "1250.4500" }, "balance_text": { "type": "string", "example": "$ 1250.45" }, "currency_code": { "type": "string", "example": "USD" }, "currency_symbol": { "type": "string", "example": "$" }, "redemption_time": { "type": "string", "example": "2026-07-25 13:30:00" }, "expiration_time": { "type": [ "string", "null" ] }, "amount": { "type": "integer", "example": 60 }, "product_name": { "type": "string", "example": "PUBG Mobile 60 UC" }, "player_id": { "type": "string", "example": "51515969536" }, "player_name": { "type": "string", "example": "PlayerOne" }, "created_at": { "type": "string", "example": "2026-07-25 13:30:02" } }, "example": { "id": 142, "status": "found", "code_masked": "REDE********MPLE", "charged_amount": "0.0500", "charged_amount_text": "$ 0.05", "balance": "1250.4500", "balance_text": "$ 1250.45", "currency_code": "USD", "currency_symbol": "$", "redemption_time": "2026-07-25 13:30:00", "expiration_time": null, "amount": 60, "product_name": "PUBG Mobile 60 UC", "player_id": "51515969536", "player_name": "PlayerOne", "created_at": "2026-07-25 13:30:02" }, "additionalProperties": true }, "meta": { "type": "object", "properties": { "idempotent_replay": { "type": "boolean", "example": false } }, "example": { "idempotent_replay": false }, "additionalProperties": true } }, "example": { "success": true, "data": { "id": 142, "status": "found", "code_masked": "REDE********MPLE", "charged_amount": "0.0500", "charged_amount_text": "$ 0.05", "balance": "1250.4500", "balance_text": "$ 1250.45", "currency_code": "USD", "currency_symbol": "$", "redemption_time": "2026-07-25 13:30:00", "expiration_time": null, "amount": 60, "product_name": "PUBG Mobile 60 UC", "player_id": "51515969536", "player_name": "PlayerOne", "created_at": "2026-07-25 13:30:02" }, "meta": { "idempotent_replay": false } }, "additionalProperties": true }, "example": { "success": true, "data": { "id": 142, "status": "found", "code_masked": "REDE********MPLE", "charged_amount": "0.0500", "charged_amount_text": "$ 0.05", "balance": "1250.4500", "balance_text": "$ 1250.45", "currency_code": "USD", "currency_symbol": "$", "redemption_time": "2026-07-25 13:30:00", "expiration_time": null, "amount": 60, "product_name": "PUBG Mobile 60 UC", "player_id": "51515969536", "player_name": "PlayerOne", "created_at": "2026-07-25 13:30:02" }, "meta": { "idempotent_replay": false } } } } }, "503": { "description": "Public API отключён администратором.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API отключён администратором." } } } } } } }, "401": { "description": "Заголовок X-API-KEY не передан.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "Заголовок X-API-KEY не передан." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "API ключ недействителен или отключён, либо клиент неактивен." } } } } } } }, "403": { "description": "IP адрес запроса не разрешён.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "IP адрес запроса не разрешён." } } } } } } }, "429": { "description": "Превышен лимит запросов в минуту.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Превышен лимит запросов в минуту." } } } } } } }, "422": { "description": "Для этой операции требуется стабильный ключ идемпотентности.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IDEMPOTENCY_KEY_REQUIRED": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REQUIRED", "message": "Для этой операции требуется стабильный ключ идемпотентности." } } }, "IDEMPOTENCY_KEY_INVALID": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_INVALID", "message": "Ключ идемпотентности недействителен или длиннее 128 символов." } } }, "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Код отсутствует или имеет неверную длину." } } }, "REDEEM_CHECK_FAILED": { "value": { "success": false, "error": { "code": "REDEEM_CHECK_FAILED", "message": "Проверка кода не удалась, сервис отключён или недостаточно средств." } } } } } } }, "409": { "description": "Один ключ использован с другим содержимым запроса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IDEMPOTENCY_CONFLICT": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Один ключ использован с другим содержимым запроса." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "REDEEM-CODE-EXAMPLE", "description": "Проверяемый код. 6-160 символов." } }, "additionalProperties": false, "required": [ "code" ] }, "example": { "code": "REDEEM-CODE-EXAMPLE" } } } } } } }, "webhooks": { "orderStatusChanged": { "post": { "summary": "Доставка webhook", "description": "Этот запрос показывает payload, который платформа отправляет на callback_url. Получатель должен проверить HMAC, обрабатывать event_id идемпотентно и быстро вернуть 2xx.", "security": [], "parameters": [ { "name": "X-EPINBULK-Signature-V2", "in": "header", "required": true, "description": "Рекомендуется: sha256=HMAC_SHA256(timestamp + \".\" + event_id + \".\" + raw_json_body, webhook_secret). Используйте заголовки timestamp и event-id, указанные выше.", "schema": { "type": "string" } }, { "name": "X-EPINBULK-Signature-Version", "in": "header", "required": true, "description": "2", "schema": { "type": "string" } }, { "name": "X-EPINBULK-Signature", "in": "header", "required": true, "description": "sha256=HMAC_SHA256(сырое_тело_json, секрет_webhook)", "schema": { "type": "string" } }, { "name": "X-EPINBULK-Timestamp", "in": "header", "required": true, "description": "Время отправки webhook в ISO-8601. При проверке подписи V2 проверяйте также актуальность времени.", "schema": { "type": "string" } }, { "name": "X-EPINBULK-Event-Id", "in": "header", "required": true, "description": "Уникальный UUID попытки обратного вызова.", "schema": { "type": "string" } }, { "name": "X-EPINBULK-Event", "in": "header", "required": true, "description": "Actual event name: order.status_changed or qr_login.*", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "legacy": { "value": { "event_id": "47c8c6ba-16a5-4089-9f62-7ae1e51d4c0f", "order_id": 8821, "client_order_id": "order-10001", "status": "COMPLETED", "product_name": "Steam Wallet 10 USD", "qty": 2, "player_id": null, "player_name": null, "server_id": null, "region": null, "price": "19.9800", "currency": "USD", "delivery": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ], "manual_action_required": false, "delivery_message": null, "timestamp": "2026-07-25T13:31:10+04:00" } }, "events": { "value": { "event_id": "47c8c6ba-16a5-4089-9f62-7ae1e51d4c0f", "event": "order.status_changed", "callback_mode": "events", "order_id": 8821, "client_order_id": "order-10001", "product_id": 91, "product_name": "PUBG Mobile 60 UC", "product_type": "TOPUP", "game_id": 1, "game_name": "PUBG Mobile", "player_id": "51515969536", "player_name": "PlayerOne", "server_id": "1234", "region": "TR", "qty": 1, "price": "0.8800", "currency": "USD", "delivery": [], "manual_action_required": false, "delivery_message": null, "status": "COMPLETED", "message": "Заказ успешно завершён.", "timestamp": "2026-07-25T13:30:10+04:00" } } } } } }, "responses": { "204": { "description": "Webhook accepted" }, "400": { "description": "Invalid payload" }, "401": { "description": "Invalid signature" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "Поле product_id обязательно." }, "details": { "type": "object", "properties": { "max": { "type": "integer", "example": 1 } }, "example": { "max": 1 }, "additionalProperties": true } }, "example": { "code": "VALIDATION_ERROR", "message": "Поле product_id обязательно.", "details": { "max": 1 } }, "additionalProperties": true } }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Поле product_id обязательно.", "details": { "max": 1 } } }, "additionalProperties": true } } }, "x-public-api-idempotency-header": "X-Idempotency-Key", "x-public-api-request-id-header": "X-Request-Id", "x-public-api-status-lifecycle": [ { "status": "PENDING", "terminal": false, "description": "Заказ создан и ожидает обработки." }, { "status": "PROCESSING", "terminal": false, "description": "Заказ обрабатывается." }, { "status": "COMPLETED", "terminal": true, "description": "Заказ успешно завершён. Для ваучера возвращаются коды." }, { "status": "FAILED", "terminal": true, "description": "Заказ завершился ошибкой или отменён." }, { "status": "CANCELED", "terminal": true, "description": "Заказ отменён." }, { "status": "REFUNDED", "terminal": true, "description": "Сумма возвращена на баланс." } ], "x-public-api-webhook-policy": { "event": "order.status_changed", "events": [ "order.status_changed", "qr_login.waiting_worker", "qr_login.worker_assigned", "qr_login.qr_ready", "qr_login.customer_scanned", "qr_login.new_qr_requested", "qr_login.otp_required", "qr_login.otp_submitted" ], "method": "POST", "content_type": "application/json", "headers": [ { "name": "X-EPINBULK-Signature-V2", "description": "Рекомендуется: sha256=HMAC_SHA256(timestamp + \".\" + event_id + \".\" + raw_json_body, webhook_secret). Используйте заголовки timestamp и event-id, указанные выше." }, { "name": "X-EPINBULK-Signature-Version", "description": "2" }, { "name": "X-EPINBULK-Signature", "description": "sha256=HMAC_SHA256(сырое_тело_json, секрет_webhook)" }, { "name": "X-EPINBULK-Timestamp", "description": "Время отправки webhook в ISO-8601. При проверке подписи V2 проверяйте также актуальность времени." }, { "name": "X-EPINBULK-Event-Id", "description": "Уникальный UUID попытки обратного вызова." }, { "name": "X-EPINBULK-Event", "description": "Actual event name: order.status_changed or qr_login.*" } ], "requirements": [ "Принимаются только HTTPS URL.", "Принимается только порт 443.", "Частные, зарезервированные и localhost адреса блокируются.", "Учётные данные в URL не принимаются.", "Перенаправления не выполняются.", "Сервер должен вернуть ответ 2xx." ], "retry_schedule": [ "1 → 1 минута", "2 → 5 минут", "3 → 15 минут", "4-6 → 60 минут", "7-20 → 6 часов" ], "max_attempts": 20, "legacy_example": { "event_id": "47c8c6ba-16a5-4089-9f62-7ae1e51d4c0f", "order_id": 8821, "client_order_id": "order-10001", "status": "COMPLETED", "product_name": "Steam Wallet 10 USD", "qty": 2, "player_id": null, "player_name": null, "server_id": null, "region": null, "price": "19.9800", "currency": "USD", "delivery": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ], "manual_action_required": false, "delivery_message": null, "timestamp": "2026-07-25T13:31:10+04:00" }, "events_example": { "event_id": "47c8c6ba-16a5-4089-9f62-7ae1e51d4c0f", "event": "order.status_changed", "callback_mode": "events", "order_id": 8821, "client_order_id": "order-10001", "product_id": 91, "product_name": "PUBG Mobile 60 UC", "product_type": "TOPUP", "game_id": 1, "game_name": "PUBG Mobile", "player_id": "51515969536", "player_name": "PlayerOne", "server_id": "1234", "region": "TR", "qty": 1, "price": "0.8800", "currency": "USD", "delivery": [], "manual_action_required": false, "delivery_message": null, "status": "COMPLETED", "message": "Заказ успешно завершён.", "timestamp": "2026-07-25T13:30:10+04:00" } }, "x-public-api-limits": { "max_per_page": 100, "max_voucher_qty": 500, "max_topup_qty": 1, "default_callback_mode": "legacy" } }