GMXAZ Bot Public API kolleksiyası

Giriş

API kataloqa baxış, oyunçu yoxlaması, vauçer və top-up sifarişləri, sifariş izləmə, redeem yoxlamaları və imzalanmış müştəri webhook-larını təmin edir. Provayder məlumatları daxili məlumatdır və müştəriyə təqdim olunan API cavablarına və ya webhook məlumatlarına heç vaxt daxil edilmir.

Autentifikasiya və təhlükəsizlik

Hər qorunan sorğuda şəxsi API açarınızı X-API-KEY başlığında göndərin. Açarı yalnız backend-də saxlayın. Onu brauzer kodunda, Mini App-lərdə, mobil paketlərdə və ya açıq repozitoriyalarda heç vaxt paylaşmayın.

X-API-KEY: YOUR_API_KEY
Accept: application/json

İdempotentlik

Sifariş yaradarkən X-Idempotency-Key başlığında unikal UUID göndərin. Eyni açar və eyni məlumatlarla təkrar sorğu mövcud sifarişi qaytarır. Eyni açarın fərqli məlumatlarla yenidən istifadəsi IDEMPOTENCY_CONFLICT xətası qaytarır. Hazır Postman kolleksiyasında təkrar cəhd zamanı yaradılmış əməliyyat açarını dəyişməyin; yalnız yeni maliyyə əməliyyatına başlayanda onu təmizləyin.

X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Sifariş axını

1. Oyunları, kateqoriyaları və məhsulları yükləyin. Cari qiyməti, stok vəziyyətini, dəstəklənən sahələri və doğrulama tələbini yoxlayın.
2. supports_player_validation true olduqda və ya məhsul doğrulama tələb etdikdə oyunçunu yoxlayın.
3. UUID idempotentlik açarı ilə sifariş yaradın və tələb olunduqda callback_url ilə callback_mode göndərin.
4. Yekun status əldə edilənədək sifarişi GET /order/{id}, GET /orders və ya imzalanmış webhook hadisələri vasitəsilə izləyin.

Webhook-lar

API sifarişində callback_url göstərildikdə platforma həmin ünvana imzalanmış JSON yeniləmələri göndərir. Webhook-larda yalnız sifariş, məhsul, oyunçu, qiymət, status, çatdırılma və müştəri əməliyyatı sahələri olur. Yuxarı səviyyəli provayder adları, URL-lər, sifariş ID-ləri və xam cavablar heç vaxt açıqlanmır.

Callback rejimləri

Webhook başlıqları

Callback URL tələbləri

• Yalnız HTTPS URL qəbul edilir.
• Yalnız 443 portu qəbul edilir.
• Şəxsi və yerli ünvanlar bloklanır.
• URL daxilində giriş məlumatı qəbul edilmir.
• Yönləndirmələr izlənmir.
• Server 2xx cavab qaytarmalıdır.

Təkrar cəhd cədvəli

1 → 1 dəqiqə → 2 → 5 dəqiqə → 3 → 15 dəqiqə → 4-6 → 60 dəqiqə → 7-20 → 6 saat · Maksimum 20 göndərmə cəhdi.

{
    "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"
}

{
    "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": "Sifariş uğurla tamamlandı.",
    "timestamp": "2026-07-25T13:30:10+04:00"
}

İmzanın yoxlanılması

API girişi ilə birlikdə verilmiş webhook_secret məlumatından istifadə edərək sorğunun dəyişdirilməmiş xam JSON gövdəsi üzərində HMAC SHA-256 hesablayın. Nəticəni bu sənəddə göstərilən imza başlığı ilə zamanlama hücumlarına davamlı üsulla müqayisə edin.

<?php
$secret = 'YOUR_WEBHOOK_SECRET';
$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_GAMEX_SIGNATURE'] ?? '';
$computed = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($computed, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

http_response_code(204);

Statusların həyat dövrü

Xəta kodları

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "product_id sahəsi məcburidir.",
        "details": {
            "max": 1
        }
    }
}

Limitlər və təkrar cəhd qaydaları

Təyin edilmiş dəqiqəlik sorğu limitinə əməl edin. 429 və müvəqqəti 5xx cavablarını eksponensial gecikmə ilə təkrar yoxlayın. Eyni sifariş sorğusunu təkrar göndərərkən yeni idempotentlik açarı yaratmayın.

Yükləmələr və Postman faylları