Holatlar#

Yakuniy holatlar o'zgarmaydi. Faqat sms_received da pul yechiladi.

Holat	Ma'nosi	Pul
`waiting_sms`	Raqam ajratildi, SMS kutilmoqda	Band qilingan
`sms_received`	Kod `sms_code` maydonida	Yechildi
`cancelled`	Siz bekor qildingiz	Qaytarildi
`expired`	20 daqiqada SMS kelmadi	Qaytarildi
`failed`	Provayder tomonidagi xato	Qaytarildi

Buyurtma yaratish#

country_id (GET /v1/countries) va service_code (GET /v1/prices yoki /v1/services) kerak. Javobda raqam (phone), narx va expires_at (yaratilgandan 20 daqiqa) bo'ladi.

curl -X POST 'https://api.milliysavdo.uz/v1/orders' \
  -H "Authorization: Bearer $MILLIYSAVDO_API_KEY" \
  -H 'Idempotency-Key: 8f14e45f-ceea-4e1a-9b2c-0d3c5e7a1b20' \
  -H "Content-Type: application/json" \
  -d '{"country_id":6,"service_code":"907"}'

201 Created

{
  "id": "ord_test_14",
  "object": "order",
  "mode": "test",
  "status": "waiting_sms",
  "phone": "+1888582997",
  "sms_code": null,
  "country": {
    "id": 6,
    "name": "United States",
    "iso_code": null
  },
  "service": {
    "code": "907",
    "title": "Telegram"
  },
  "price": {
    "amount": "3842.44",
    "amount_cents": 384244,
    "retail_amount": "4269.38",
    "retail_amount_cents": 426938,
    "discount_percent": "10.00",
    "currency": "UZS"
  },
  "created_at": "2026-10-16T02:13:52.251868Z",
  "expires_at": "2026-10-16T02:33:52.251868Z",
  "completed_at": null
}

Narx maydonlari#

amount — siz to'laydigan summa (UZS, satr), retail_amount — chegirmasiz narx, discount_percent — sizga xos chegirma. Hisob-kitob uchun *_cents butun sonlaridan foydalaning (1 so'm = 100 cents) — suzuvchi nuqta xatolaridan qochasiz.

SMS ni kutish: webhook yoki polling#

	Webhook	Polling
Kechikish	Darhol	So'rovlar oralig'iga bog'liq
Limit sarfi	Yo'q	Har bir tekshiruv — 1 so'rov
Murakkablik	Ommaviy HTTPS endpoint + imzo tekshiruvi	Oddiy sikl

Tavsiya: webhook + zaxira sifatida kamdan-kam polling (masalan, har 30 soniyada). Faqat polling ishlatsangiz, 3–5 soniya oraliq yetarli.

curl 'https://api.milliysavdo.uz/v1/orders/ord_test_14' \
  -H "Authorization: Bearer $MILLIYSAVDO_API_KEY"

Hali kutilmoqda

{
  "id": "ord_test_14",
  "object": "order",
  "mode": "test",
  "status": "waiting_sms",
  "phone": "+1888582997",
  "sms_code": null,
  "country": {
    "id": 6,
    "name": "United States",
    "iso_code": null
  },
  "service": {
    "code": "907",
    "title": "Telegram"
  },
  "price": {
    "amount": "3842.44",
    "amount_cents": 384244,
    "retail_amount": "4269.38",
    "retail_amount_cents": 426938,
    "discount_percent": "10.00",
    "currency": "UZS"
  },
  "created_at": "2026-10-16T02:13:52.251868Z",
  "expires_at": "2026-10-16T02:33:52.251868Z",
  "completed_at": null
}

Bekor qilish va pulni qaytarish#

POST /v1/orders/{id}/cancel faqat waiting_sms holatida ishlaydi va pul darhol qaytariladi. SMS allaqachon kelgan bo'lsa — 409 sms_already_received, boshqa yakuniy holatda — 409 order_not_cancellable. Provayder vaqtincha javob bermasa — 503, birozdan so'ng qayta urining.

