Korumalı uç noktalara isteklerde şirketinizin gizli API anahtarı bulunmalıdır. Çoğu uç nokta bunu şu başlıkta alır: key başlığında; bazı eski GET/XML uç noktaları şu parametreyi kullanır: key sorgu parametresi.
API Anahtarınızı Açığa Çıkarmayın
Anahtarı sunucu ortam değişkeninde tutun. Ön yüz JavaScript'ine, mobil uygulamaya veya herkese açık Git deposuna koymayın.
İstek Başlıkları
key: YOUR_API_KEY
Content-Type: application/json
02
KURALLAR
Biçimler ve Durumlar
API çoğunlukla JSON yanıt döndürür. statusID alanı sonucu gösterir; başarılı isteğin değeri 0 . XML uç noktası XML yanıt döndürür.
0 SMS gönderildi
1 Alındı
2 Teslim edilmedi
3 Durum bekleniyor
4 Hata
API BAŞVURU KAYNAĞI
Tüm Kaynaklar ve Uç Noktalar
Aşağıdaki bilgiler, herkese açık Postman koleksiyonunun son sürümüyle eşitlenmiştir.
API GRUBU
SMS API
11 uç nokta
SMS API / Gönderici Adı Oluştur
Gönderici Adı Oluştur
API Anahtarı · Başlık
POSThttps://api.ubill.dev/v1/sms/brandNameCreate
Yanıt Durumu
statusID
Açıklama
0
Gönderici Adı Oluşturuldu
10
brandName alanı boş
20
brandName en az 2, en fazla 11 karakter olmalıdır
30
brandName içinde izin verilmeyen işaretler var
40
brandName zaten eklenmiş
50
Son eklenen brandName'in onaylanmasını bekleyin
60
The description field is required. Specify your website, Facebook/Instagram page or application and how you will use the brandName.
İstekleri doğrulayan gizli API anahtarı. Şirket ayarlarından görüntülenip yönetilir.
brandID
Sistemdeki benzersiz marka kimliği.
numbers
Virgülle ayrılmış cep telefonu numaraları. Uluslararası biçimde olmalıdır olmadan 00 veya +.
text
SMS içeriği. Tüm Unicode karakterleri desteklenir.
İsteğe Bağlı Parametreler
Parametre
Açıklama
stopList
stopList=false — engelleme listesi kontrolünü kapatır. Numara listede olsa da mesaj gönderilir.
otp
otp=true — mesajı OTP (tek kullanımlık parola / doğrulama kodu) olarak işaretler. OTP mesajları en yüksek öncelikle işlenir. ⚠️ Kullanılmalıdır yalnızca kimlik doğrulama kodları için.
sendTime
Zamanlanmış SMS teslim saati. Biçim: Y-m-d H:i (örneğin: 2026-02-01 23:30). Belirtilen zaman gelecekte olmalıdır. Belirtilmezse hemen gönderilir.
callbackUrl
Bu SMS isteğine özel geri çağırma URL'si. Yalnızca API uygulamasında genel varsayılan geri çağırma URL'si ayarlanmışsa çalışır.
Notlar
OTP mesajları yalnızca giriş, doğrulama ve parola sıfırlama gibi kimlik doğrulama işlemleri içindir.
Yanlış kullanılan otp parametresi teslimat veya hesap kısıtlamalarına neden olabilir.
Yanıt Durumu
statusID
Açıklama
0
SMS Gönderildi
10
brandID bulunamadı
20
Numaralar bulunamadı
30
Mesaj metni boş
40
Yetersiz SMS bakiyesi
50
Geçerli numara bulunamadı
60
Geçersiz sendTime biçimi. Y-m-d H:i kullanın
90
JSON Hatası
99
Genel Hata
⚠️ GET Yönteminin Sınırları
API katı bir sınır uygulamaz alıcı numarası sayısına.
Gerçek sınırları belirleyen: URL ve HTTP başlık boyutu sınırları (Cloudflare, proxy'ler, tarayıcılar).
Pratik Sınırlar
✅ İstek başına yaklaşık 1500 numaraya kadar güvenilir çalışır.
⚠️ Yaklaşık 2000 ve üzeri numara şuna yol açabilir: Header overflow hataları.
Bu hatalar oluşur istek API'ye ulaşmadan önce , HTTP / proxy düzeyinde.
Öneri
Kullanın: GET yalnızca küçük ve orta istekler için.
Büyük alıcı listelerinde her zaman kullanın: POST.
URL Parametreleri 5
keyqueryYOUR_API_KEY
brandIDquery1
numbersquery9955XXXXXXXX,9955XXXXXXXX
textquerymessage
stopListqueryfalse
Kod Örnekleri
cURL · PHP · JavaScript
cURL
curl --request GET \
--url 'https://api.ubill.dev/v1/sms/send?key=YOUR_API_KEY&brandID=1&numbers=9955XXXXXXXX,9955XXXXXXXX&text=message&stopList=false'
Cep telefonu numaraları dizisi. Uluslararası biçimde olmalıdır olmadan 00 veya + . Örnek: ["9955XXXXXXXX","9955XXXXXXXX"]
text
SMS içeriği. Tüm Unicode karakterleri desteklenir.
İsteğe Bağlı Parametreler (JSON Gövdesi)
Parametre
Açıklama
stopList
false — engelleme listesi kontrolünü kapatır. Numara listede olsa da mesaj gönderilir.
otp
true — mesajı OTP (tek kullanımlık parola / doğrulama kodu) olarak işaretler. OTP mesajları en yüksek öncelikle işlenir. ⚠️ Kullanılmalıdır yalnızca kimlik doğrulama kodları için.
sendTime
Zamanlanmış SMS teslim saati. Biçim: Y-m-d H:i (örneğin: "2026-02-01 23:30" ). Gelecekte olmalıdır. Belirtilmezse hemen gönderilir.
callbackUrl
Bu SMS isteğine özel geri çağırma URL'si. Yalnızca API uygulamasında genel varsayılan geri çağırma URL'si ayarlanmışsa çalışır.
Notlar
OTP mesajları yalnızca giriş, doğrulama ve parola sıfırlama gibi kimlik doğrulama işlemleri içindir.
Yanlış kullanılan otp parametresi teslimat veya hesap kısıtlamalarına neden olabilir.
Yanıt Durumu
statusID
Açıklama
0
SMS Gönderildi
10
brandID bulunamadı
20
Numaralar bulunamadı
30
Mesaj metni boş
40
Yetersiz SMS bakiyesi
50
Geçerli numara bulunamadı
60
Geçersiz sendTime biçimi. Y-m-d H:i kullanın
90
JSON Hatası
99
Genel Hata
⚠️ Sınırlar ve Notlar
En büyük istek gövdesi: 100 MB → Bu boyutu aşan istekler reddedilir.
Cloudflare proxy zaman aşımı: 100 saniye → Daha uzun istekler 524 Timeout döndürür.
Zaman aşımı ve bellek sorunlarını önlemek için büyük SMS isteklerini küçük parçalara bölün.
Testlerimizde SMS başarıyla gönderildi: tek istekte 500.000 numaraya kadar . Daha fazlası bellek, zaman aşımı veya istek boyutu sorunlarına yol açabilir. Gerçek sınırlar metin uzunluğuna, kodlamaya ve sunucu yüküne bağlıdır.
Öneri:
Güvenli ve kararlı çalışma için istekleri sınırlayın: paket başına yaklaşık 100.000 numara .
İstek Başlıkları 2
Anahtar
Değer
Kaynak
key
YOUR_API_KEY
Kimlik Doğrulama
Content-Type
application/json
Başlık
İstek Gövdesi JSON
İstek Gövdesi
{
"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)
}
Cep telefonu numaraları dizisi. Uluslararası biçimde olmalıdır olmadan 00 veya + . Örnek: ["9955XXXXXXXX","9955XXXXXXXX"]
text
SMS içeriği. Tüm Unicode karakterleri desteklenir.
İsteğe Bağlı Parametreler (JSON Gövdesi)
Parametre
Açıklama
stopList
false — engelleme listesi kontrolünü kapatır. Numara listede olsa da mesaj gönderilir.
otp
true — mesajı OTP (tek kullanımlık parola / doğrulama kodu) olarak işaretler. OTP mesajları en yüksek öncelikle işlenir. ⚠️ Kullanılmalıdır yalnızca kimlik doğrulama kodları için.
sendTime
Zamanlanmış SMS teslim saati. Biçim: Y-m-d H:i (örneğin: "2026-02-01 23:30" ). Gelecekte olmalıdır. Belirtilmezse hemen gönderilir.
callbackUrl
Bu SMS isteğine özel geri çağırma URL'si. Yalnızca API uygulamasında genel varsayılan geri çağırma URL'si ayarlanmışsa çalışır.
Notlar
OTP mesajları yalnızca giriş, doğrulama ve parola sıfırlama gibi kimlik doğrulama işlemleri içindir.
Yanlış kullanılan otp parametresi teslimat veya hesap kısıtlamalarına neden olabilir.
Yanıt Durumu
statusID
Açıklama
0
SMS Gönderildi
10
brandID bulunamadı
20
Numaralar bulunamadı
30
Mesaj metni boş
40
Yetersiz SMS bakiyesi
50
Geçerli numara bulunamadı
60
Geçersiz sendTime biçimi. Y-m-d H:i kullanın
90
JSON Hatası
99
Genel Hata
⚠️ Sınırlar ve Notlar
En büyük istek gövdesi: 100 MB → Bu boyutu aşan istekler reddedilir.
Cloudflare proxy zaman aşımı: 100 saniye → Daha uzun istekler 524 Timeout döndürür.
Zaman aşımı ve bellek sorunlarını önlemek için büyük SMS isteklerini küçük parçalara bölün.
API uygulama ayarlarında tek ortak adres vardır: HTTPS Geri Çağırma URL'si . Teslim raporları, SMS markası etkinleştirme bildirimleri ve gelecekteki API olayları aynı adrese gönderilir: GET isteği .
Kullanın: event parametresini bildirim türünü belirlemek için. Başarılı işlemden sonra döndürün: 2xx HTTP durumu.
Ortak Parametreler
Parametre
Açıklama
key
API uygulama ayarlarındaki geri çağırma doğrulama anahtarı
Telefon numaralarıyla yeni müşteri oluşturur. Müşteri numarası ( id yanıtta, cID iç sistemde) otomatik oluşturulur ve şirket içinde benzersizdir.
Gerekli İzin: customers.create . İstek gövdesi JSON olmalı ve Content-Type: application/json başlığı zorunludur.
İstek Gövdesi
Alan
Tür
Zorunlu
Açıklama
typeID
tam sayı
evet
Müşterinin hukuki türü uBill müşteri türleri listesinde olmalıdır ( 1 = gerçek kişi).
name
dize, en fazla 50
hayır
Müşteri adı.
personalNo
dize, en fazla 11
hayır
Kişisel numara veya şirket kimlik kodu; yalnızca harf ve rakam.
email
dize
hayır
Gönderildiğinde geçerli e-posta adresi olmalıdır.
birthDate
dize
hayır
Tarih şu biçimde: YYYY-MM-DD biçiminde.
lang
dize
hayır
Şunlardan biri: ka, en, ru . Varsayılan, şirket için ayarlanan müşteri dilidir.
address
dize, en fazla 50
hayır
Müşteri adresi.
column1, column2
dize, en fazla 50
hayır
Serbest ek alanlar.
numbers
dizi
evet
Müşterinin telefonları; en az biri zorunludur.
numbers[] nesnesi
Alan
Tür
Açıklama
number
dize
Ülke kodu olmadan yerel numara, 6–15 rakam.
mobile
dize
Tam uluslararası numara. Bu anahtar kullanıldığında ülke kodu numaranın başından çıkarılır.
countryCode
dize
Ülke kodu, varsayılan: +995.
isPrimary
0 veya 1
Ana numarayı işaretler. Hiçbiri işaretlenmezse ilk numara ana olur.
smsEnabled
0 veya 1
Numaranın SMS bildirimi alıp almayacağı, varsayılan: 1.
note
dize, en fazla 100
Numara için serbest not.
Tek numara kısa biçimde de gönderilebilir: {"mobile": "9955XXXXXXXX", "countryCode": "+995"} şunun yerine: numbers dizisi. Tekrarlar sessizce kaldırılır; aynı şirketin başka müşterisine ait numara reddedilir.
Yanıtlar
HTTP
statusID
Açıklama
201
0
Müşteri oluşturuldu, data yeni müşteriyi içerir.
400
400
Doğrulama başarısız, errors nesnesi her geçersiz alanı belirtir.
{
"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"
}
}
Numara Zaten Kullanılıyor 400
Yanıt · JSON
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"numbers": "+9955XXXXXXXX is already assigned to another customer"
}
}
Faturalama API / Müşteriler / Müşteriyi Getir
Müşteriyi Getir
API Anahtarı · Başlık
GEThttps://api.ubill.dev/v1/customers/100001
Bu uç noktanın Postman koleksiyonunda ayrı açıklaması yoktur.
{
"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"
}
Doğrulama Başarısız 400
Yanıt · 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 Zaten Kullanılıyor 400
Yanıt · JSON
{
"statusID": 400,
"message": "Account creation failed",
"data": null,
"errors": {
"account": [
"ეს MAC მისამართი უკვე მითითებულია სხვა ანგარიშზე"
]
}
}
Faturalama API / Hesaplar / Hesabı Getir
Hesabı Getir
API Anahtarı · Başlık
GEThttps://api.ubill.dev/v1/accounts/100001
Bu uç noktanın Postman koleksiyonunda ayrı açıklaması yoktur.