API
API hujjati
Keng tarqalgan SMS API tizimlarining yóllari bilan mos REST API. Sórov tanasi - JSON, multipart/form-data yoki x-www-form-urlencoded; javoblar - JSON.
Bazaviy manzil: https://sms.faol.uz
Endpointlar
- POST
/api/auth/loginemail, password -> token - PATCH
/api/auth/refreshtoken -> token - GET
/api/auth/user - GET
/api/user/get-limit - POST
/api/message/sms/sendmobile_phone, message - POST
/api/message/sms/send-batchmessages[] - GET
/api/message/sms/status_by_id/{id} - GET
/api/message/sms/listpage, per_page, status, dispatch_id
Autentifikatsiya
Kabinetda («API» bólimi) API parolini yarating. E-mail va şu parol bilan kiring; javobda 30 kunlik token bóladi. Uni Authorization: Bearer <token> kórinişida yuboring. Yangi API paroli barça tokenlarni bekor qiladi.
curl -X POST https://sms.faol.uz/api/auth/login \
-F email=app@example.com -F password='<API password>'
# {"message":"token_generated","data":{"token":"eyJ..."},"token_type":"bearer"}SMS yuboriş
Maydonlar: mobile_phone va message majburiy. callback_url ga holat webhooklari keladi, user_sms_id ularda qaytadi, priority=high xabarni navbatda birinçi qóyadi, ttl (60-259200 s) - eskirişidan oldin qança kutişi mumkin.
curl -X POST https://sms.faol.uz/api/message/sms/send \
-H "Authorization: Bearer <token>" \
-F mobile_phone=998901234567 \
-F message="Your code: 4821" \
-F callback_url=https://app.example.com/sms/callback \
-F user_sms_id=order-1042 \
-F priority=high -F ttl=300
# {"id":123,"message":"Waiting for SMS provider","status":"waiting","sms_count":1}Paket yuboriş
Bitta sórovda 500 tagaça xabar. Paket tóliq qabul qilinadi yoki umuman qabul qilinmaydi; u kunlik limitga hisoblanadi.
curl -X POST https://sms.faol.uz/api/message/sms/send-batch \
-H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
-d '{
"messages": [
{"user_sms_id": "a1", "to": "998901234567", "text": "Hello"},
{"user_sms_id": "a2", "to": "998931234567", "text": "Hello"}
],
"dispatch_id": "campaign-17",
"callback_url": "https://app.example.com/sms/callback"
}'
# {"message":"Waiting for SMS provider","status":"waiting","data":[{"id":124,"user_sms_id":"a1"},{"id":125,"user_sms_id":"a2"}]}Holat va róyxat
Bitta xabar id bóyiça yoki holat va dispatch_id bóyiça filtrlangan sahifa (per_page 200 gaça).
GET /api/message/sms/status_by_id/123
GET /api/message/sms/list?page=1&per_page=50&status=delivered&dispatch_id=campaign-17
GET /api/user/get-limit # {"daily_limit":1000,"used_today":42,"remaining_today":958}
GET /api/auth/user # the profile and the limits
PATCH /api/auth/refresh # a new token for a valid oneLimitlar
Kunlik va daqiqalik limitlarni administrator belgilaydi, ular kabinetda kórinadi; ularni GET /api/user/get-limit qaytaradi. Limit tugasa API 429 javobini beradi.
Holatlar
waiting → sent → delivered | undelivered. failed - takrorlab bólmaydigan xatoda; expired - xabar yuborilmasdan ttl tugasa.
Webhooklar
Har bir holat ózgarganda callback_url ga JSON bilan POST ketadi. X-Faol-Signature sarlavhasi - t=<unix time>,v1=<hex>, bunda v1 = HMAC-SHA256(webhook secret, "<t>.<raw body>"). 2xx javob bering; aks holda 8 martagaça takrorlanadi. Yetkaziş at-least-once: takrorni X-Faol-Event-Id bóyiça ajrating.
POST https://app.example.com/sms/callback
X-Faol-Event-Id: 91
X-Faol-Attempt: 1
X-Faol-Signature: t=1788988800,v1=3f1c...e2
{"event":"sms.status","message_id":123,"user_sms_id":"order-1042","dispatch_id":null,
"phone_number":"998901234567","status":"delivered","sms_count":1,"error":null,
"status_date":"2026-11-10T12:38:06+05:00"}[$t, $v1] = array_map(fn ($kv) => explode('=', $kv, 2)[1], explode(',', $_SERVER['HTTP_X_FAOL_SIGNATURE']));
$body = file_get_contents('php://input');
$valid = hash_equals(hash_hmac('sha256', "$t.$body", $webhookSecret), $v1) && abs(time() - (int) $t) < 300;import { createHmac, timingSafeEqual } from 'node:crypto';
function valid(header, rawBody, secret) {
const { t, v1 } = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
}import hashlib, hmac, time
def valid(header: str, raw_body: bytes, secret: str) -> bool:
parts = dict(kv.split("=", 1) for kv in header.split(","))
expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300Xatolar
Har bir xato {"status":"error","message":"...","errors":{"field":"..."}} kórinişida, HTTP holati 401, 403, 404, 422, 429 yoki 500.
HTTP/1.1 422
{"status":"error","message":"Validation failed","errors":{"mobile_phone":"The phone number must be 998XXXXXXXXX"}}Bilib qóying
- SMS oddiy telefon raqamidan keladi: jónatuvçi nomini (alfa-nom) qóyib bólmaydi. Xizmat tranzaksion xabarlar - kodlar va bildirişnomalar uçun.
- Oluvçining roziligisiz reklama yuboriş, şuningdek 18:00 dan 09:00 gaça reklama tarqatiş taqiqlanadi.
- Kirill matn (UCS-2) bitta SMS qismiga 70 belgi, lotin 160 belgi siǵadi. Ózbek lotinidagi tutuq belgilari (o‘ g‘) arzonroq kodlaşni saqlaş uçun oddiy apostrofga almaştiriladi.