curl -X POST 'https://api.milliysavdo.uz/v1/orders/ord_test_15/cancel' \
  -H "Authorization: Bearer $MILLIYSAVDO_API_KEY"

Bekor qilindi

{
  "id": "ord_test_15",
  "object": "order",
  "mode": "test",
  "status": "cancelled",
  "phone": "+1231407863",
  "sms_code": null,
  "country": {
    "id": 6,
    "name": "United States",
    "iso_code": null
  },
  "service": {
    "code": "907",
    "title": "Telegram"
  },
  "price": {
    "amount": "3842.44",
    "amount_cents": 384244,
    "retail_amount": "4269.38",
    "retail_amount_cents": 426938,
    "discount_percent": "10.00",
    "currency": "UZS"
  },
  "created_at": "2026-10-16T02:13:52.318700Z",
  "expires_at": "2026-10-16T02:33:52.318700Z",
  "completed_at": "2026-10-16T02:13:52.343024Z"
}

SMS kelgan

{
  "type": "https://api.milliysavdo.uz/docs/errors#sms_already_received",
  "title": "SMS kod allaqachon kelgan",
  "status": 409,
  "detail": "SMS kod allaqachon kelgan, bekor qilib bo'lmaydi",
  "code": "sms_already_received",
  "request_id": "req_e237cc97a1d76d93e1ac4323"
}

20 daqiqalik muddat#

expires_at gacha SMS kelmasa, buyurtma avtomatik expired bo'ladi va pul balansingizga qaytadi — hech narsa qilish shart emas. Webhook ulangan bo'lsa, order.expired hodisasi keladi.

Ma'lumot

Bir vaqtda faol buyurtmalar soni (max_active_orders) va kunlik buyurtmalar soni cheklangan. Limitga yetsangiz — 429 order_limit_reached. SMS kelmaydigan buyurtmalar ko'p bo'lsa, vaqtincha too_many_failed_orders cheklovi qo'yilishi mumkin.

Buyurtmalar ro'yxati#

GET /v1/orders faqat API orqali olingan buyurtmalarni qaytaradi (yangilari birinchi). status bo'yicha filtrlash va cursor sahifalash mavjud.

curl 'https://api.milliysavdo.uz/v1/orders?limit=2' \
  -H "Authorization: Bearer $MILLIYSAVDO_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "ord_test_15",
      "object": "order",
      "mode": "test",
      "status": "cancelled",
      "phone": "+1231407863",
      "sms_code": null,
      "country": {
        "id": 6,
        "name": "United States",
        "iso_code": null
      },
      "service": {
        "code": "907",
        "title": "Telegram"
      },
      "price": {
        "amount": "3842.44",
        "amount_cents": 384244,
        "retail_amount": "4269.38",
        "retail_amount_cents": 426938,
        "discount_percent": "10.00",
        "currency": "UZS"
      },
      "created_at": "2026-10-16T02:13:52.318700Z",
      "expires_at": "2026-10-16T02:33:52.318700Z",
      "completed_at": "2026-10-16T02:13:52.343024Z"
    },
    {
      "id": "ord_test_14",
      "object": "order",
      "mode": "test",
      "status": "sms_received",
      "phone": "+1888582997",
      "sms_code": "636841",
      "country": {
        "id": 6,
        "name": "United States",
        "iso_code": null
      },
      "service": {
        "code": "907",
        "title": "Telegram"
      },
      "price": {
        "amount": "3842.44",
        "amount_cents": 384244,
        "retail_amount": "4269.38",
        "retail_amount_cents": 426938,
        "discount_percent": "10.00",
        "currency": "UZS"
      },
      "created_at": "2026-10-16T02:13:52.251868Z",
      "expires_at": "2026-10-16T02:33:52.251868Z",
      "completed_at": "2026-10-16T02:13:52.301158Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}