Qorunan endpoint sorğularında şirkətinizin məxfi API açarı olmalıdır. Əksəriyyəti onu bu başlıqda qəbul edir: key başlığında; bəzi köhnə GET/XML endpoint-ləri istifadə edir: key sorğu parametrindən.
API açarınızı açıqlamayın
Açarı server mühit dəyişənində saxlayın. Frontend JavaScript, mobil tətbiq və ya açıq Git repozitoriyasına daxil etməyin.
Sorğu başlıqları
key: YOUR_API_KEY
Content-Type: application/json
02
QAYDALAR
Formatlar və statuslar
API əsasən JSON cavabları qaytarır. statusID sahəsi nəticəni bildirir; uğurlu sorğunun dəyəri 0 . XML endpoint XML cavabı qaytarır.
0 SMS göndərildi
1 Alındı
2 Çatdırılmadı
3 Status gözlənilir
4 Xəta
API ARAYIŞI
Bütün resurslar və endpoint-lər
Aşağıdakı məlumat açıq Postman kolleksiyasının son versiyası ilə sinxronlaşdırılıb.
API QRUPU
SMS API
11 endpoint
SMS API / Göndərən adı yarat
Göndərən adı yarat
API açarı · Başlıq
POSThttps://api.ubill.dev/v1/sms/brandNameCreate
Cavab statusu
statusID
Təsvir
0
Göndərən adı yaradıldı
10
brandName sahəsi boşdur
20
brandName 2–11 simvoldan ibarət olmalıdır
30
brandName icazəsiz işarələr ehtiva edir
40
brandName artıq əlavə olunub
50
Son əlavə olunmuş brandName təsdiqini gözləyin
60
The description field is required. Specify your website, Facebook/Instagram page or application and how you will use the brandName.
Sorğuların təsdiqi üçün məxfi API açarı. Şirkət parametrlərində baxın və idarə edin.
brandID
Sistemdə unikal brend identifikatoru.
numbers
Vergüllə ayrılmış mobil nömrələr. Beynəlxalq format tələb olunur olmadan 00 və ya +.
text
SMS mətni. Bütün Unicode simvolları dəstəklənir.
İxtiyari parametrlər
Parametr
Təsvir
stopList
stopList=false — stop-siyahı yoxlamasını söndürür. Nömrə siyahıda olsa belə mesaj göndərilir.
otp
otp=true — mesajı OTP (birdəfəlik şifrə / təsdiq kodu) kimi işarələyir. OTP mesajları ən yüksək prioritetlə emal olunur. ⚠️ İstifadə olunmalıdır yalnız giriş təsdiqi kodları üçün.
sendTime
Planlı SMS çatdırılma vaxtı. Format: Y-m-d H:i (məsələn: 2026-02-01 23:30). Göstərilən vaxt gələcəkdə olmalıdır. Göstərilməzsə dərhal göndərilir.
callbackUrl
Bu SMS sorğusu üçün fərdi callback URL-i. Yalnız API tətbiqində qlobal standart callback URL-i təyin olunubsa işləyir.
Qeydlər
OTP yalnız giriş, təsdiq və şifrə sıfırlama kimi autentifikasiya prosesləri üçündür.
Yanlış istifadə olunan otp parametri çatdırılma və ya hesab məhdudiyyətlərinə səbəb ola bilər.
Cavab statusu
statusID
Təsvir
0
SMS göndərildi
10
brandID tapılmadı
20
Nömrələr tapılmadı
30
Mesaj mətni boşdur
40
SMS balansı kifayət deyil
50
Etibarlı nömrələr tapılmadı
60
sendTime formatı yanlışdır. Y-m-d H:i istifadə edin
Mobil nömrələr massivi. Beynəlxalq format tələb olunur olmadan 00 və ya + . Nümunə: ["9955XXXXXXXX","9955XXXXXXXX"]
text
SMS mətni. Bütün Unicode simvolları dəstəklənir.
İxtiyari parametrlər (JSON gövdəsi)
Parametr
Təsvir
stopList
false — stop-siyahı yoxlamasını söndürür. Nömrə siyahıda olsa belə mesaj göndərilir.
otp
true — mesajı OTP (birdəfəlik şifrə / təsdiq kodu) kimi işarələyir. OTP mesajları ən yüksək prioritetlə emal olunur. ⚠️ İstifadə olunmalıdır yalnız giriş təsdiqi kodları üçün.
sendTime
Planlı SMS çatdırılma vaxtı. Format: Y-m-d H:i (məsələn: "2026-02-01 23:30" ). Gələcəkdə olmalıdır. Verilməzsə dərhal göndərilir.
callbackUrl
Bu SMS sorğusu üçün fərdi callback URL-i. Yalnız API tətbiqində qlobal standart callback URL-i təyin olunubsa işləyir.
Qeydlər
OTP yalnız giriş, təsdiq və şifrə sıfırlama kimi autentifikasiya prosesləri üçündür.
Yanlış istifadə olunan otp parametri çatdırılma və ya hesab məhdudiyyətlərinə səbəb ola bilər.
Cavab statusu
statusID
Təsvir
0
SMS göndərildi
10
brandID tapılmadı
20
Nömrələr tapılmadı
30
Mesaj mətni boşdur
40
SMS balansı kifayət deyil
50
Etibarlı nömrələr tapılmadı
60
sendTime formatı yanlışdır. Y-m-d H:i istifadə edin
90
JSON xətası
99
Ümumi xəta
⚠️ Hədlər və qeydlər
Maksimum sorğu gövdəsi: 100 MB → Daha böyük sorğular rədd edilir.
Cloudflare proksi gözləmə həddi: 100 saniyə → Daha uzun sorğular 524 Timeout qaytarır.
Gözləmə və yaddaş problemlərini önləmək üçün böyük SMS sorğularını kiçik hissələrə bölün.
İstifadə edin: stopList bloklanmış nömrələrə göndərişin qarşısını almaq üçün.
Sınaqdan praktik müşahidə:
Sınaqlarımızda uğurla göndərilib: bir sorğuda 500 000 nömrəyə qədər . Daha çoxu yaddaş, gözləmə və sorğu ölçüsü problemləri yarada bilər. Faktiki hədlər mətn uzunluğu, kodlaşdırma və server yükündən asılıdır.
Tövsiyə:
Təhlükəsiz və etibarlı iş üçün sorğuları məhdudlaşdırın: hər paketdə təxminən 100 000 nömrə .
Sorğu başlıqları 2
Açar
Dəyər
Mənbə
key
YOUR_API_KEY
Autentifikasiya
Content-Type
application/json
Başlıq
Sorğu gövdəsi JSON
Sorğu gövdəsi
{
"brandID": 1,
"numbers": [
9955XXXXXXXX,
9955XXXXXXXX
],
"text": "Message",
"stopList": false, // Enable/disable checking numbers in the stop list
"sendTime": "2026-02-01 23:01" // sendTime (optional)
}
Mobil nömrələr massivi. Beynəlxalq format tələb olunur olmadan 00 və ya + . Nümunə: ["9955XXXXXXXX","9955XXXXXXXX"]
text
SMS mətni. Bütün Unicode simvolları dəstəklənir.
İxtiyari parametrlər (JSON gövdəsi)
Parametr
Təsvir
stopList
false — stop-siyahı yoxlamasını söndürür. Nömrə siyahıda olsa belə mesaj göndərilir.
otp
true — mesajı OTP (birdəfəlik şifrə / təsdiq kodu) kimi işarələyir. OTP mesajları ən yüksək prioritetlə emal olunur. ⚠️ İstifadə olunmalıdır yalnız giriş təsdiqi kodları üçün.
sendTime
Planlı SMS çatdırılma vaxtı. Format: Y-m-d H:i (məsələn: "2026-02-01 23:30" ). Gələcəkdə olmalıdır. Verilməzsə dərhal göndərilir.
callbackUrl
Bu SMS sorğusu üçün fərdi callback URL-i. Yalnız API tətbiqində qlobal standart callback URL-i təyin olunubsa işləyir.
Qeydlər
OTP yalnız giriş, təsdiq və şifrə sıfırlama kimi autentifikasiya prosesləri üçündür.
Yanlış istifadə olunan otp parametri çatdırılma və ya hesab məhdudiyyətlərinə səbəb ola bilər.
Cavab statusu
statusID
Təsvir
0
SMS göndərildi
10
brandID tapılmadı
20
Nömrələr tapılmadı
30
Mesaj mətni boşdur
40
SMS balansı kifayət deyil
50
Etibarlı nömrələr tapılmadı
60
sendTime formatı yanlışdır. Y-m-d H:i istifadə edin
90
JSON xətası
99
Ümumi xəta
⚠️ Hədlər və qeydlər
Maksimum sorğu gövdəsi: 100 MB → Daha böyük sorğular rədd edilir.
Cloudflare proksi gözləmə həddi: 100 saniyə → Daha uzun sorğular 524 Timeout qaytarır.
Gözləmə və yaddaş problemlərini önləmək üçün böyük SMS sorğularını kiçik hissələrə bölün.
İstifadə edin: stopList bloklanmış nömrələrə göndərişin qarşısını almaq üçün.
Sınaqdan praktik müşahidə:
Alıcıya düşən SMS
Sorğuda maksimum nömrə sayı
1
400,000
2
200,000
3
150,000
4
120,000
5
100,000
6
50,000
Faktiki hədlər mətn uzunluğu, kodlaşdırma və server yükündən asılıdır.
Tövsiyə:
Etibarlı iş üçün birləşdirilmiş SMS sayına uyğun yuxarıda göstərilən nömrə hədlərinə riayət edin.
API tətbiqinin parametrlərində bir ortaq ünvan var: HTTPS callback URL-i . Çatdırılma hesabatları, SMS brend aktivləşməsi və gələcək API hadisələri eyni ünvana göndərilir: GET sorğusu .
İstifadə edin: event parametrini bildiriş növünü müəyyən etmək üçün. Uğurlu emaldan sonra qaytarın: 2xx uğurlu HTTP statusu.
Telefon nömrələri ilə birlikdə yeni müştəri yaradır. Müştəri nömrəsi ( id cavabda, cID daxili olaraq) avtomatik yaradılır və şirkət daxilində unikaldır.
Tələb olunan icazə: customers.create . Sorğu gövdəsi JSON olmalıdır və Content-Type: application/json başlığı məcburidir.
Sorğu gövdəsi
Sahə
Növ
Məcburi
Təsvir
typeID
tam ədəd
bəli
Müştərinin hüquqi növü uBill növ siyahısında olmalıdır ( 1 = fiziki şəxs).
name
sətir, maksimum 50
xeyr
Müştəri adı.
personalNo
sətir, maksimum 11
xeyr
Şəxsi nömrə və ya şirkət kodu, yalnız hərf və rəqəmlər.
email
sətir
xeyr
Verildikdə etibarlı e-poçt ünvanı olmalıdır.
birthDate
sətir
xeyr
Tarix bu formatda: YYYY-MM-DD formatında.
lang
sətir
xeyr
Bunlardan biri: ka, en, ru . Standart olaraq şirkətdə təyin olunan müştəri dili götürülür.
address
sətir, maksimum 50
xeyr
Müştəri ünvanı.
column1, column2
sətir, maksimum 50
xeyr
Sərbəst əlavə sahələr.
numbers
massiv
bəli
Müştərinin telefonları, ən azı biri məcburidir.
numbers[] obyekti
Sahə
Növ
Təsvir
number
sətir
Ölkə kodu olmadan yerli nömrə, 6–15 rəqəm.
mobile
sətir
Tam beynəlxalq nömrə. Bu açar işlədildikdə ölkə kodu nömrənin əvvəlindən çıxarılır.
countryCode
sətir
Ölkə kodu, standart: +995.
isPrimary
0 və ya 1
Əsas nömrəni işarələyir. Seçilməzsə, siyahının birinci nömrəsi əsas olur.
smsEnabled
0 və ya 1
Nömrənin SMS bildirişləri alması, standart: 1.
note
sətir, maksimum 100
Nömrə üçün sərbəst qeyd.
Bir nömrə qısa formada da göndərilə bilər: {"mobile": "9955XXXXXXXX", "countryCode": "+995"} bunun əvəzinə: numbers massivi. Təkrarlar xəbərdarlıq olmadan silinir; eyni şirkətdə başqa müştəriyə aid nömrə rədd olunur.
Cavablar
HTTP
statusID
Təsvir
201
0
Müştəri yaradıldı, data yeni müştərini ehtiva edir.
400
400
Yoxlama uğursuzdur, errors obyekti hər yanlış sahəni göstərir.
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"typeID": "typeID does not exist",
"birthDate": "birthDate must be a valid date in YYYY-MM-DD format",
"email": "Email is invalid",
"numbers": "Phone number is invalid"
}
}
Nömrə artıq istifadə olunur 400
Cavab · JSON
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"numbers": "+9955XXXXXXXX is already assigned to another customer"
}
}
Billinq API / Müştərilər / Müştərini al
Müştərini al
API açarı · Başlıq
GEThttps://api.ubill.dev/v1/customers/100001
Bu endpoint-in Postman kolleksiyasında ayrıca təsviri yoxdur.
Mövcud müştəri üçün yeni hesab (xidmət) yaradır. Hesab nömrəsi ( id cavabda) uBill veb interfeysində olduğu kimi şirkətin cID parametrlərindən yaradılır.
Tələb olunan icazə: accounts.create . Sorğu gövdəsi JSON olmalıdır və Content-Type: application/json başlığı məcburidir.
Sorğu gövdəsi
Sahə
Növ
Məcburi
Təsvir
customerID
tam ədəd
bəli
Hesabın aid olduğu müştəri nömrəsi, eyni id müştəri endpoint-lərinin qaytardığı dəyər.
name
sətir, maksimum 50
xeyr
Hesab adı.
birthDate
sətir
xeyr
Tarix bu formatda: YYYY-MM-DD formatında.
areaID
tam ədəd
xeyr
uBill rayon siyahısındakı yaşayış məntəqəsi ID-si.
address
sətir, maksimum 50
xeyr
Xidmət ünvanı.
geoLocation
sətir, maksimum 100
xeyr
Koordinatlar bu formatda: 41.732438,44.7688134 formatında.
column1, column2
sətir, maksimum 50
xeyr
Sərbəst əlavə sahələr.
tariffID
tam ədəd
xeyr
Şirkətin tarif nömrəsi.
groupID
tam ədəd
xeyr
Şirkətin qrup və ya filial nömrəsi.
tagsID
tam ədədlər massivi
xeyr
Hesaba əlavə olunan şirkət etiketlərinin nömrələri.
numbers
massiv
xeyr
Hesab telefonları müştəri kimi təsvir olunur. Müştəridən fərqli olaraq hesab nömrəsiz yaradıla bilər.
Moduldan asılı sahələr
Bu sahələr yalnız şirkətdə uyğun modul aktivdirsə oxunur.
Sahə
Modul
Məcburi
Təsvir
mac
Şəbəkə
bəli
Cihazın MAC ünvanı, şirkət daxilində unikal.
onuMac
Şəbəkə
xeyr
ONU MAC ünvanı, şirkət daxilində unikal.
ipRangeID
Şəbəkə
bəli
NAS IP diapazonunun nömrəsi. İlk boş ünvan avtomatik hesaba verilir və belə qaytarılır: ip.
stbMac
IPTV
xeyr
STB MAC ünvanı, şirkət daxilində unikal.
gpsProviderID
GPS track
bəli
Şirkətin GPS provayder nömrəsi.
gpsTrackIdentifier
GPS track
xeyr
Cihaz identifikatoru, şirkət daxilində unikal.
SMS bildirişi
Şirkətdə hesab əlavə etmə SMS-i aktivdirsə, yeni hesabın SMS aktiv bütün nömrələrinə mesaj göndərilir və şirkətin SMS balansından tutulur. Balans çatmasa da hesab yaradılır, cavaba əlavə olunur: warning sahəsi.
Cavablar
HTTP
statusID
Təsvir
201
0
Hesab yaradıldı, data yeni hesabı ehtiva edir.
400
400
Yoxlama uğursuzdur, errors obyekti hər səhv sahəni göstərir. Təkrar MAC və nömrələr eyni qaydada bildirilir.
{
"statusID": 0,
"message": "Account created",
"data": {
"id": 100002,
"customerID": 100001,
"name": "მეორე ბინა",
"mobile": "9955XXXXXXXX",
"numbers": [
{
"mobile": "9955XXXXXXXX",
"countryCode": "+995",
"number": "5XXXXXXXX",
"isPrimary": 1,
"smsEnabled": 1,
"note": null
}
],
"personalNo": "XXXXXXXXXXX",
"birthDate": null,
"areaID": null,
"area": "არ არის მითითებული",
"address": "",
"geoLocation": null,
"column1": "",
"column2": "",
"groupID": null,
"tagsID": [],
"tariffID": null,
"balance": "0.00",
"statusID": 1,
"createdAt": "2026-08-26 13:20:11"
},
"warning": "account was created, but the notification sms was not sent - not enough messages on the balance"
}
Yoxlama uğursuzdur 400
Cavab · JSON
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"customerID": "Customer not found",
"geoLocation": "geoLocation must look like 41.732438,44.7688134",
"tariffID": "tariffID does not exist",
"mac": "mac is required",
"ipRangeID": "ipRangeID is required"
}
}
MAC artıq istifadə olunur 400
Cavab · JSON
{
"statusID": 400,
"message": "Account creation failed",
"data": null,
"errors": {
"account": [
"ეს MAC მისამართი უკვე მითითებულია სხვა ანგარიშზე"
]
}
}
Billinq API / Hesablar / Hesabı al
Hesabı al
API açarı · Başlıq
GEThttps://api.ubill.dev/v1/accounts/100001
Bu endpoint-in Postman kolleksiyasında ayrıca təsviri yoxdur.