Asosiy qismga o'tish

API metodlari · 8-bob

Buyurtmalar

Buyurtma bitta mijoz uchun bitta taklifni sotib oladi va balansingizdan to'lanadi. Bu bo'limda buyurtmalarni xavfsiz yaratish, ularning holatini kuzatish va natijani o'qish tushuntirilgan.

2 daqiqa o'qish

Buyurtma yaratish

POST/orders

Maydon Tavsif
transaction_id Majburiy. Shu buyurtma uchun o'zingizning noyob ID ingiz: harflar, raqamlar va . _ : -, 100 belgigacha.
offer_id Majburiy. Taklif id si.
quantity Ixtiyoriy, 1–100, sukut bo'yicha 1.
fields Taklif talab qiladigan mijoz maydonlari, masalan {"player_id": "5123456789"}.
max_price Ixtiyoriy. Siz rozi bo'ladigan eng yuqori umumiy summa, masalan "10.00". Umumiy summa bundan yuqori bo'lsa, PRICE_CHANGED olasiz va hech narsa yechilmaydi.
curl https://partner.goxost.net/api/v1/orders \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "shop-88121",
    "offer_id": 1042,
    "quantity": 1,
    "fields": { "player_id": "5123456789" },
    "max_price": "10.00"
  }'

Buyurtma qabul qilinganda (HTTP 201) balansdan pul yechiladi:

{
  "data": {
    "transaction_id": "shop-88121",
    "order_id": "P-000123",
    "status": "completed",
    "offer_id": 1042,
    "quantity": 1,
    "fields": { "player_id": "5123456789" },
    "unit_price": "9.63",
    "total": "9.63",
    "currency": "USD",
    "delivered": [],
    "error": null,
    "refunded": false,
    "sandbox": false,
    "created_at": "2026-11-15T10:02:11Z",
    "updated_at": "2026-11-15T10:02:14Z"
  }
}

transaction_id bilan xavfsiz qayta yuborish

transaction_id — takrorlanishdan himoya kaliti. So'rov javobsiz qolsa yoki serveringiz qayta ishga tushsa, xuddi shu so'rovni shu transaction_id bilan qayta yuboring:

  • mavjud buyurtma HTTP 200 bilan qaytadi — pul hech qachon ikki marta yechilmaydi;
  • shu transaction_id boshqa taklif yoki maydonlar bilan kelsa, 409 TRANSACTION_ID_CONFLICT qaytadi.
Maslahat

transaction_id sifatida o'zingizning buyurtma raqamingizni ishlating (masalan shop-88121). Shunda har qanday tarmoq xatosidan keyin qayta yuborish doim xavfsiz bo'ladi.

Buyurtma holatlari

Holat Ma'nosi
pending Qabul qilingan va yuborilishini kutmoqda.
processing Yetkazilmoqda.
completed Bajarildi. code takliflarida kodlar delivered ichida bo'ladi.
failed Yetkazilmadi. Sababi error da yozilgan, pul balansingizga qaytgan (refunded: true).

Ko'pchilik buyurtmalar bir necha soniyada bajariladi. Yetkazish sekin bo'lsa, buyurtma pending yoki processing holatida qoladi va biz siz uchun qayta urinib turamiz. Natijani webhooklar yoki GET /orders/{transaction_id} orqali kuzating.

Buyurtma maydonlari

Maydon Tavsif
transaction_id So'rovdagi sizning ID ingiz.
order_id Bizning buyurtma raqamimiz. Yordam kerak bo'lsa, uni Yordam markazidagi murojaatda koʻrsating.
unit_price, total Bir dona narxi va yechilgan summa.
delivered code takliflari bajarilganda: { "type": "code", "value": "…", "pin": "…" } ro'yxati; pin null bo'lishi mumkin. Aks holda bo'sh.
error null yoki buyurtma bajarilmaganda { "code": "…", "message": "…" }.
refunded Summa balansingizga qaytarilganda true.
sandbox Test kaliti bilan yaratilgan test buyurtmasida true (uning order_id qiymati S- bilan boshlanadi), live buyurtmalarda false. Sandbox bobiga qarang.

Bajarilgan vaucher buyurtmasi misoli:

"delivered": [{ "type": "code", "value": "ABCD-EFGH-1234", "pin": null }]

Buyurtmani olish

GET/orders/{transaction_id}

Buyurtmani xuddi shu ko'rinishda qaytaradi. Noma'lum transaction_id uchun 404 ORDER_NOT_FOUND qaytadi.

Buyurtmalar ro'yxati

GET/orders

Eng yangilari birinchi. Parametrlar: status (pending, processing, completed yoki failed), page, per_page (500 tagacha). Javobda data (buyurtmalar ro'yxati) va page, per_page, total hamda last_page bor meta bo'ladi.

Buyurtma bajarilmasa

  • Qabul qilinishidan oldin xato olasiz va hech narsa yechilmaydi: INSUFFICIENT_BALANCE, OFFER_UNAVAILABLE, PRICE_CHANGED, VALIDATION_FAILED.
  • Qabul qilingandan keyin buyurtma SUPPLIER_FAILED yoki SUBMIT_TIMEOUT error.code bilan failed holatiga o'tadi va to'liq summa balansingizga qaytadi.
  • Yetkazish paytida narx o'zgargan bo'lsa, 409 PRICE_CHANGED olasiz; pul allaqachon balansingizga qaytgan.