Buyurtmalar va holatlar

Order (buyurtma) bitta qabul qiluvchiga Stars yoki Premium yetkazib berishni bildiradi. Buyurtma uni yaratgan Project'ga tegishli.

YaratishCopy Anchor Link

curl -X POST "https://example.com/v1/orders" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "externalId": "bot-order-1024",    "username": "durov",    "product": "STARS",    "quantity": 100  }'

{  "success": true,  "data": {    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",    "externalId": "bot-order-1024",    "product": "STARS",    "quantity": 100,    "months": null,    "username": "durov",    "recipientName": "Pavel Durov",    "status": "QUEUED",    "price": "1.65",    "currency": "USD",    "failure": null,    "createdAt": "2026-10-06T09:15:22.443Z",    "sentAt": null,    "completedAt": null  },  "meta": {    "requestId": "9f1c2b7e-3a4d-4e5f-8a6b-7c8d9e0f1a2b",    "timestamp": "2026-10-06T09:15:22.481Z",    "processingTimeMs": 38  }}

POST /v1/orders
X-API-Key: ifk_…
Idempotency-Key: 5c0e1d7a-3b1f-4c1e-9d55-0f6b6a1b2c3d
Content-Type: application/json

{ "product": "STARS", "quantity": 500, "username": "durov", "externalId": "1042" }

201 javobida buyurtma obyekti qaytadi:

{
  "id": "0199a1b2-6f00-7abc-9def-112233445566",
  "externalId": "1042",
  "product": "STARS",
  "quantity": 500,
  "months": null,
  "username": "durov",
  "recipientName": "Pavel Durov",
  "status": "QUEUED",
  "price": "8.25",
  "currency": "USD",
  "failure": null,
  "createdAt": "2026-09-26T10:15:30.000Z",
  "sentAt": null,
  "completedAt": null
}

price AQSh dollaridagi satr. failure faqat FAILED holatida to'ldiriladi: { "code": "RECIPIENT_NOT_FOUND", "message": "Telegram user not found" }.

Buyurtma yaratilganda biz:

1. qabul qiluvchini (kesh orqali) tekshiramiz: u topilmasa, darhol 422 (-9002) qaytaramiz, Premium sovg'a qilib bo'lmasa, 422 (-9003); bunda pul bloklanmaydi;
2. narxni narxlar ro'yxatingiz bo'yicha qayd etamiz: u buyurtmada saqlanadi va keyin o'zgarmaydi;
3. summani balansda bloklaymiz (HOLD), mablag' yetmasa, 402 (-9301) qaytaramiz;
4. buyurtmani navbatga qo'yamiz va QUEUED holati bilan 201 javob beramiz.

HolatlarCopy Anchor Link

curl -X GET "https://example.com/v1/orders/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "success": true,  "data": {    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",    "externalId": "bot-order-1024",    "product": "STARS",    "quantity": 100,    "months": null,    "username": "durov",    "recipientName": "Pavel Durov",    "status": "SUCCEEDED",    "price": "1.65",    "currency": "USD",    "failure": null,    "createdAt": "2026-10-06T09:15:22.443Z",    "sentAt": "2026-10-06T09:15:31.902Z",    "completedAt": "2026-10-06T09:15:48.215Z"  },  "meta": {    "requestId": "9f1c2b7e-3a4d-4e5f-8a6b-7c8d9e0f1a2b",    "timestamp": "2026-10-06T09:15:22.481Z",    "processingTimeMs": 38  }}

curl -X GET "https://example.com/v1/orders"

