API sənədləri

Başlanğıc

API bayi hesabınızın adından işləyir: gördüyünüz qiymətlər sizin bayi qiymətlərinizdir, sifarişlər sizin balansınızdan ödənilir. Açar hesabınıza bağlıdır — onu paylaşmayın, sızdığını düşünürsünüzsə dərhal bizə yazın.

1. API açarı alın

Bayi hesabınız təsdiqləndikdən sonra panelinizdən açar yaradılır. Açar bir dəfə göstərilir, saxlanmır — itirsəniz yenisini yaradın, köhnəsi dərhal etibarsız olur.

2. Hər sorğuya açarı əlavə edin

curl https://ztopup.store/api/v1/me \
  -H "X-API-Key: sizin_açarınız" \
  -H "Accept: application/json"

3. Balansı doldurun

Sifariş yaratmaq üçün balansınız kifayət etməlidir — API balansı özü doldurmur. Balans panelin Balansım bölməsindən artırılır; kart məlumatları orada göstərilir.

4. İlk sifariş

Ardıcıllıq həmişə eynidir: kataloqdan paket seçin, oyunçu hesabını yoxlayın, sifarişi yaradın, nəticəni webhook ilə və ya sorğu ilə izləyin.

Ümumi qaydalar

Ünvan və format

Bütün endpointlər https://ztopup.store/api/v1 altındadır və yalnız HTTPS qəbul edir. Sorğu və cavab gövdəsi JSON, kodlaşdırma UTF-8-dir.

Cavab qabığı

Hər cavab ok sahəsi ilə gəlir. Uğurlu cavabda məlumat data içindədir, xətada isə error.

{
  "ok": true,
  "data": { }
}

Məbləğlər

Bütün məbləğlər AZN və iki onluq işarə ilə, mətn kimi göndərilir ("1.91"). Sürüşən nöqtə xətası olmasın deyə rəqəm tipi işlədilmir.

Tarixlər

ISO 8601, Bakı vaxtı ilə: 2026-09-21T14:05:31+04:00.

Idempotensiya

Sifariş yaradan sorğuda Idempotency-Key başlığı məcburidir. Eyni açarla təkrar göndərilən sorğu yeni sifariş yaratmır — ilk sifarişin cavabını qaytarır. Şəbəkə kəsiləndə sorğunu təhlükəsiz təkrarlamağın yolu budur. Açar 24 saat saxlanır və hesabınıza aiddir.

Eyni açarla fərqli gövdə göndərsəniz sorğu 409 qaytarır — səhvən eyni açarın iki ayrı sifarişə yapışdırılması beləcə tutulur.

Səhifələmə

Siyahı qaytaran endpointlər page və per_page (ən çox 100, standart 25) qəbul edir. Cavabda meta olur.

"meta": {
  "page": 1,
  "per_page": 25,
  "total": 134,
  "last_page": 6
}

Hesab və balans

{
  "ok": true,
  "data": {
    "id": 42,
    "name": "Nümunə MMC",
    "dealer_tier": "Gümüş",
    "balance": "184.50",
    "currency": "AZN"
  }
}

{
  "ok": true,
  "data": { "balance": "184.50", "currency": "AZN" }
}

Kataloq

Kataloq iki səviyyəlidir: məhsul (oyun və region, məsələn «Free Fire Almaz — Azərbaycan») və onun altındakı paketlər. Sifariş həmişə paketə verilir.

{
  "ok": true,
  "data": [
    {
      "id": 1,
      "slug": "free-fire-almaz-azerbaycan",
      "name": "Free Fire Almaz — Azərbaycan",
      "category": "Free Fire",
      "region": "AZ",
      "requires_player_id": true,
      "player_id_label": "Player ID"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 18, "last_page": 1 }
}

{
  "ok": true,
  "data": [
    {
      "id": 1,
      "name": "110 Almaz",
      "price": "1.64",
      "list_price": "1.91",
      "currency": "AZN",
      "available": true,
      "stock": null
    }
  ]
}

stock dəyəri null olanda limit yoxdur. available false olan paketə sifariş verilə bilməz — paketin özü bağlıdır və ya təchizat müvəqqəti dayanıb.

Oyunçu yoxlaması

requires_player_id olan məhsullarda sifarişdən əvvəl oyunçu hesabı yoxlanmalıdır. Yoxlama sizə oyunçunun adını qaytarır və player_token verir; sifariş həmin token olmadan qəbul edilmir.

Səbəbi sadədir: səhv Player ID-yə yüklənmiş almaz geri qayıtmır. Token 5 dəqiqə etibarlıdır və yalnız yoxlandığı paket + Player ID cütü üçün işləyir.

curl -X POST https://ztopup.store/api/v1/players/validate \
  -H "X-API-Key: sizin_açarınız" \
  -H "Content-Type: application/json" \
  -d '{
    "package_id": 1,
    "player_id": "5012345678"
  }'

