{ "format": "bot-manager-public-api-full-spec", "version": 1, "generated_at": "2026-09-27T11:40:03+00:00", "language": "en", "brand": "GMXAZ Bot", "documentation": { "version": "v1", "base_url": "https://gmx.az/api/v1", "currency": "USD", "currency_symbol": "$", "auth_header": "X-API-KEY", "idempotency_header": "X-Idempotency-Key", "request_id_header": "X-Request-Id", "rate_limit_per_minute": 60, "api_enabled": true, "require_ip_whitelist": false, "limits": { "max_per_page": 100, "max_voucher_qty": 500, "max_topup_qty": 1, "default_callback_mode": "legacy" }, "endpoints": [ { "id": "get-me", "group": "Account", "method": "GET", "path": "/getMe", "title": "Check API account", "summary": "Returns the API user, balance, and currency.", "description": "Use this endpoint to verify the API key and account status.", "success_status": 200, "parameters": [], "request_example": null, "response_example": { "success": true, "data": { "user_id": 579365494, "username": "reseller_pro", "balance": "1250.5000", "currency": "USD", "webhook_secret_configured": true } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." } ], "url": "https://gmx.az/api/v1/getMe", "curl": "curl -s -X GET 'https://gmx.az/api/v1/getMe' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY'" }, { "id": "games", "group": "Catalog", "method": "GET", "path": "/games", "title": "List games", "summary": "Returns active games and their active categories.", "description": "Games can be filtered by type or searched by name.", "success_status": 200, "parameters": [ { "name": "type", "location": "query", "type": "string", "required": false, "description": "Product type filter.", "example": "topup", "options": [ "voucher", "topup" ] }, { "name": "q", "location": "query", "type": "string", "required": false, "description": "Search by game name.", "example": "pubg", "options": [] } ], "request_example": null, "response_example": { "success": true, "data": [ { "id": 1, "name": "PUBG Mobile", "type": "TOPUP", "categories": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } ] }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "VALIDATION_ERROR", "status": 422, "description": "The type or q parameter is invalid." } ], "url": "https://gmx.az/api/v1/games", "curl": "curl -s -X GET 'https://gmx.az/api/v1/games?type=topup&q=pubg' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY'" }, { "id": "categories", "group": "Catalog", "method": "GET", "path": "/categories", "title": "List categories", "summary": "Returns active categories for the selected game.", "description": "game_id is required and must be taken from the /games response.", "success_status": 200, "parameters": [ { "name": "game_id", "location": "query", "type": "integer", "required": true, "description": "Active game ID.", "example": 1, "options": [] } ], "request_example": null, "response_example": { "success": true, "data": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "VALIDATION_ERROR", "status": 422, "description": "game_id is missing or is not an integer." }, { "code": "GAME_NOT_FOUND", "status": 404, "description": "The game was not found or is inactive." } ], "url": "https://gmx.az/api/v1/categories", "curl": "curl -s -X GET 'https://gmx.az/api/v1/categories?game_id=1' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY'" }, { "id": "products", "group": "Catalog", "method": "GET", "path": "/products", "title": "List products", "summary": "Returns active products with price, stock, input fields, and pagination.", "description": "Filters can be combined. Only products linked to active games and categories are returned.", "success_status": 200, "parameters": [ { "name": "type", "location": "query", "type": "string", "required": false, "description": "voucher or topup.", "example": "topup", "options": [ "voucher", "topup" ] }, { "name": "game", "location": "query", "type": "string", "required": false, "description": "Partial game-name search.", "example": "PUBG", "options": [] }, { "name": "category", "location": "query", "type": "string", "required": false, "description": "Partial category-name search.", "example": "Global", "options": [] }, { "name": "game_id", "location": "query", "type": "integer", "required": false, "description": "Game ID.", "example": 1, "options": [] }, { "name": "category_id", "location": "query", "type": "integer", "required": false, "description": "Category ID.", "example": 10, "options": [] }, { "name": "q", "location": "query", "type": "string", "required": false, "description": "Search by product name.", "example": "60 UC", "options": [] }, { "name": "page", "location": "query", "type": "integer", "required": false, "description": "Page number.", "example": 1, "options": [] }, { "name": "per_page", "location": "query", "type": "integer", "required": false, "description": "Page size. Current maximum: 100.", "example": 50, "options": [] } ], "request_example": null, "response_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": "Player ID", "required": true } ], "supports_player_validation": true } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "VALIDATION_ERROR", "status": 422, "description": "A filter or pagination parameter is invalid." } ], "url": "https://gmx.az/api/v1/products", "curl": "curl -s -X GET 'https://gmx.az/api/v1/products?type=topup&game=PUBG&category=Global&game_id=1&category_id=10&q=60+UC&page=1&per_page=50' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY'" }, { "id": "validate-player", "group": "Validation", "method": "POST", "path": "/validate-player", "title": "Validate player", "summary": "Validates the player ID and, when required, the server ID.", "description": "If validation is optional, validation_optional=true may be returned and the order can continue.", "success_status": 200, "parameters": [ { "name": "product_id", "location": "body", "type": "integer", "required": true, "description": "Top-up product ID.", "example": 91, "options": [] }, { "name": "player_id", "location": "body", "type": "string", "required": true, "description": "Player ID.", "example": "51515969536", "options": [] }, { "name": "server_id", "location": "body", "type": "string", "required": false, "description": "Server or zone ID when required.", "example": "1234", "options": [] }, { "name": "input_2...input_8", "location": "body", "type": "string", "required": false, "description": "Additional input_2...input_8 values matching the product fields list.", "example": "Additional mapped values", "options": [] } ], "request_example": { "product_id": 91, "player_id": "51515969536", "server_id": "1234", "input_3": "CharacterName" }, "response_example": { "success": true, "data": { "nickname": "PlayerOne", "player_name": "PlayerOne", "region": "TR", "country": "TR", "server": "1234", "nickname_verified": true, "validation_optional": false } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "VALIDATION_ERROR", "status": 422, "description": "A required body field is missing or invalid." }, { "code": "PRODUCT_NOT_FOUND", "status": 404, "description": "The top-up product was not found or is inactive." }, { "code": "PLAYER_NOT_FOUND", "status": 404, "description": "The player could not be validated and validation is required." } ], "url": "https://gmx.az/api/v1/validate-player", "curl": "curl -s -X POST 'https://gmx.az/api/v1/validate-player' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\n \"product_id\": 91,\n \"player_id\": \"51515969536\",\n \"server_id\": \"1234\",\n \"input_3\": \"CharacterName\"\n}'" }, { "id": "place-order", "group": "Orders", "method": "POST", "path": "/order", "title": "Create order", "summary": "Creates a voucher or top-up order and deducts the amount from the customer balance.", "description": "This endpoint creates a real financial operation. Use X-Idempotency-Key to protect retries. Top-up quantity is always 1.", "success_status": 200, "side_effect": true, "warning": "This request creates a real order and deducts the amount from the balance.", "parameters": [ { "name": "X-Idempotency-Key", "location": "header", "type": "string", "required": false, "description": "Unique retry key. Required for money-changing operations; on POST /order client_order_id can be used as the fallback key.", "example": "550e8400-e29b-41d4-a716-446655440000", "options": [] }, { "name": "product_id", "location": "body", "type": "integer", "required": true, "description": "Active product ID.", "example": 91, "options": [] }, { "name": "qty", "location": "body", "type": "integer", "required": false, "description": "Voucher maximum: 500; top-up maximum: 1.", "example": 1, "options": [] }, { "name": "player_id", "location": "body", "type": "string", "required": false, "description": "Required for top-up products.", "example": "51515969536", "options": [] }, { "name": "server_id", "location": "body", "type": "string", "required": false, "description": "Server or zone ID when required.", "example": "1234", "options": [] }, { "name": "input_2...input_8", "location": "body", "type": "string", "required": false, "description": "Additional input_2...input_8 values matching the product fields list.", "example": "Additional mapped values", "options": [] }, { "name": "client_order_id", "location": "body", "type": "string", "required": false, "description": "Your own order reference. If X-Idempotency-Key is omitted on POST /order, this value also becomes the retry key.", "example": "client-order-10001", "options": [] }, { "name": "callback_url", "location": "body", "type": "string", "required": false, "description": "Secure HTTPS callback URL.", "example": "https://customer.example/webhooks/bot-manager", "options": [] }, { "name": "callback_mode", "location": "body", "type": "string", "required": false, "description": "Callback format. Current default: legacy.", "example": "legacy", "options": [ "legacy", "events" ] } ], "request_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" }, "response_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 } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "VALIDATION_ERROR", "status": 422, "description": "One of the request-body fields is invalid." }, { "code": "PRODUCT_NOT_FOUND", "status": 404, "description": "The product was not found or is inactive." }, { "code": "INVALID_QUANTITY", "status": 422, "description": "The quantity exceeds the product or API limit." }, { "code": "PLAYER_ID_REQUIRED", "status": 422, "description": "player_id is required for top-up orders." }, { "code": "SERVER_ID_REQUIRED", "status": 422, "description": "server_id is required for this product." }, { "code": "PLAYER_NOT_FOUND", "status": 404, "description": "Required player validation failed." }, { "code": "INSUFFICIENT_FUNDS", "status": 400, "description": "The balance is insufficient for this order." }, { "code": "OUT_OF_STOCK", "status": 409, "description": "The order could not be created or sent for processing." }, { "code": "IDEMPOTENCY_KEY_REQUIRED", "status": 422, "description": "A stable idempotency key is required for this operation." }, { "code": "IDEMPOTENCY_KEY_INVALID", "status": 422, "description": "The idempotency key is invalid or longer than 128 characters." }, { "code": "IDEMPOTENCY_CONFLICT", "status": 409, "description": "The same idempotency key was reused with a different payload." }, { "code": "CLIENT_ORDER_ID_CONFLICT", "status": 409, "description": "The same client_order_id is already assigned to another order." }, { "code": "SECURITY_ERROR", "status": 400, "description": "The callback URL does not meet the security requirements." }, { "code": "ORDER_FAILED", "status": 409, "description": "The order could not be created or sent for processing." } ], "url": "https://gmx.az/api/v1/order", "curl": "curl -s -X POST 'https://gmx.az/api/v1/order' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY' \\\n -H 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \\\n -H 'Content-Type: application/json' \\\n --data '{\n \"product_id\": 91,\n \"qty\": 1,\n \"player_id\": \"51515969536\",\n \"server_id\": \"1234\",\n \"input_3\": \"CharacterName\",\n \"client_order_id\": \"client-order-10001\",\n \"callback_url\": \"https://customer.example/webhooks/bot-manager\",\n \"callback_mode\": \"events\"\n}'" }, { "id": "qr-login-status", "group": "Orders", "method": "GET", "path": "/order/{id}/qr-login/status", "title": "QR Login status", "summary": "Get the live QR Login fulfillment state for an owned order.", "description": "Returns QR availability, version, worker state, expiry and the actions currently allowed.", "success_status": 200, "parameters": [ { "name": "id", "location": "path", "type": "string", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "example": "8821", "options": [] } ], "request_example": null, "response_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 } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "ORDER_NOT_FOUND", "status": 404, "description": "The order was not found or belongs to another API user." } ], "url": "https://gmx.az/api/v1/order/{id}/qr-login/status", "curl": "curl -s -X GET 'https://gmx.az/api/v1/order/8821/qr-login/status' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY'" }, { "id": "qr-login-preview", "group": "Orders", "method": "GET", "path": "/order/{id}/qr-login/preview", "title": "QR Login preview", "summary": "Fetch the currently active QR image.", "description": "Returns a private JPEG only while the QR is active. Authenticate this request with the same API key. Browser tags cannot attach X-API-KEY, so fetch the image as an authenticated binary/blob request and display the returned object URL.", "success_status": 200, "parameters": [ { "name": "id", "location": "path", "type": "string", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "example": "8821", "options": [] }, { "name": "v", "location": "query", "type": "integer", "required": false, "description": "Optional QR version cache-buster.", "example": 1, "options": [] } ], "request_example": null, "response_example": "Binary image/jpeg response.", "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "ORDER_NOT_FOUND", "status": 404, "description": "The order was not found or belongs to another API user." } ], "url": "https://gmx.az/api/v1/order/{id}/qr-login/preview", "curl": "curl -s -X GET 'https://gmx.az/api/v1/order/8821/qr-login/preview?v=1' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY'" }, { "id": "qr-login-scanned", "group": "Orders", "method": "POST", "path": "/order/{id}/qr-login/scanned", "title": "Confirm QR scanned", "summary": "Tell the assigned worker that the customer scanned the active QR.", "description": "Use only after the customer actually scans the QR. This does not itself complete the order.", "success_status": 200, "parameters": [ { "name": "id", "location": "path", "type": "string", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "example": "8821", "options": [] } ], "request_example": {}, "response_example": { "success": true, "data": { "session_status": "customer_scanned", "has_qr": true } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "ORDER_NOT_FOUND", "status": 404, "description": "The order was not found or belongs to another API user." } ], "url": "https://gmx.az/api/v1/order/{id}/qr-login/scanned", "curl": "curl -s -X POST 'https://gmx.az/api/v1/order/8821/qr-login/scanned' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{}'" }, { "id": "qr-login-new-qr", "group": "Orders", "method": "POST", "path": "/order/{id}/qr-login/new-qr", "title": "Request a new QR", "summary": "Invalidate the current QR and request a replacement.", "description": "Use when the displayed QR expired or cannot be scanned.", "success_status": 200, "parameters": [ { "name": "id", "location": "path", "type": "string", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "example": "8821", "options": [] } ], "request_example": {}, "response_example": { "success": true, "data": { "session_status": "awaiting_new_qr", "has_qr": false } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "ORDER_NOT_FOUND", "status": 404, "description": "The order was not found or belongs to another API user." } ], "url": "https://gmx.az/api/v1/order/{id}/qr-login/new-qr", "curl": "curl -s -X POST 'https://gmx.az/api/v1/order/8821/qr-login/new-qr' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{}'" }, { "id": "qr-login-otp", "group": "Orders", "method": "POST", "path": "/order/{id}/qr-login/otp", "title": "Submit QR Login OTP", "summary": "Send the one-time code requested by the assigned worker.", "description": "OTP is accepted only during awaiting_otp and is forwarded to the assigned worker without being stored.", "success_status": 200, "parameters": [ { "name": "id", "location": "path", "type": "string", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "example": "8821", "options": [] }, { "name": "otp", "location": "body", "type": "string", "required": true, "description": "4-10 digit one-time code.", "example": "123456", "options": [] } ], "request_example": { "otp": "123456" }, "response_example": { "success": true, "data": { "session_status": "customer_scanned", "has_qr": true } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "VALIDATION_ERROR", "status": 422, "description": "OTP must contain 4-10 digits." }, { "code": "ORDER_NOT_FOUND", "status": 404, "description": "The order was not found or belongs to another API user." } ], "url": "https://gmx.az/api/v1/order/{id}/qr-login/otp", "curl": "curl -s -X POST 'https://gmx.az/api/v1/order/8821/qr-login/otp' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\n \"otp\": \"123456\"\n}'" }, { "id": "order-status", "group": "Orders", "method": "GET", "path": "/order/{id}", "title": "Get order status", "summary": "Finds an order by local ID, UUID, or client_order_id.", "description": "Returns the current order status and voucher delivery codes when available.", "success_status": 200, "parameters": [ { "name": "id", "location": "path", "type": "string", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "example": "8821", "options": [] } ], "request_example": null, "response_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" } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "ORDER_NOT_FOUND", "status": 404, "description": "The order was not found or belongs to another API user." } ], "url": "https://gmx.az/api/v1/order/{id}", "curl": "curl -s -X GET 'https://gmx.az/api/v1/order/8821' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY'" }, { "id": "order-status-legacy", "group": "Orders", "method": "GET", "path": "/order-status/{id}", "title": "Legacy status endpoint", "summary": "A compatibility alias for /order/{id}.", "description": "Use /order/{id} for new integrations. The response and behavior are identical.", "success_status": 200, "parameters": [ { "name": "id", "location": "path", "type": "string", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "example": "8821", "options": [] } ], "request_example": null, "response_example": { "success": true, "data": { "order_id": 8821, "status": "COMPLETED", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "ORDER_NOT_FOUND", "status": 404, "description": "The order was not found." } ], "url": "https://gmx.az/api/v1/order-status/{id}", "curl": "curl -s -X GET 'https://gmx.az/api/v1/order-status/8821' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY'" }, { "id": "orders", "group": "Orders", "method": "GET", "path": "/orders", "title": "Get order history", "summary": "Returns orders for the current API user with filters and pagination.", "description": "Customers can only access their own orders. per_page is limited to 100.", "success_status": 200, "parameters": [ { "name": "status", "location": "query", "type": "string", "required": false, "description": "Order status.", "example": "completed", "options": [ "pending", "processing", "completed", "failed", "canceled", "cancelled", "refunded" ] }, { "name": "type", "location": "query", "type": "string", "required": false, "description": "Product type.", "example": "voucher", "options": [ "voucher", "topup" ] }, { "name": "page", "location": "query", "type": "integer", "required": false, "description": "Page number.", "example": 1, "options": [] }, { "name": "per_page", "location": "query", "type": "integer", "required": false, "description": "Page size. Maximum 100.", "example": 50, "options": [] } ], "request_example": null, "response_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 } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "VALIDATION_ERROR", "status": 422, "description": "A filter or pagination parameter is invalid." } ], "url": "https://gmx.az/api/v1/orders", "curl": "curl -s -X GET 'https://gmx.az/api/v1/orders?status=completed&type=voucher&page=1&per_page=50' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY'" }, { "id": "redeem-check", "group": "Redeem check", "method": "POST", "path": "/redeem-check", "title": "Check redeem data", "summary": "Checks the code and charges the amount that matches the result.", "description": "This endpoint creates a real balance operation. A maximum amount can be reserved and the unused portion refunded.", "success_status": 200, "side_effect": true, "warning": "This request performs a real code check and may charge the balance.", "parameters": [ { "name": "X-Idempotency-Key", "location": "header", "type": "string", "required": true, "description": "Required unique retry key. Reusing it with the same code returns the original result without charging or checking upstream again.", "example": "4d83ae61-b98b-4d4d-bf11-58f3bc028a71", "options": [] }, { "name": "code", "location": "body", "type": "string", "required": true, "description": "Code to check. 6-160 characters.", "example": "REDEEM-CODE-EXAMPLE", "options": [] } ], "request_example": { "code": "REDEEM-CODE-EXAMPLE" }, "response_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 } }, "errors": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "IDEMPOTENCY_KEY_REQUIRED", "status": 422, "description": "A stable idempotency key is required for this operation." }, { "code": "IDEMPOTENCY_KEY_INVALID", "status": 422, "description": "The idempotency key is invalid or longer than 128 characters." }, { "code": "IDEMPOTENCY_CONFLICT", "status": 409, "description": "The same idempotency key was reused with a different payload." }, { "code": "VALIDATION_ERROR", "status": 422, "description": "The code is missing or has an invalid length." }, { "code": "REDEEM_CHECK_FAILED", "status": 422, "description": "The redeem check failed, the service is disabled, or the balance is insufficient." } ], "url": "https://gmx.az/api/v1/redeem-check", "curl": "curl -s -X POST 'https://gmx.az/api/v1/redeem-check' \\\n -H 'Accept: application/json' \\\n -H 'X-API-KEY: YOUR_API_KEY' \\\n -H 'X-Idempotency-Key: 4d83ae61-b98b-4d4d-bf11-58f3bc028a71' \\\n -H 'Content-Type: application/json' \\\n --data '{\n \"code\": \"REDEEM-CODE-EXAMPLE\"\n}'" } ], "status_lifecycle": [ { "status": "PENDING", "terminal": false, "description": "The order was created and is waiting for processing." }, { "status": "PROCESSING", "terminal": false, "description": "The order is being processed." }, { "status": "COMPLETED", "terminal": true, "description": "The order was completed successfully. Voucher delivery codes are returned when applicable." }, { "status": "FAILED", "terminal": true, "description": "The order failed or was cancelled." }, { "status": "CANCELED", "terminal": true, "description": "The order was cancelled." }, { "status": "REFUNDED", "terminal": true, "description": "The amount was refunded to the balance." } ], "webhook": { "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": "Recommended: sha256=HMAC_SHA256(timestamp + \".\" + event_id + \".\" + raw_json_body, webhook_secret). Use the timestamp and event-id headers shown above." }, { "name": "X-EPINBULK-Signature-Version", "description": "2" }, { "name": "X-EPINBULK-Signature", "description": "sha256=HMAC_SHA256(raw_json_body, webhook_secret)" }, { "name": "X-EPINBULK-Timestamp", "description": "ISO-8601 webhook delivery timestamp. Verify freshness when validating the V2 signature." }, { "name": "X-EPINBULK-Event-Id", "description": "Unique UUID for the callback attempt." }, { "name": "X-EPINBULK-Event", "description": "Actual event name: order.status_changed or qr_login.*" } ], "requirements": [ "Only HTTPS URLs are accepted.", "Only port 443 is accepted.", "Private, reserved, and localhost addresses are blocked.", "Credentials in the URL are not accepted.", "Redirects are not followed.", "The receiving server must return a 2xx response." ], "retry_schedule": [ "1 → 1 minute", "2 → 5 minutes", "3 → 15 minutes", "4-6 → 60 minutes", "7-20 → 6 hours" ], "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": "Order completed successfully.", "timestamp": "2026-07-25T13:30:10+04:00" } }, "error_catalog": [ { "code": "API_DISABLED", "status": 503, "description": "Public API has been disabled by the administrator." }, { "code": "API_KEY_MISSING", "status": 401, "description": "The X-API-KEY header was not sent." }, { "code": "CLIENT_ORDER_ID_CONFLICT", "status": 409, "description": "The same client_order_id is already assigned to another order." }, { "code": "GAME_NOT_FOUND", "status": 404, "description": "The game was not found or is inactive." }, { "code": "IDEMPOTENCY_CONFLICT", "status": 409, "description": "The same idempotency key was reused with a different payload." }, { "code": "IDEMPOTENCY_KEY_INVALID", "status": 422, "description": "The idempotency key is invalid or longer than 128 characters." }, { "code": "IDEMPOTENCY_KEY_REQUIRED", "status": 422, "description": "A stable idempotency key is required for this operation." }, { "code": "INSUFFICIENT_FUNDS", "status": 400, "description": "The balance is insufficient for this order." }, { "code": "INVALID_API_KEY", "status": 401, "description": "The API key is invalid or disabled, or the customer is inactive." }, { "code": "INVALID_QUANTITY", "status": 422, "description": "The quantity exceeds the product or API limit." }, { "code": "IP_NOT_ALLOWED", "status": 403, "description": "The requesting IP address is not allowed." }, { "code": "ORDER_FAILED", "status": 409, "description": "The order could not be created or sent for processing." }, { "code": "ORDER_NOT_FOUND", "status": 404, "description": "The order was not found or belongs to another API user." }, { "code": "OUT_OF_STOCK", "status": 409, "description": "The order could not be created or sent for processing." }, { "code": "PLAYER_ID_REQUIRED", "status": 422, "description": "player_id is required for top-up orders." }, { "code": "PLAYER_NOT_FOUND", "status": 404, "description": "The player could not be validated and validation is required." }, { "code": "PRODUCT_NOT_FOUND", "status": 404, "description": "The top-up product was not found or is inactive." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "description": "The per-minute request limit has been exceeded." }, { "code": "REDEEM_CHECK_FAILED", "status": 422, "description": "The redeem check failed, the service is disabled, or the balance is insufficient." }, { "code": "SECURITY_ERROR", "status": 400, "description": "The callback URL does not meet the security requirements." }, { "code": "SERVER_ID_REQUIRED", "status": 422, "description": "server_id is required for this product." }, { "code": "VALIDATION_ERROR", "status": 422, "description": "The type or q parameter is invalid." } ], "common_error_shape": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The product_id field is required.", "details": { "max": 1 } } }, "changelog": [ { "date": "2026-07-25", "title": "Live request workspace", "description": "Live request, response, and signature tools were added." }, { "date": "2026-07-25", "title": "Security hardening", "description": "Callback and idempotency protections were strengthened." } ] } }