{  "success": true,  "data": [    {      "id": "2f1a8b3c-5d6e-4f70-8a9b-0c1d2e3f4a5b",      "externalId": "bot-order-1025",      "product": "PREMIUM",      "quantity": null,      "months": 6,      "username": "durov",      "recipientName": "Pavel Durov",      "status": "FAILED",      "price": "16.99",      "currency": "USD",      "failure": {        "code": "RECIPIENT_NOT_ELIGIBLE",        "message": "The recipient cannot receive this gift (Premium may already be active)"      },      "createdAt": "2026-10-06T09:16:02.118Z",      "sentAt": null,      "completedAt": "2026-10-06T09:16:05.774Z"    },    {      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",      "externalId": "bot-order-1024",      "product": "STARS",      "quantity": 100,      "months": null,      "username": "durov",      "recipientName": "Pavel Durov",      "status": "SUCCEEDED",      "price": "1.65",      "currency": "USD",      "failure": null,      "createdAt": "2026-10-06T09:15:22.443Z",      "sentAt": "2026-10-06T09:15:31.902Z",      "completedAt": "2026-10-06T09:15:48.215Z"    }  ],  "meta": {    "requestId": "9f1c2b7e-3a4d-4e5f-8a6b-7c8d9e0f1a2b",    "timestamp": "2026-10-06T09:20:00.012Z",    "processingTimeMs": 21,    "pagination": {      "page": 1,      "limit": 20,      "totalItems": 2,      "totalPages": 1    }  }}

QUEUED ──▶ PROCESSING ──▶ SENT ──▶ SUCCEEDED
  ▲            │            │
  └─ takror ───┘            ├──▶ QUEUED        (o'tkazma bajarilmagani isbotlangan)
               │            └──▶ NEEDS_REVIEW ──▶ SUCCEEDED | FAILED
               └──▶ FAILED  (yakuniy xato yoki 3 urinish)

Odatda QUEUED dan SUCCEEDED gacha 10 dan 60 soniyagacha vaqt ketadi. Agar barcha akkauntlar band bo'lsa (trottling bo'limiga qarang), buyurtma QUEUED holatida kutadi. Bu odatiy hol.

Qayta urinishlarCopy Anchor Link

Qayta urinishlarni platformaning o'zi bajaradi, buyurtmani qayta yaratishingiz shart emas:

• to'lov yuborilishidan oldin akkauntda muammo bo'lsa (sessiya muddati tugagan, hamyonda mablag' kam): buyurtma QUEUED holatiga qaytadi va boshqa akkaunt tomonidan olinadi, urinish hisoblanmaydi;
• yuborishdan oldin yetkazib beruvchi yoki tarmoqda vaqtinchalik xato bo'lsa: 30 soniya × urinish raqami o'tgach qayta urinish; jami 3 urinish, shundan so'ng buyurtma ATTEMPTS_EXHAUSTED kodi bilan FAILED bo'ladi;
• yakuniy xato bo'lsa (qabul qiluvchi topilmadi, Premium allaqachon faol): darhol RECIPIENT_NOT_FOUND yoki RECIPIENT_NOT_ELIGIBLE kodi bilan FAILED;
• SENT dan keyin buyurtma faqat o'tkazma bajarilmagani isbotlansa takrorlanadi (urinish hisoblanadi). Shu tariqa ikki marta yetkazish va ikki marta to'lash istisno qilinadi; agar natija 10 daqiqa ichida aniq bo'lmasa, buyurtma NEEDS_REVIEW holatiga o'tadi va qo'lda hal qilinadi (rad etilsa, REJECTED_BY_REVIEW kodi bilan FAILED bo'ladi).

IdempotentlikCopy Anchor Link

Idempotentlik bitta so'rovni bir necha marta yuborish natijani o'zgartirmasligini, ya'ni takroriy so'rov ikkinchi buyurtma yaratmasligini bildiradi. Dublikatlardan ikki xil himoya bor, ikkalasidan ham foydalaning:

• Idempotency-Key aniq bir HTTP so'rovni himoya qiladi. Xuddi shu kalit va xuddi shu tana bilan qayta yuborilgan so'rov ikkinchi buyurtma yaratmasdan o'sha javobni qaytaradi (Idempotent-Replayed: true sarlavhasi bilan). Xuddi shu kalit boshqa tana bilan kelsa, 422 (-11002) qaytadi; agar birinchi so'rov hali bajarilayotgan bo'lsa, 409 (-11003) qaytadi, birozdan keyin qayta urining. Xato javoblar eslab qolinmaydi: tuzatilgan so'rovni xuddi shu kalit bilan qayta yuborish mumkin. Kalitni har bir amal uchun bir marta yarating (masalan, UUID) va taymautda uni takror ishlating.
• externalId sizning tizimingizdagi buyurtmani himoya qiladi. Project ichida bir xil externalId bilan ikkinchi buyurtma yangi Idempotency-Key bilan ham yaratilmaydi: xuddi shu parametrlar bilan takroriy POST mavjud buyurtmani qaytaradi, boshqa parametrlar bilan (username, product, quantity, months) esa 409 (-9207) qaytaradi. Buyurtma yaratilganiga ishonchingiz komil bo'lmasa, uni toping: GET /v1/orders?externalId=1042.

Buyurtmalarni olishCopy Anchor Link

• GET /v1/orders/{id}: bitta buyurtma; boshqa Project'ning buyurtmasi uchun 404 (-9201).
• GET /v1/orders?status=FAILED&externalId=1042&page=1&limit=20: Project buyurtmalari ro'yxati, yangilari birinchi (limit 100 gacha); sahifalash meta.pagination ichida.