{
  "ok": true,
  "data": {
    "valid": true,
    "player_name": "OyuncuAZ",
    "player_token": "pv_9f2c1a...",
    "expires_at": "2026-09-21T14:10:31+04:00"
  }
}

Bəzi oyunlarda ad sorğulanmır; belə hallarda player_name null gəlir, token yenə verilir. Yanlış ID-də cavab 422 olur və sifariş yaradılmır — pul tutulmur.

Sifarişlər

curl -X POST https://ztopup.store/api/v1/orders \
  -H "X-API-Key: sizin_açarınız" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1f0c94-2d3a-4e55-9f10-8c2b6de41a77" \
  -d '{
    "package_id": 1,
    "quantity": 1,
    "player_id": "5012345678",
    "player_token": "pv_9f2c1a...",
    "reference": "sizin-sifaris-1042"
  }'

{
  "ok": true,
  "data": {
    "id": "ord_8412",
    "order_no": "GX260921ABCD",
    "status": "paid",
    "reference": "sizin-sifaris-1042",
    "package": { "id": 1, "name": "110 Almaz" },
    "player_id": "5012345678",
    "player_name": "OyuncuAZ",
    "quantity": 1,
    "unit_price": "1.64",
    "total": "1.64",
    "currency": "AZN",
    "balance_after": "182.86",
    "items": [
      { "id": "itm_9103", "fulfillment_status": "pending", "delivered_at": null }
    ],
    "created_at": "2026-09-21T14:05:31+04:00"
  }
}

reference sizin öz sifariş nömrənizdir — istəyə bağlıdır, cavablarda və webhook-da geri qaytarılır, hesablaşmanı asanlaşdırır. Idempotensiya üçün isə reference yox, Idempotency-Key istifadə olunur.

Webhook

Sifariş statusu dəyişəndə göstərdiyiniz ünvana POST göndərilir. Ünvanı və imza açarını paneldən təyin edirsiniz.

{
  "event": "order.completed",
  "sent_at": "2026-09-21T14:05:47+04:00",
  "data": {
    "id": "ord_8412",
    "order_no": "GX260921ABCD",
    "reference": "sizin-sifaris-1042",
    "status": "completed",
    "items": [
      { "id": "itm_9103", "fulfillment_status": "delivered", "delivered_at": "2026-09-21T14:05:47+04:00" }
    ]
  }
}

Hadisələr

İmzanı yoxlayın

Hər sorğuda X-ZTopup-Signature başlığı olur: gövdənin imza açarınızla hesablanmış HMAC-SHA256 dəyəri (hex). Gövdəni JSON-a çevirmədən əvvəl, xam haldaca yoxlayın — yenidən kodlaşdırma imzanı pozur.

$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $raw, $secret);

if (! hash_equals($expected, $_SERVER['HTTP_X_ZTOPUP_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Sorğu limitləri

Limit aşılanda cavab 429 olur və Retry-After başlığında neçə saniyə gözləməli olduğunuz yazılır. Qalan haqqınız hər cavabda X-RateLimit-Remaining ilə gəlir.

Statuslar və xətalar

Sifariş statusu

Sətir statusu

HTTP kodları

Xəta gövdəsi

{
  "ok": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Balans kifayət etmir.",
    "details": { "required": "1.64", "balance": "0.80" }
  }
}

code sabitdir və proqramla yoxlanmaq üçündür; message insan üçündür və dəyişə bilər — şərtlərinizi mesaja görə yazmayın.