Developer hujjatlari

SMS Gateway REST API'si orqali har qanday tildagi dasturdan SMS yuborishingiz, qabul qilishingiz, kontaktlarni boshqarishingiz va yetkazish statusini real-time kuzatishingiz mumkin.

1. Tezkor boshlash

1. Hisob yarating: Ro'yxatdan o'tish
2. Android ilovasini o'rnating va QR kod skan qiling
3. /settings/api/ dan API key oling
4. Quyidagi birinchi so'rovni yuboring:

curl -X POST https://smsgw.uz/api/v1/messages/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+998901234567",
    "message": "Salom dunyo!"
  }'

import requests

resp = requests.post(
    "https://smsgw.uz/api/v1/messages/send",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "number": "+998901234567",
        "message": "Salom dunyo!",
    },
)
print(resp.json())

const resp = await fetch(
  "https://smsgw.uz/api/v1/messages/send",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      number: "+998901234567",
      message: "Salom dunyo!",
    }),
  },
);
console.log(await resp.json());

$ch = curl_init("https://smsgw.uz/api/v1/messages/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "number" => "+998901234567",
        "message" => "Salom dunyo!",
    ]),
]);
echo curl_exec($ch);

2. Autentifikatsiya

Har so'rov API key bilan autentifikatsiya qilinishi kerak. Kalitni 3 xil joydan uzatish mumkin:

# Tavsiya — Authorization header
Authorization: Bearer YOUR_API_KEY

# Yoki
X-API-Key: YOUR_API_KEY

# Yoki query param (faqat GET uchun, loglarda qoladi — ehtiyot bo'ling)
?key=YOUR_API_KEY

3. Endpointlar

To'liq interaktiv hujjatlar uchun: Swagger UI yoki ReDoc.

4. SMS yuborish

POST /api/v1/messages/send

Request body

{
  "number":  "+998901234567",     // majburiy
  "message": "Xabar matni",        // majburiy (1-1600 belgi)
  "devices": "1",                  // qurilma id (ixtiyoriy)
  "sim_slot": 0,                   // 0 yoki 1 (ixtiyoriy)
  "schedule": 1800000000,          // unix timestamp (ixtiyoriy)
  "type": "sms"                    // "sms" yoki "mms"
}

Javob

{
  "success": true,
  "data": {
    "messages": [{
      "ID": 12345,
      "number": "+998901234567",
      "message": "Xabar matni",
      "deviceID": 1,
      "simSlot": "0",
      "status": "queued",
      "sentDate": "2026-04-13T10:30:00Z",
      "groupID": "abc123"
    }],
    "credits": null
  }
}

5. Xabarlarni o'qish

GET /api/v1/messages?status=Delivered&deviceID=1

Query parametrlari

• id — aniq xabar
• groupId — bulk batch ID
• status — Pending, Sent, Delivered, Failed, Queued, Canceled, Received
• deviceID, simSlot — qurilma filterlari

6. Long-polling (qurilma uchun)

GET /api/v1/polling/pending?key=API_KEY&wait=30

Android qurilma wait soniya (0-30) kutadi — yangi SMS kelsa darhol oladi, aks holda bo'sh javob. FCM ga qo'shimcha fallback sifatida ishlatiladi.

7. Webhook'lar

SMS statusini pollaysizmi? Yaxshisi webhook qo'shing. SMS yuborilganda / yetkazilganda / xato bo'lganda bizga sizga POST HTTP so'rov yuborib turadi.

Webhook endpointni /webhooks/ sahifasidan qo'shing.

Event turlari

• sms.sent — qurilmaga yuborildi
• sms.delivered — operator yetkazishni tasdiqladi
• sms.failed — barcha urinishlar muvaffaqiyatsiz
• sms.received — kiruvchi SMS
• device.online / device.offline
• system.ping — sinov hodisasi

Payload format

POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Id: 550e8400-e29b-41d4-a716-446655440000
X-Webhook-Event: sms.delivered
X-Webhook-Signature: sha256=abc123...
X-Webhook-Attempt: 1

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "sms.delivered",
  "created_at": "2026-04-13T10:30:00Z",
  "data": {
    "message_id": 12345,
    "phone": "+998901234567",
    "delivered_at": "2026-04-13T10:30:05Z"
  }
}

Imzoni tekshirish (Python)

import hmac, hashlib

def verify(secret: str, body: bytes, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    provided = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, provided)

8. Idempotency

Tarmoq xatosi tufayli so'rov ikki marta yuborilganda duplikat SMS'ni oldini olish uchun Idempotency-Key header yuboring:

POST /api/v1/messages/send
Idempotency-Key: order-1001-sms
{...}

Bir xil kalit bilan keyingi so'rovlar avvalgi javobni qaytaradi (24 soat davomida). Kalit sifatida UUID yoki sizning biznes ID'ngizni ishlating.

9. Rate limit

Har tarif uchun alohida chegara:

• Free: 60 so'rov/daqiqa
• Starter: 300/daqiqa
• Business: 1,500/daqiqa
• Pro: 6,000/daqiqa
• OTP endpoint'i: raqam bo'yicha 3/daqiqa (spam'dan himoya)

Har javobda limit headerlar bor:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1730000000

# Chegara oshsa:
HTTP/1.1 429 Too Many Requests
Retry-After: 30

10. Xatolik kodlari

Xato javob formati

{
  "success": false,
  "error": {
    "code": "quota_exceeded",
    "message": "Oylik SMS limiti tugadi.",
    "details": { "used": 5000, "limit": 5000 }
  }
}

11. SDK va integratsiyalar

Hozirda rasmiy SDK yo'q, lekin har til uchun ochiq misollar mavjud:

• Python / Node.js / PHP / cURL — yuqoridagi misollar
• Swagger UI — so'rovlarni brauzerdan sinab ko'ring
• OpenAPI 3.0 schema — SDK generate qilish uchun