Запити до захищених кінцевих точок мають містити секретний ключ API компанії. Більшість приймає його в заголовку key ; деякі застарілі GET/XML-точки використовують key параметр запиту.
Не розкривайте ключ API
Зберігайте ключ у змінній середовища сервера. Не додавайте його до клієнтського JavaScript, мобільного застосунку чи публічного Git-репозиторію.
Заголовки запиту
key: YOUR_API_KEY
Content-Type: application/json
02
ПРАВИЛА
Формати й статуси
API переважно повертає відповіді JSON. Поле statusID визначає результат; успішний запит має значення 0 . Кінцева точка XML повертає відповідь XML.
0 SMS надіслано
1 Отримано
2 Не доставлено
3 Очікування статусу
4 Помилка
ДОВІДНИК API
Усі ресурси й кінцеві точки
Наведену інформацію синхронізовано з останньою версією публічної колекції Postman.
ГРУПА API
SMS API
11 кінцева точка
SMS API / Створення імені відправника
Створення імені відправника
Ключ API · Заголовок
POSThttps://api.ubill.dev/v1/sms/brandNameCreate
Статус відповіді
statusID
Опис
0
Ім’я відправника створено
10
Поле brandName порожнє
20
brandName має містити від 2 до 11 символів
30
brandName містить недозволені символи
40
brandName уже додано
50
Дочекайтеся підтвердження останнього brandName
60
The description field is required. Specify your website, Facebook/Instagram page or application and how you will use the brandName.
Секретний ключ API для автентифікації запитів. Перегляд і керування — у налаштуваннях компанії.
brandID
Унікальний ідентифікатор бренду в системі.
numbers
Мобільні номери через кому. Мають бути в міжнародному форматі без 00 або +.
text
Текст SMS. Підтримуються всі символи Unicode.
Необов’язкові параметри
Параметр
Опис
stopList
stopList=false — вимикає перевірку стоп-списку. Повідомлення буде надіслано навіть на номер у списку.
otp
otp=true — позначає повідомлення як OTP (одноразовий пароль / код перевірки). OTP обробляються з найвищим пріоритетом. ⚠️ Слід використовувати лише для кодів автентифікації.
sendTime
Запланований час доставки SMS. Формат: Y-m-d H:i (наприклад: 2026-02-01 23:30). Зазначений час має бути в майбутньому. Якщо не вказано, надсилається негайно.
callbackUrl
Окрема URL-адреса зворотного виклику для цього запиту. Працює лише за наявності глобальної типової адреси в налаштуваннях API-застосунку.
Примітки
OTP призначені виключно для автентифікації: входу, перевірки, скидання пароля.
Неправильне використання otp параметра може призвести до обмежень доставки чи облікового запису.
Масив мобільних номерів. Мають бути в міжнародному форматі без 00 або + . Приклад: ["9955XXXXXXXX","9955XXXXXXXX"]
text
Текст SMS. Підтримуються всі символи Unicode.
Необов’язкові параметри (тіло JSON)
Параметр
Опис
stopList
false — вимикає перевірку стоп-списку. Повідомлення буде надіслано навіть на номер у списку.
otp
true — позначає повідомлення як OTP (одноразовий пароль / код перевірки). OTP обробляються з найвищим пріоритетом. ⚠️ Слід використовувати лише для кодів автентифікації.
sendTime
Запланований час доставки SMS. Формат: Y-m-d H:i (наприклад: "2026-02-01 23:30" ). Має бути в майбутньому. Якщо не вказано — надсилається негайно.
callbackUrl
Окрема URL-адреса зворотного виклику для цього запиту. Працює лише за наявності глобальної типової адреси в налаштуваннях API-застосунку.
Примітки
OTP призначені виключно для автентифікації: входу, перевірки, скидання пароля.
Неправильне використання otp параметра може призвести до обмежень доставки чи облікового запису.
Розбивайте великі пакети SMS на менші запити, щоб уникнути тайм-аутів і проблем пам’яті.
Використовуйте stopList щоб не надсилати на заблоковані номери.
Практичне спостереження під час тестування:
У наших тестах SMS успішно надсилалися на до 500 000 номерів в одному запиті . Більша кількість може спричинити проблеми пам’яті, часу очікування чи розміру запиту. Фактичні межі залежать від довжини тексту, кодування й навантаження сервера.
Рекомендація:
Для безпечної й надійної роботи рекомендовано обмежитися приблизно 100 000 номерів у пакеті .
Заголовки запиту 2
Ключ
Значення
Джерело
key
YOUR_API_KEY
Автентифікація
Content-Type
application/json
Заголовок
Тіло запиту JSON
Тіло запиту
{
"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)
}
Масив мобільних номерів. Мають бути в міжнародному форматі без 00 або + . Приклад: ["9955XXXXXXXX","9955XXXXXXXX"]
text
Текст SMS. Підтримуються всі символи Unicode.
Необов’язкові параметри (тіло JSON)
Параметр
Опис
stopList
false — вимикає перевірку стоп-списку. Повідомлення буде надіслано навіть на номер у списку.
otp
true — позначає повідомлення як OTP (одноразовий пароль / код перевірки). OTP обробляються з найвищим пріоритетом. ⚠️ Слід використовувати лише для кодів автентифікації.
sendTime
Запланований час доставки SMS. Формат: Y-m-d H:i (наприклад: "2026-02-01 23:30" ). Має бути в майбутньому. Якщо не вказано — надсилається негайно.
callbackUrl
Окрема URL-адреса зворотного виклику для цього запиту. Працює лише за наявності глобальної типової адреси в налаштуваннях API-застосунку.
Примітки
OTP призначені виключно для автентифікації: входу, перевірки, скидання пароля.
Неправильне використання otp параметра може призвести до обмежень доставки чи облікового запису.
У налаштуваннях API-застосунку є спільна HTTPS-адреса зворотного виклику . Звіти про доставку, сповіщення про активацію бренду та майбутні події надсилаються на цю адресу через GET-запит .
Використовуйте event параметр для визначення типу сповіщення. Після успішної обробки повертайте будь-який 2xx статус HTTP.
Спільні параметри
Параметр
Опис
key
Ключ перевірки зворотного виклику з налаштувань API
Створює клієнта разом із номерами телефонів. Номер клієнта ( id у відповіді, cID всередині) генерується автоматично й унікальний у межах компанії.
Необхідний дозвіл: customers.create . Тіло запиту має бути JSON, а Content-Type: application/json заголовок обов’язковий.
Тіло запиту
Поле
Тип
Обов’язково
Опис
typeID
ціле число
так
Правовий тип клієнта має бути в переліку типів uBill ( 1 = фізична особа).
name
рядок, до 50
ні
Ім’я клієнта.
personalNo
рядок, до 11
ні
Особистий номер або код компанії, лише літери й цифри.
email
рядок
ні
Якщо надано, має бути коректною email-адресою.
birthDate
рядок
ні
Дата у YYYY-MM-DD форматі.
lang
рядок
ні
Одне зі значень ka, en, ru . Типово використовується мова клієнта з налаштувань компанії.
address
рядок, до 50
ні
Адреса клієнта.
column1, column2
рядок, до 50
ні
Довільні додаткові поля.
numbers
масив
так
Телефони клієнта, потрібен щонайменше один.
об’єкт numbers[]
Поле
Тип
Опис
number
рядок
Місцевий номер без коду країни, 6–15 цифр.
mobile
рядок
Повний міжнародний номер. За цього ключа код країни видаляється з початку номера.
countryCode
рядок
Код країни, типово +995.
isPrimary
0 або 1
Позначає основний номер. Якщо жоден не позначено, основним стає перший у списку.
smsEnabled
0 або 1
Чи отримує номер SMS-сповіщення, типово 1.
note
рядок, до 100
Довільна примітка до номера.
Один номер також можна передати скорочено {"mobile": "9955XXXXXXXX", "countryCode": "+995"} замість numbers масиву. Дублікати видаляються без сповіщення, а номер іншого клієнта тієї самої компанії відхиляється.
Відповіді
HTTP
statusID
Опис
201
0
Клієнта створено, data містить нового клієнта.
400
400
Перевірка не пройдена, errors об’єкт указує всі некоректні поля.
{
"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"
}
}
Номер уже використовується 400
Відповідь · JSON
{
"statusID": 400,
"message": "Validation failed",
"data": null,
"errors": {
"numbers": "+9955XXXXXXXX is already assigned to another customer"
}
}
Білінг API / Клієнти / Отримання клієнта
Отримання клієнта
Ключ API · Заголовок
GEThttps://api.ubill.dev/v1/customers/100001
Для цієї кінцевої точки в колекції Postman немає окремого опису.
Білінг API / Облікові записи / Створення облікового запису
Створення облікового запису
Ключ API · Заголовок
POSThttps://api.ubill.dev/v1/accounts/create
Створює обліковий запис (послугу) для наявного клієнта. Номер ( id у відповіді) генерується з налаштувань cID компанії так само, як у вебінтерфейсі uBill.
Необхідний дозвіл: accounts.create . Тіло запиту має бути JSON, а Content-Type: application/json заголовок обов’язковий.
Тіло запиту
Поле
Тип
Обов’язково
Опис
customerID
ціле число
так
Номер клієнта, якому належить запис, той самий id що повертають клієнтські кінцеві точки.
name
рядок, до 50
ні
Назва облікового запису.
birthDate
рядок
ні
Дата у YYYY-MM-DD форматі.
areaID
ціле число
ні
Ідентифікатор населеного пункту в переліку районів uBill.
address
рядок, до 50
ні
Адреса надання послуги.
geoLocation
рядок, до 100
ні
Координати у 41.732438,44.7688134 форматі.
column1, column2
рядок, до 50
ні
Довільні додаткові поля.
tariffID
ціле число
ні
Номер тарифу компанії.
groupID
ціле число
ні
Номер групи чи філії компанії.
tagsID
масив цілих чисел
ні
Номери міток компанії, прикріплених до запису.
numbers
масив
ні
Телефони запису описуються так само, як для клієнта. На відміну від клієнта, запис можна створити без номера.
Поля залежно від модуля
Поля зчитуються лише за активного відповідного модуля компанії.
Поле
Модуль
Обов’язково
Опис
mac
Мережа
так
MAC-адреса пристрою, унікальна в межах компанії.
onuMac
Мережа
ні
MAC-адреса ONU, унікальна в межах компанії.
ipRangeID
Мережа
так
Номер діапазону IP NAS. Перша вільна адреса автоматично призначається запису й повертається як ip.
stbMac
IPTV
ні
MAC-адреса STB, унікальна в межах компанії.
gpsProviderID
GPS track
так
Номер GPS-провайдера компанії.
gpsTrackIdentifier
GPS track
ні
Ідентифікатор пристрою, унікальний у межах компанії.
SMS-сповіщення
Якщо ввімкнено SMS про створення запису, повідомлення надсилається на всі його номери з активними SMS, зі списанням балансу компанії. За недостатнього балансу запис усе одно створюється, а відповідь містить додаткове warning поле.
Відповіді
HTTP
statusID
Опис
201
0
Обліковий запис створено, data містить новий обліковий запис.
400
400
Перевірка не пройдена, errors об’єкт указує некоректні поля. Дублікати MAC-адрес і телефонів повідомляються так само.
{
"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"
}
Перевірку не пройдено 400
Відповідь · 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 уже використовується 400
Відповідь · JSON
{
"statusID": 400,
"message": "Account creation failed",
"data": null,
"errors": {
"account": [
"ეს MAC მისამართი უკვე მითითებულია სხვა ანგარიშზე"
]
}
}
Білінг API / Облікові записи / Отримання облікового запису
Отримання облікового запису
Ключ API · Заголовок
GEThttps://api.ubill.dev/v1/accounts/100001
Для цієї кінцевої точки в колекції Postman немає окремого опису.