Dokumentasi API reseller

URL asas dan protokol

Setiap laluan dalam rujukan ini adalah relatif kepada URL asas di bawah. Permintaan dan respons menggunakan JSON melalui HTTPS. Amaun dihantar sebagai string supaya tiada ralat pembundaran float, dan semua cap masa dalam UTC mengikut ISO 8601.

https://shop2topup.com/api/endpoints/v1

Pengesahan

Setiap permintaan membawa satu header. Pasangan kunci dikeluarkan dari halaman Akses API dalam panel reseller anda dan boleh dihadkan kepada senarai IP yang dibenarkan. Panggilan dari alamat lain ditolak dengan IP_NOT_ALLOWED sebelum sampai ke mana-mana logik perniagaan.

Authorization: Bearer <keyId>.<secret>

Panggilan pertama

Tiada apa yang perlu dipasang. Masukkan kunci anda sendiri dan permintaan ini akan memulangkan data katalog secara langsung.

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Konvensyen respons

• Setiap respons mengandungi medan boolean success. Satu syarat sahaja sudah cukup untuk memisahkan laluan berjaya daripada semua kegagalan.
• Kegagalan memulangkan objek error yang mengandungi kod stabil, mesej yang mudah dibaca dan butiran pilihan. Bina logik anda berdasarkan kod, bukan mesej.
• Nilai wang sentiasa dalam bentuk rentetan perpuluhan seperti "0.950000" dalam USD. Jangan tukar kepada float binari sebelum anda membandingkan atau menjumlahkannya.
• Endpoint senarai memulangkan objek pagination yang mengandungi page, limit, total dan total_pages.
• Pembuatan pesanan bersifat idempoten berdasarkan UUID order_id yang anda berikan, jadi cubaan semula tidak akan mengenakan caj dua kali.

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "action": "FIX_INPUT",
    "retryable": false,
    "retry_after": null,
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

Bahagian rujukan

Had kadar

Had dikenakan bagi setiap akaun berdasarkan tempoh masa yang dikira secara berterusan. Endpoint katalog, pesanan dan akaun menyertakan X-RateLimit-Limit, X-RateLimit-Remaining dan X-RateLimit-Reset. Panggilan yang melebihi had menerima respons 429 dengan header Retry-After. Pengesahan pemain pula menggunakan kuota semakan pemain harian anda: responsnya tidak menyertakan header X-RateLimit, dan maklumat kuota diberikan dalam badan respons 429.

Webhook

Keputusan pesanan dihantar ke endpoint HTTPS yang anda daftarkan, ditandatangani dengan HMAC-SHA256 ke atas body mentah. Senarai event, senarai header, struktur payload dan contoh kod pengesahan boleh didapati di halaman gambaran keseluruhan API.