Розробникам uBill REST API · v1 Робоче середовище

Повна документація API

Усі ресурси SMS і білінг API в одному місці: точні кінцеві точки, повні описи Postman, заголовки, тіла запитів, приклади відповідей і готовий код.

Почати інтеграцію
29 кінцева точка Автентифікація ключем API JSON / XML
POST /v1/sms/send
1curl --request POST \2  --url api.ubill.dev/v1/sms/send \3  --header 'key: ••••••••'
200 OK{ "statusID": 0, "message": "SMS Sent" }
ПОЧАТОК РОБОТИ

Робота з uBill API

UBill API надає програмний доступ до наших ресурсів. Інтегруйте сервіс у свою систему та легко спілкуйтеся з клієнтами.

Приклади API

Реалізації API різними мовами програмування з різних джерел.

Базова URL-адреса https://api.ubill.dev
Версія v1
Протокол HTTPS
Кодування UTF-8
01
БЕЗПЕКА

Автентифікація

Запити до захищених кінцевих точок мають містити секретний ключ 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

14 кінцева точка

SMS API / Створення імені відправника

Створення імені відправника

Ключ API · Заголовок
POST https://api.ubill.dev /v1/sms/brandNameCreate

Статус відповіді

statusID Опис
0 Ім’я відправника створено
10 Поле brandName порожнє
20 brandName має містити від 2 до 11 символів
30 brandName містить недозволені символи
40 brandName уже додано
50 Дочекайтеся підтвердження останнього brandName
60The description field is required. Specify your website, Facebook/Instagram page or application and how you will use the brandName.
61The description must not exceed 500 characters
90 Помилка JSON
99 Загальна помилка

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Тіло запиту JSON

Тіло запиту
{
    "brandName" : "test"
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/sms/brandNameCreate' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "brandName" : "test"
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/brandNameCreate',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "brandName" : "test"
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/brandNameCreate',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"brandName\" : \"test\"\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Створення імені відправника Приклад
Відповідь · JSON
{
    "statusID": 0,
    "brandID": 1,
    "message": "BrandName Created"
}
SMS API / Видалення імені відправника

Видалення імені відправника

Ключ API · Заголовок
POST https://api.ubill.dev /v1/sms/brandNameDelete

Статус відповіді

statusID Опис
0 Ім’я відправника видалено
10 Ім’я відправника не знайдено
90 Помилка JSON
99 Загальна помилка

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Тіло запиту JSON

Тіло запиту
{
    "brandID": 2
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/sms/brandNameDelete' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "brandID": 2
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/brandNameDelete',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "brandID": 2
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/brandNameDelete',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"brandID\": 2\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Видалення імені відправника Приклад
Відповідь · JSON
{
    "statusID": 0,
    "brandID": "2",
    "message": "BrandName Deleted"
}
SMS API / Отримання всіх імен відправників

Отримання всіх імен відправників

Ключ API · Заголовок
GET https://api.ubill.dev /v1/sms/brandNames

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/sms/brandNames' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/brandNames',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/brandNames',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Отримання всіх імен відправників Приклад
Відповідь · JSON
{
    "statusID": 0,
    "data": [
        {
            "id": "1",
            "name": "test",
            "authorized": "1",
            "createdAt": "2020-11-14 20:42:44"
        },
        {
            "id": "2",
            "name": "test2",
            "authorized": "2",
            "createdAt": "2021-03-27 00:22:38"
        }
    ]
}
SMS API / Надіслати SMS

Надіслати SMS

Ключ API · Параметр запиту
GET https://api.ubill.dev /v1/sms/send?key=YOUR_API_KEY&brandID=1&numbers=9955XXXXXXXX,9955XXXXXXXX&text=message&stopList=false

Обов’язкові параметри

Параметр Опис
key Секретний ключ 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 параметра може призвести до обмежень доставки чи облікового запису.


Статус відповіді

statusID Опис
0 SMS надіслано
10 brandID не знайдено
20 Номери не знайдено
30 Порожній текст повідомлення
40 Недостатньо SMS
50 Коректні номери не знайдено
60 Некоректний формат sendTime. Використовуйте Y-m-d H:i
90 Помилка JSON
99 Загальна помилка

⚠️ Обмеження методу GET

  • API не встановлює жорсткого ліміту на кількість номерів одержувачів.

  • Фактичні обмеження визначаються граничним розміром URL і заголовків HTTP (Cloudflare, проксі, браузери).

Практичні обмеження

  • ✅ До приблизно 1500 номерів у запиті працює надійно.

  • ⚠️ Приблизно 2000 і більше номерів можуть спричинити Header overflow помилки.

  • Ці помилки виникають до надходження запиту до API , на рівні HTTP / проксі.

Рекомендація

  • Використовуйте GET лише для малих і середніх запитів.

  • Для великих списків завжди використовуйте POST.

OTP recipient limits and partial batches

In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.

A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount та rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown або otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.

If all recipients are rejected, statusID=47, smsID=null та acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.

Параметри URL 5

keyqueryYOUR_API_KEY
brandIDquery1
numbersquery9955XXXXXXXX,9955XXXXXXXX
textquerymessage
stopListqueryfalse

Приклади коду

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'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/send?key=YOUR_API_KEY&brandID=1&numbers=9955XXXXXXXX,9955XXXXXXXX&text=message&stopList=false',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET'
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/send?key=YOUR_API_KEY&brandID=1&numbers=9955XXXXXXXX,9955XXXXXXXX&text=message&stopList=false',
  {
  method: 'GET'
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

3 приклад
Надіслати SMS Приклад
Відповідь · JSON
{
    "statusID": 0,
    "smsID": "117345",
    "message": "SMS Sent"
}
OTP partial success 200
Відповідь · JSON
{
  "statusID": 0,
  "smsID": 123,
  "message": "SMS partially sent",
  "acceptedCount": 1,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
OTP all recipients restricted 200
Відповідь · JSON
{
  "statusID": 47,
  "smsID": null,
  "message": "OTP recipient protection limit exceeded",
  "acceptedCount": 0,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
SMS API / Надіслати SMS

Надіслати SMS

Ключ API · Заголовок
POST https://api.ubill.dev /v1/sms/send

Заголовки

Ключ Значення
key Ваш секретний ключ API
Content-Type application/json

Обов’язкові параметри (тіло JSON)

Параметр Опис
brandID Унікальний ідентифікатор бренду в системі.
numbers Масив мобільних номерів. Мають бути в міжнародному форматі без 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 параметра може призвести до обмежень доставки чи облікового запису.

Статус відповіді

statusID Опис
0 SMS надіслано
10 brandID не знайдено
20 Номери не знайдено
30 Порожній текст повідомлення
40 Недостатньо SMS
50 Коректні номери не знайдено
60 Некоректний формат sendTime. Використовуйте Y-m-d H:i
90 Помилка JSON
99 Загальна помилка

⚠️ Обмеження та примітки

  • Максимальний розмір тіла запиту: 100 MB → Більші запити відхиляються.

  • Час очікування проксі Cloudflare: 100 секунд → Довші запити повертають 524 Timeout.

  • Розбивайте великі пакети SMS на менші запити, щоб уникнути тайм-аутів і проблем пам’яті.

  • Використовуйте stopList щоб не надсилати на заблоковані номери.

Практичне спостереження під час тестування:

У наших тестах SMS успішно надсилалися на до 500 000 номерів в одному запиті . Більша кількість може спричинити проблеми пам’яті, часу очікування чи розміру запиту. Фактичні межі залежать від довжини тексту, кодування й навантаження сервера.

Рекомендація:

Для безпечної й надійної роботи рекомендовано обмежитися приблизно 100 000 номерів у пакеті .

OTP recipient limits and partial batches

In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.

A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount та rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown або otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.

If all recipients are rejected, statusID=47, smsID=null та acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/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)
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/sms/send' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "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)
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "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)
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/send',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"brandID\": 1,\n    \"numbers\": [\n        9955XXXXXXXX,\n        9955XXXXXXXX\n    ],\n    \"text\": \"Message\",\n    \"stopList\": false, // Enable/disable checking numbers in the stop list\n    \"sendTime\": \"2026-02-01 23:01\" // sendTime (optional)\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

3 приклад
Надіслати SMS Приклад
Відповідь · JSON
{
    "statusID": 0,
    "smsID": 111,
    "message": "SMS Sended"
}
OTP partial success 200
Відповідь · JSON
{
  "statusID": 0,
  "smsID": 123,
  "message": "SMS partially sent",
  "acceptedCount": 1,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
OTP all recipients restricted 200
Відповідь · JSON
{
  "statusID": 47,
  "smsID": null,
  "message": "OTP recipient protection limit exceeded",
  "acceptedCount": 0,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
SMS API / Надсилання SMS — різні тексти

Надсилання SMS — різні тексти

Ключ API · Заголовок
POST https://api.ubill.dev /v1/sms/send

Заголовки

Ключ Значення
key Ваш секретний ключ API
Content-Type application/json

Обов’язкові параметри (тіло JSON)

Параметр Опис
brandID Унікальний ідентифікатор бренду в системі.
numbers Масив мобільних номерів. Мають бути в міжнародному форматі без 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 параметра може призвести до обмежень доставки чи облікового запису.


Статус відповіді

statusID Опис
0 SMS надіслано
10 brandID не знайдено
20 Номери не знайдено
30 Порожній текст повідомлення
40 Недостатньо SMS
50 Коректні номери не знайдено
60 Некоректний формат sendTime. Використовуйте Y-m-d H:i
90 Помилка JSON
99 Загальна помилка

⚠️ Обмеження та примітки

  • Максимальний розмір тіла запиту: 100 MB → Більші запити відхиляються.

  • Час очікування проксі Cloudflare: 100 секунд → Довші запити повертають 524 Timeout.

  • Розбивайте великі пакети SMS на менші запити, щоб уникнути тайм-аутів і проблем пам’яті.

  • Використовуйте stopList щоб не надсилати на заблоковані номери.

Практичне спостереження під час тестування:

SMS на одержувача Максимум номерів у запиті
1 400,000
2 200,000
3 150,000
4 120,000
5 100,000
6 50,000

Фактичні межі залежать від довжини тексту, кодування й навантаження сервера.

Рекомендація:

Для надійної роботи дотримуйтеся наведених меж номерів у пакеті відповідно до кількості з’єднаних SMS.

OTP recipient limits and partial batches

In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.

A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount та rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown або otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.

If all recipients are rejected, statusID=47, smsID=null та acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Тіло запиту JSON

Тіло запиту
{
    "brandID": 1,
    "numbers": [
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, Nicholas"
        },
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, George"
        }
    ],
    "stopList": false, // Enable/disable checking numbers in the stop list
    "sendTime": "2026-02-01 23:01" // sendTime (optional)
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/sms/send' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "brandID": 1,
    "numbers": [
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, Nicholas"
        },
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, George"
        }
    ],
    "stopList": false, // Enable/disable checking numbers in the stop list
    "sendTime": "2026-02-01 23:01" // sendTime (optional)
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "brandID": 1,
    "numbers": [
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, Nicholas"
        },
        {
            "number": 9955XXXXXXXX,
            "text": "Hello, George"
        }
    ],
    "stopList": false, // Enable/disable checking numbers in the stop list
    "sendTime": "2026-02-01 23:01" // sendTime (optional)
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/send',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"brandID\": 1,\n    \"numbers\": [\n        {\n            \"number\": 9955XXXXXXXX,\n            \"text\": \"Hello, Nicholas\"\n        },\n        {\n            \"number\": 9955XXXXXXXX,\n            \"text\": \"Hello, George\"\n        }\n    ],\n    \"stopList\": false, // Enable/disable checking numbers in the stop list\n    \"sendTime\": \"2026-02-01 23:01\" // sendTime (optional)\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

3 приклад
Надсилання SMS — різні тексти Приклад
Відповідь · JSON
{
    "statusID": 0,
    "smsID": 111,
    "message": "SMS Sended"
}
OTP partial success 200
Відповідь · JSON
{
  "statusID": 0,
  "smsID": 123,
  "message": "SMS partially sent",
  "acceptedCount": 1,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
OTP all recipients restricted 200
Відповідь · JSON
{
  "statusID": 47,
  "smsID": null,
  "message": "OTP recipient protection limit exceeded",
  "acceptedCount": 0,
  "rejectedCount": 1,
  "rejectedNumbers": [
    {
      "index": 0,
      "number": "5XXXXXXXX",
      "statusID": 47,
      "reason": "otpCooldown",
      "retryAfter": 30
    }
  ]
}
SMS API / Надсилання SMS через XML

Надсилання SMS через XML

Ключ API · Параметр запиту
POST https://api.ubill.dev /v1/sms/sendXml?key=YOUR_API_KEY

Статус відповіді

statusID Опис
0 SMS надіслано
10 brandID не знайдено
20 Номери не знайдено
30 Порожній текст повідомлення
40 Недостатньо SMS
50 Коректні номери не знайдено
90 Помилка JSON
99 Загальна помилка

⚠️ Обмеження та примітки

  • Максимальний розмір тіла запиту: 100 MB → Більші запити відхиляються.

  • Час очікування проксі Cloudflare: 100 секунд → Довші запити повертають 524 Timeout.

  • Розбивайте великі пакети SMS на менші запити, щоб уникнути тайм-аутів і проблем пам’яті.

  • Використовуйте stopList щоб не надсилати на заблоковані номери.

OTP recipient limits and partial batches

In automatic protection mode, OTP cooldown and per-number limits reject only the affected recipient rows. Other recipients continue; the application is not paused by these two rules. Overall volume and unique OTP recipient limits remain application-wide. The owner can disable additional OTP protection per application.

A mixed batch returns statusID=0, a valid smsID, message=SMS partially sent, acceptedCount, rejectedCount та rejectedNumbers. Each rejection contains the original zero-based request index, normalized number, statusID=47, reason (otpCooldown або otpNumberLimit) and retryAfter seconds. If both rules apply, the later-release reason is returned. Only accepted rows are queued, charged and counted against limits. Retry only rejected indexes; resending the full batch can duplicate accepted SMS.

If all recipients are rejected, statusID=47, smsID=null та acceptedCount=0. The HTTP Retry-After header gives the earliest recipient retry time. Rejected retries do not extend it. A separate whole-request failure queues nothing. XML uses <rejectedNumbers><recipient>...</recipient></rejectedNumbers> with the same fields. Responses without filtering keep their existing shape.

Параметри URL 1

keyqueryYOUR_API_KEY

Тіло запиту XML

Тіло запиту
<?xml version="1.0" encoding="UTF-8"?>
<request>
    <brandID>1</brandID>
    <numbers>9955XXXXXXXX</numbers>
    <text>test</text>
    <stopList>false</stopList> <!-- Enable/disable checking numbers in the stop list -->
</request>

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/sms/sendXml?key=YOUR_API_KEY' \
  --data '<?xml version="1.0" encoding="UTF-8"?>
<request>
    <brandID>1</brandID>
    <numbers>9955XXXXXXXX</numbers>
    <text>test</text>
    <stopList>false</stopList> <!-- Enable/disable checking numbers in the stop list -->
</request>'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/sendXml?key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
<?xml version="1.0" encoding="UTF-8"?>
<request>
    <brandID>1</brandID>
    <numbers>9955XXXXXXXX</numbers>
    <text>test</text>
    <stopList>false</stopList> <!-- Enable/disable checking numbers in the stop list -->
</request>
BODY
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/sendXml?key=YOUR_API_KEY',
  {
  method: 'POST',
  body: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<request>\n    <brandID>1</brandID>\n    <numbers>9955XXXXXXXX</numbers>\n    <text>test</text>\n    <stopList>false</stopList> <!-- Enable/disable checking numbers in the stop list -->\n</request>"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

3 приклад
Надсилання SMS через XML Приклад
Відповідь · XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <statusID>0</statusID>
    <smsID>11574</smsID>
    <message>SMS Sent</message>
</response>
OTP partial success 200
Відповідь · XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <statusID>0</statusID>
    <smsID>123</smsID>
    <message>SMS partially sent</message>
    <acceptedCount>1</acceptedCount>
    <rejectedCount>1</rejectedCount>
    <rejectedNumbers>
        <recipient>
            <index>0</index>
            <number>599000001</number>
            <statusID>47</statusID>
            <reason>otpCooldown</reason>
            <retryAfter>30</retryAfter>
        </recipient>
    </rejectedNumbers>
</response>
OTP all recipients restricted 200
Відповідь · XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <statusID>47</statusID>
    <smsID>null</smsID>
    <message>OTP recipient protection limit exceeded</message>
    <acceptedCount>0</acceptedCount>
    <rejectedCount>1</rejectedCount>
    <rejectedNumbers>
        <recipient>
            <index>0</index>
            <number>599000001</number>
            <statusID>47</statusID>
            <reason>otpCooldown</reason>
            <retryAfter>30</retryAfter>
        </recipient>
    </rejectedNumbers>
</response>
SMS API / Звіт про доставку

Звіт про доставку

Ключ API · Заголовок
GET https://api.ubill.dev /v1/sms/report/{smsID}

Статуси

statusID Опис
0 Надіслано
1 Отримано
2 Не доставлено
3 Очікування статусу
4 Помилка

Параметри URL 1

smsIDpath{smsID}

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/sms/report/{smsID}' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/report/{smsID}',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/report/{smsID}',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Звіт про доставку Приклад
Відповідь · JSON
{
    "statusID": 0,
    "result": [
        {
            "number": "9955XXXXXXXX",
            "statusID": "0"
        },
        {
            "number": "9955XXXXXXXX",
            "statusID": "0"
        }
    ]
}
SMS API / Отримання балансу SMS

Отримання балансу SMS

Ключ API · Параметр запиту
GET https://api.ubill.dev /v1/sms/balance?key=YOUR_API_KEY

Параметри URL 1

keyqueryYOUR_API_KEY

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/sms/balance?key=YOUR_API_KEY'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/balance?key=YOUR_API_KEY',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET'
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/balance?key=YOUR_API_KEY',
  {
  method: 'GET'
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Отримання балансу SMS Приклад
Відповідь · JSON
{
    "statusID": 0,
    "sms": 5000
}
РЕСУРС

Incoming SMS

3 кінцева точка

SMS API / Incoming SMS / Get Incoming SMS

Get Incoming SMS

Ключ API · Заголовок
GET https://api.ubill.dev /v1/sms/inbound

Incoming SMS — receive messages through the API

Required application permission: sms.inbound. Enable Incoming SMS access in the company's API application settings and pass that application's API key in the key header. Only messages assigned to the key's company are returned. A client-supplied company ID cannot change this scope. IP restrictions and API rate limits still apply.

Without date parameters, returns the last 24 hours by provider send time. Results are in receipt order, oldest first, rather than sorted by UUID or sender timestamp. Dates in sendAt and response metadata are UTC; date-only filters use the Asia/Tbilisi calendar.

Query parameters

Параметр Тип Обов’язково Опис
dateString Ні One whole Tbilisi calendar day, for example 2026-11-02. Cannot be combined with from або to.
fromString Ні Inclusive start. Accepts YYYY-MM-DD or an RFC 3339 timestamp with timezone and up to 6 fractional digits. Defaults to 24 hours before the end.
toString Ні Defaults to now. A date includes its entire Tbilisi calendar day; a timestamp is an exclusive end.
limitInteger Ні Batch size: 1–100; default 50.
cursorString (UUIDv4) Ні Use the previous response's meta.nextCursor to retrieve later records. Unknown or other-company cursors return HTTP 404.

Date examples

GET /v1/sms/inbound
GET /v1/sms/inbound?date=2026-11-02
GET /v1/sms/inbound?from=2026-11-01&to=2026-11-02
GET /v1/sms/inbound?from=2026-11-02T00%3A00%3A00%2B04%3A00&to=2026-11-03T00%3A00%3A00%2B04%3A00

URL-encode timezone offsets, especially + as %2B. Invalid, conflicting or reversed date filters return HTTP 400.

Message fields

Поле Тип Опис
eventIDString (UUIDv4)Stable UBill-generated public message ID. It is independent of the SMS provider's message ID and is also used in callbacks. Use it to deduplicate messages.
fromStringSubscriber number in local nine-digit format, for example 5XXXXXXXX.
toStringReceiving short number.
textStringIncoming message text. Unicode and line breaks are preserved.
noSmsBooleanEffective NO SMS policy configured for the short number by the administrator; not the provider's flag.
sendAtString / nullProvider send time in UTC, with microsecond precision. May be null for older imported messages.

Provider IDs and internal numeric row IDs are not exposed. Other applications of the same company with sms.inbound access see the same public message ID.

Pagination and polling

meta.count is the number of messages in this batch; meta.hasMore indicates another batch. For the next page, reuse meta.from, meta.to та meta.nextCursor so the date window remains fixed. On an empty batch, nextCursor retains the supplied cursor, or is null if no cursor was supplied.

For polling, omit dates and send the last cursor to fetch newer records within the latest 24-hour window. Persist public eventID values to handle duplicates. Use explicit dates when retrieving older history.

Errors

HTTP 400: invalid dates, limit or cursor format. HTTP 401: invalid API key or missing sms.inbound permission. HTTP 403: IP not allowed. HTTP 404: unknown or other-company cursor. HTTP 429: rate limit exceeded.

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Acceptapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/sms/inbound' \
  --header 'key: YOUR_API_KEY' \
  --header 'Accept: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/inbound',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Accept: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/inbound',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Accept': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

5 приклад
Last 24 hours 200
Відповідь · JSON
{
  "statusID": 0,
  "meta": {
    "from": "2026-11-01T09:00:00.000000Z",
    "to": "2026-11-02T09:00:00.000000Z",
    "limit": 50,
    "count": 1,
    "hasMore": false,
    "nextCursor": "29a24670-e631-4bf3-b593-ea35df838115"
  },
  "result": [
    {
      "eventID": "29a24670-e631-4bf3-b593-ea35df838115",
      "from": "5XXXXXXXX",
      "to": "90566",
      "text": "Example incoming SMS",
      "noSms": false,
      "sendAt": "2026-11-02T08:30:00.396288Z"
    }
  ]
}
No messages 200
Відповідь · JSON
{
  "statusID": 0,
  "meta": {
    "from": "2026-11-01T09:00:00.000000Z",
    "to": "2026-11-02T09:00:00.000000Z",
    "limit": 50,
    "count": 0,
    "hasMore": false,
    "nextCursor": null
  },
  "result": []
}
Invalid date 400
Відповідь · JSON
{
  "statusID": 400,
  "message": "Invalid date",
  "result": []
}
Permission denied 401
Відповідь · JSON
{
  "statusID": 401,
  "message": "Invalid API key or permission denied",
  "result": []
}
Cursor not found 404
Відповідь · JSON
{
  "statusID": 404,
  "message": "Cursor not found",
  "result": []
}
SMS API / Incoming SMS / Get Incoming SMS by eventID

Get Incoming SMS by eventID

Ключ API · Заголовок
GET https://api.ubill.dev /v1/sms/inbound/{eventID}

Get one incoming SMS

Requires the application's sms.inbound permission and key header. Replace {eventID} with the public UUID returned by the incoming-message list or callback.

The lookup is restricted to the API key's company and has no date restriction. An invalid UUID returns HTTP 400; an unknown, provider-owned or other-company UUID returns HTTP 404. The response contains statusID and a result array with one message object.

Параметри URL 1

eventIDpath{eventID}

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Acceptapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/sms/inbound/{eventID}' \
  --header 'key: YOUR_API_KEY' \
  --header 'Accept: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/sms/inbound/{eventID}',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Accept: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/sms/inbound/{eventID}',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Accept': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

3 приклад
Incoming message 200
Відповідь · JSON
{
  "statusID": 0,
  "result": [
    {
      "eventID": "29a24670-e631-4bf3-b593-ea35df838115",
      "from": "5XXXXXXXX",
      "to": "90566",
      "text": "Example incoming SMS",
      "noSms": false,
      "sendAt": "2026-11-02T08:30:00.396288Z"
    }
  ]
}
Invalid message ID 400
Відповідь · JSON
{
  "statusID": 400,
  "message": "Invalid ID",
  "result": []
}
Message not found 404
Відповідь · JSON
{
  "statusID": 404,
  "message": "Message not found",
  "result": []
}
SMS API / Incoming SMS / Incoming SMS Callback

Incoming SMS Callback

API event callback
POST https://example.com/callback

Incoming SMS callback

Set an HTTPS-адреса зворотного виклику for your API application and enable sms.inbound. When an incoming SMS is assigned to that company, uBill queues one delivery for each active, permitted application with a configured callback URL.

This event uses POST with a JSON body to the same callback URL used by delivery-status notifications. The event type is sms.inbound.received. Delivery-status and brand-activation events continue to use GET; a shared receiver should route by HTTP method and event type.

Authentication and fields

The application's callback key is sent both in the X-Webhook-Token header and the JSON key field. Validate it against your configured callback key. For legacy applications without a callback key, the existing API-key fallback is used.

Поле Тип Опис
eventStringsms.inbound.received
keyStringCallback authentication key.
eventIDString (UUIDv4)The same stable public message ID returned by the Incoming SMS API. It is not the provider's message ID.
fromStringSubscriber's local nine-digit number.
toStringReceiving short number.
textStringIncoming message, including Unicode and line breaks.
noSmsBooleanAdministrator-configured short-number NO SMS policy.
sendAtStringProvider send time in UTC with microsecond precision.

Acknowledgement and retries

After safely accepting the message, return any 2xx HTTP response. Delivery is at least once: store eventID with a unique constraint and return success for a message already accepted. A timed-out request may already have reached your server.

Network failures and non-2xx responses are retried, up to 5 HTTP attempts. Retry delays are 1 minute, 5 minutes, 30 minutes, then 2 hours; actual timing depends on worker scheduling. The message ID stays unchanged. The request timeout is 10 seconds. Redirects are not followed with the token or SMS content.

Before sending, uBill rechecks application activity, permission, company and callback URL. Removing access or disabling the app cancels pending delivery. Old messages are not automatically pushed when callbacks are first enabled; use the Incoming SMS API to retrieve history.

Заголовки запиту 2

Ключ Значення Джерело
Content-Typeapplication/json Заголовок
X-Webhook-TokenYOUR_CALLBACK_KEY Заголовок

Тіло запиту JSON

Тіло запиту
{
  "eventID": "29a24670-e631-4bf3-b593-ea35df838115",
  "from": "5XXXXXXXX",
  "to": "90566",
  "text": "Example incoming SMS",
  "noSms": false,
  "sendAt": "2026-11-02T08:30:00.396288Z",
  "event": "sms.inbound.received",
  "key": "YOUR_CALLBACK_KEY"
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://example.com/callback' \
  --header 'Content-Type: application/json' \
  --header 'X-Webhook-Token: YOUR_CALLBACK_KEY' \
  --data '{
  "eventID": "29a24670-e631-4bf3-b593-ea35df838115",
  "from": "5XXXXXXXX",
  "to": "90566",
  "text": "Example incoming SMS",
  "noSms": false,
  "sendAt": "2026-11-02T08:30:00.396288Z",
  "event": "sms.inbound.received",
  "key": "YOUR_CALLBACK_KEY"
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://example.com/callback',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
  "eventID": "29a24670-e631-4bf3-b593-ea35df838115",
  "from": "5XXXXXXXX",
  "to": "90566",
  "text": "Example incoming SMS",
  "noSms": false,
  "sendAt": "2026-11-02T08:30:00.396288Z",
  "event": "sms.inbound.received",
  "key": "YOUR_CALLBACK_KEY"
}
BODY,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Webhook-Token: YOUR_CALLBACK_KEY'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://example.com/callback',
  {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Token': 'YOUR_CALLBACK_KEY'
  },
  body: "{\n  \"eventID\": \"29a24670-e631-4bf3-b593-ea35df838115\",\n  \"from\": \"5XXXXXXXX\",\n  \"to\": \"90566\",\n  \"text\": \"Example incoming SMS\",\n  \"noSms\": false,\n  \"sendAt\": \"2026-11-02T08:30:00.396288Z\",\n  \"event\": \"sms.inbound.received\",\n  \"key\": \"YOUR_CALLBACK_KEY\"\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Accepted by your endpoint (example) 200
Відповідь · JSON
{
  "success": true
}
SMS API / Зворотні виклики подій API

Зворотні виклики подій API

Ключ API · Параметр запиту
GET https://example.com/callback?key=YourCallbackKey&event=sms.brand.activated&brandID=12&brandName=MyBrand&authorized=1&date=2026-08-10 15:30:00

Зворотні виклики подій API

У налаштуваннях API-застосунку є спільна HTTPS-адреса зворотного виклику . The event type determines the HTTP method and payload format; not every callback is a GET request.

Використовуйте event to route notifications. Return any 2xx HTTP status after safely accepting an event.

Підтримувані події

Подія Метод Fields
sms.delivery.updatedGET querykey, event, smsID, number, statusID, date
sms.brand.activatedGET querykey, event, brandID, brandName, authorized=1, date
sms.inbound.receivedPOST JSONkey, event, eventID, from, to, text, noSms, sendAt

GET callbacks authenticate with the application's callback key query parameter. Incoming SMS callbacks send that key in JSON and the X-Webhook-Token header and require sms.inbound access. GET date fields use Y-m-d H:i:s; incoming SMS sendAt uses UTC RFC 3339.

Приклад активації SMS-бренду

https://example.com/callback?key=YourCallbackKey&event=sms.brand.activated&brandID=12&brandName=MyBrand&authorized=1&date=2026-08-10%2015:30:00

See Incoming SMS → Incoming SMS Callback for the JSON body, authentication, retries and deduplication rules.

Параметри URL 6

keyqueryYourCallbackKey
eventquerysms.brand.activated
brandIDquery12
brandNamequeryMyBrand
authorizedquery1
datequery2026-08-10 15:30:00

Приклади коду

cURL · PHP · JavaScript

Приклади відповідей

0 приклад
Для цієї кінцевої точки немає прикладу відповіді.
SMS API / Зворотний виклик доставки SMS

Зворотний виклик доставки SMS

Ключ API · Параметр запиту
GET https://example.com/callback?key=YourCallbackKey&event=sms.delivery.updated&smsID=12345678&number=9955XXXXXXXX&statusID=1&date=2026-02-01 12:02:02

Автоматичний статус повідомлення (зворотний виклик)

SMS API дозволяє автоматично отримувати статуси надісланих повідомлень на сервері через Зворотний виклик механізму.

Коли статус змінюється (надіслано, отримано, не доставлено тощо), система надсилає GET-запит на вказану вами HTTPS-адресу .

Вимоги до URL зворотного виклику:

  • Має починатися з https://

  • Метод: GET

  • Задається в налаштуваннях API компанії

Параметри

Параметр Опис
key Ключ перевірки зворотного виклику для сервера
smsID Унікальний ідентифікатор повідомлення
number Мобільний номер одержувача (міжнародний формат)
statusID Код поточного статусу повідомлення
date Час оновлення статусу ( Y-m-d H:i:s)

Коди статусів

statusID Опис
0 Надіслано
1 Отримано
2 Не доставлено
3 Очікування статусу
4 Помилка

Приклад обробки зворотного виклику (PHP)

$key    = $_GET['key'] ?? null;
$smsID    = $_GET['smsID'] ?? null;
$number   = $_GET['number'] ?? null;
$statusID = $_GET['statusID'] ?? null;
$date     = $_GET['date'] ?? null;

// Validation: ensure the key matches your callback key
if ($key !== 'YourCallbackKey') {
    http_response_code(403);
    echo 'Forbidden';
    exit;
}

// Process the received status in your system
http_response_code(200);
echo 'OK';
?>

Параметри URL 6

keyqueryYourCallbackKey
eventquerysms.delivery.updated
smsIDquery12345678
numberquery9955XXXXXXXX
statusIDquery1
datequery2026-02-01 12:02:02

Приклади коду

cURL · PHP · JavaScript

Приклади відповідей

0 приклад
Для цієї кінцевої точки немає прикладу відповіді.
ГРУПА API

Білінг API

15 кінцева точка

РЕСУРС

Клієнти

6 кінцева точка

Білінг API / Клієнти / Отримання всіх клієнтів

Отримання всіх клієнтів

Ключ API · Заголовок
GET https://api.ubill.dev /v1/customers

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/customers' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

0 приклад
Для цієї кінцевої точки немає прикладу відповіді.
Білінг API / Клієнти / Створення клієнта

Створення клієнта

Ключ API · Заголовок
POST https://api.ubill.dev /v1/customers/create

Створює клієнта разом із номерами телефонів. Номер клієнта ( id in the response) is generated automatically and is unique inside the company.

Необхідний дозвіл: 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 масиву. Дублікати видаляються без сповіщення, а номер іншого клієнта тієї самої компанії відхиляється.

Відповіді

HTTPstatusID Опис
2010 Клієнта створено, data містить нового клієнта.
400400 Перевірка не пройдена, errors об’єкт указує всі некоректні поля.
50099 Клієнта не вдалося зберегти, нічого не записано.

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Тіло запиту JSON

Тіло запиту
{
    "typeID": 1,
    "name": "გიორგი მაისურაძე",
    "personalNo": "XXXXXXXXXXX",
    "email": "[email protected]",
    "birthDate": "1990-05-17",
    "lang": "ka",
    "address": "ვაჟა-ფშაველას 1",
    "column1": "",
    "column2": "",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1,
            "note": "პირადი"
        },
        {
            "mobile": "9955XXXXXXXX",
            "smsEnabled": 0,
            "note": "ბიოს"
        }
    ]
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/customers/create' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "typeID": 1,
    "name": "გიორგი მაისურაძე",
    "personalNo": "XXXXXXXXXXX",
    "email": "[email protected]",
    "birthDate": "1990-05-17",
    "lang": "ka",
    "address": "ვაჟა-ფშაველას 1",
    "column1": "",
    "column2": "",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1,
            "note": "პირადი"
        },
        {
            "mobile": "9955XXXXXXXX",
            "smsEnabled": 0,
            "note": "ბიოს"
        }
    ]
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "typeID": 1,
    "name": "გიორგი მაისურაძე",
    "personalNo": "XXXXXXXXXXX",
    "email": "[email protected]",
    "birthDate": "1990-05-17",
    "lang": "ka",
    "address": "ვაჟა-ფშაველას 1",
    "column1": "",
    "column2": "",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1,
            "note": "პირადი"
        },
        {
            "mobile": "9955XXXXXXXX",
            "smsEnabled": 0,
            "note": "ბიოს"
        }
    ]
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers/create',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"typeID\": 1,\n    \"name\": \"გიორგი მაისურაძე\",\n    \"personalNo\": \"XXXXXXXXXXX\",\n    \"email\": \"[email protected]\",\n    \"birthDate\": \"1990-05-17\",\n    \"lang\": \"ka\",\n    \"address\": \"ვაჟა-ფშაველას 1\",\n    \"column1\": \"\",\n    \"column2\": \"\",\n    \"numbers\": [\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"isPrimary\": 1,\n            \"smsEnabled\": 1,\n            \"note\": \"პირადი\"\n        },\n        {\n            \"mobile\": \"9955XXXXXXXX\",\n            \"smsEnabled\": 0,\n            \"note\": \"ბიოს\"\n        }\n    ]\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

3 приклад
Клієнта створено 201
Відповідь · JSON
{
    "statusID": 0,
    "message": "Customer created",
    "data": {
        "id": 100001,
        "typeID": 1,
        "name": "გიორგი მაისურაძე",
        "mobile": "9955XXXXXXXX",
        "numbers": [
            {
                "mobile": "9955XXXXXXXX",
                "countryCode": "+995",
                "number": "5XXXXXXXX",
                "isPrimary": 1,
                "smsEnabled": 1,
                "note": "პირადი"
            },
            {
                "mobile": "9955XXXXXXXX",
                "countryCode": "+995",
                "number": "5XXXXXXXX",
                "isPrimary": 0,
                "smsEnabled": 0,
                "note": "ბიოს"
            }
        ],
        "personalNo": "XXXXXXXXXXX",
        "email": "[email protected]",
        "birthDate": "1990-05-17",
        "address": "ვაჟა-ფშაველას 1",
        "lang": "ka",
        "column1": "",
        "column2": "",
        "createdAt": "2026-08-26 13:19:02"
    }
}
Перевірку не пройдено 400
Відповідь · JSON
{
    "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"
    }
}
Billing API / Customers / Edit Customer

Edit Customer

Ключ API · Заголовок
POST https://api.ubill.dev /v1/customers/edit/100001

Updates an existing customer in the company associated with your API key. Use the customer id returned by the create, search or get endpoints in the URL.

Необхідний дозвіл: customers.edit. Enable this permission in the API application settings. A Business package is required. Send key: YOUR_API_KEY та Content-Type: application/json headers.

Partial update

Send a non-empty JSON object containing only fields to change. Omitted fields keep their current values. The customer ID, balance and status cannot be changed with this endpoint. Unknown fields and fields of disabled modules are rejected.

Тіло запиту

Поле Тип Опис
namestring/null, max 50Name; null or empty string clears it.
birthDatestring/nullYYYY-MM-DD date; null or empty string clears it.
addressstring/null, max 50Address; null or empty string clears it.
column1, column2string/null, max 50Additional fields; null or empty string clears them.
numbers масив Replacement phone number list; omission preserves existing numbers.
typeID ціле число Existing legal type ID. Cannot be null.
personalNostring/null, max 11Alphanumeric personal or company code. Null or empty string clears it.
emailstring/null, max 254Valid email address. Null or empty string clears it.
lang рядок ka, en or ru. Cannot be cleared.

Phone numbers

Omit numbers та mobile to keep existing numbers. Sending either replaces the entire phone number list; include every number you want to keep. Customers require at least one number; an empty list is rejected. Sending numbers: null is invalid. Numbers already assigned to another customer in the same company are rejected; keeping a number already on this customer is allowed.

Use the same numbers[] objects as for creation: number (local digits) or mobile (full international number), countryCode (default +995), isPrimary, smsEnabled (default true), and note (maximum 100 characters). Boolean flags accept JSON booleans or 0/1. One primary number is selected; without an explicit primary flag the first number is primary. Duplicate numbers in the submitted list are collapsed. A number must have 6 to 15 digits, and country code plus number must not exceed 15 digits.

For a single number use {"mobile":"9955XXXXXXXX","countryCode":"+995","smsEnabled":true,"numberNote":"Main"}. Send either numbers або mobile, never both. The top-level countryCode, smsEnabled, and numberNote shortcuts require mobile.

Update behavior

If the update fails, the previous data remains unchanged.

Відповіді

HTTPstatusID Опис
2000Updated successfully. data contains the updated record and current phone numbers; all related IDs in the response are public IDs.
400400Invalid request or invalid field values. errors identifies the affected fields; data is null.
401401Invalid API key or missing edit permission.
403403The caller IP address is not allowed.
404404The record is missing, deleted, or belongs to another company.
415415The request Content-Type is not application/json.
429429API rate limit exceeded.
50099The update could not be saved. The previous data remains unchanged.

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Тіло запиту JSON

Тіло запиту
{
    "name": "Updated Customer",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "email": "[email protected]"
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/customers/edit/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Customer",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "email": "[email protected]"
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers/edit/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "name": "Updated Customer",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "email": "[email protected]"
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers/edit/100001',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"name\": \"Updated Customer\",\n    \"numbers\": [\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"isPrimary\": true,\n            \"smsEnabled\": true,\n            \"note\": \"Main number\"\n        },\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"smsEnabled\": false,\n            \"note\": \"Additional number\"\n        }\n    ],\n    \"email\": \"[email protected]\"\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

4 приклад
Updated 200
Відповідь · JSON
{
    "statusID": 0,
    "message": "Customer updated",
    "data": {
        "id": 100001,
        "name": "Updated Customer",
        "birthDate": null,
        "address": "Tbilisi",
        "column1": null,
        "column2": null,
        "createdAt": "2026-10-01 10:00:00",
        "updatedAt": "2026-10-27 12:00:00",
        "mobile": "9955XXXXXXXX",
        "numbers": [
            {
                "number": "5XXXXXXXX",
                "countryCode": "+995",
                "isPrimary": 1,
                "smsEnabled": 1,
                "note": "Main number",
                "mobile": "9955XXXXXXXX"
            },
            {
                "number": "5XXXXXXXX",
                "countryCode": "+995",
                "smsEnabled": 0,
                "note": "Additional number",
                "mobile": "9955XXXXXXXX",
                "isPrimary": 0
            }
        ],
        "typeID": 1,
        "personalNo": "XXXXXXXXXXX",
        "email": "[email protected]",
        "lang": "ka"
    }
}
Перевірку не пройдено 400
Відповідь · JSON
{
    "statusID": 400,
    "message": "Validation failed",
    "data": null,
    "errors": {
        "numbers": "Phone number is invalid"
    }
}
Not found 404
Відповідь · JSON
{
    "statusID": 404,
    "message": "Customer not found",
    "data": null
}
Storage failure 500
Відповідь · JSON
{
    "statusID": 99,
    "message": "Customer update failed",
    "data": null
}
Білінг API / Клієнти / Отримання клієнта

Отримання клієнта

Ключ API · Заголовок
GET https://api.ubill.dev /v1/customers/100001

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/customers/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers/100001',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

0 приклад
Для цієї кінцевої точки немає прикладу відповіді.
Білінг API / Клієнти / Пошук клієнтів

Пошук клієнтів

Ключ API · Заголовок
GET https://api.ubill.dev /v1/customers/search?type=mobile&value=9955XXXXXXXX

Параметри URL 2

typequerymobile
valuequery9955XXXXXXXX

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/customers/search?type=mobile&value=9955XXXXXXXX' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers/search?type=mobile&value=9955XXXXXXXX',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers/search?type=mobile&value=9955XXXXXXXX',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

0 приклад
Для цієї кінцевої точки немає прикладу відповіді.
Білінг API / Клієнти / Облікові записи клієнта

Облікові записи клієнта

Ключ API · Заголовок
GET https://api.ubill.dev /v1/customers/accounts/100001

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/customers/accounts/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/customers/accounts/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/customers/accounts/100001',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Облікові записи клієнта Приклад
Відповідь · JSON
{
    "statusID": 0,
    "message": "Success",
    "draw": 0,
    "recordsTotal": 3,
    "recordsFiltered": 3,
    "data": [
        {
            "id": "170115",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "1",
            "area": "ბათუმი - ბათუმი",
            "address": "",
            "column1": "",
            "column2": "",
            "tariffID": null,
            "tariffName": null,
            "tariffPrice": null,
            "balance": "0.00",
            "statusID": "1",
            "statusName": "აქტიური",
            "shutdownDate": null,
            "creditDate": null,
            "mac": null,
            "ip": null,
            "createdAt": "2023-12-02 11:41:37"
        },
        {
            "id": "170114",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "1",
            "area": "ბათუმი - ბათუმი",
            "address": "",
            "column1": "",
            "column2": "",
            "tariffID": "1",
            "tariffName": "test2",
            "tariffPrice": "30.00",
            "balance": "-2.00",
            "statusID": "2",
            "statusName": "პასიური",
            "shutdownDate": null,
            "creditDate": null,
            "mac": null,
            "ip": null,
            "createdAt": "2023-11-20 23:56:52"
        },
        {
            "id": "100001",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "2",
            "area": "თბილისი - თბილისი",
            "address": "Example Address",
            "column1": "",
            "column2": "",
            "tariffID": "1",
            "tariffName": "test2",
            "tariffPrice": "30.00",
            "balance": "-9.71",
            "statusID": "2",
            "statusName": "პასიური",
            "shutdownDate": "2022-07-13",
            "creditDate": null,
            "mac": "Cc:2d:21:0e:c9:41",
            "ip": "192.168.5.2",
            "createdAt": "2020-07-01 21:32:31"
        }
    ]
}
РЕСУРС

Облікові записи

6 кінцева точка

Білінг API / Облікові записи / Отримання всіх облікових записів

Отримання всіх облікових записів

Ключ API · Заголовок
GET https://api.ubill.dev /v1/accounts

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/accounts' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Отримання всіх облікових записів Приклад
Відповідь · JSON
{
    "statusID": 0,
    "message": "Success",
    "draw": 0,
    "recordsTotal": 70114,
    "recordsFiltered": 70114,
    "data": [
        {
            "id": "170115",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "1",
            "area": "თბილისი - თბილისი",
            "address": "",
            "column1": "",
            "column2": "",
            "tariffID": null,
            "tariffName": null,
            "tariffPrice": null,
            "balance": "0.00",
            "statusID": "1",
            "statusName": "აქტიური",
            "shutdownDate": null,
            "creditDate": null,
            "mac": null,
            "ip": null,
            "createdAt": "2023-12-02 11:41:37"
        },
        {
            "id": "170114",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "1",
            "area": "ბათუმი - ბათუმი",
            "address": "",
            "column1": "",
            "column2": "",
            "tariffID": "1",
            "tariffName": "test2",
            "tariffPrice": "30.00",
            "balance": "-2.00",
            "statusID": "2",
            "statusName": "პასიური",
            "shutdownDate": null,
            "creditDate": null,
            "mac": null,
            "ip": null,
            "createdAt": "2023-11-20 23:56:52"
        }
    ]
}
Білінг API / Облікові записи / Створення облікового запису

Створення облікового запису

Ключ API · Заголовок
POST https://api.ubill.dev /v1/accounts/create

Створює обліковий запис (послугу) для наявного клієнта. Номер ( id in the response) is generated automatically according to the account numbering settings, just like an account created from the uBill web interface.

Необхідний дозвіл: 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.
stbMacIPTV ні MAC-адреса STB, унікальна в межах компанії.
gpsProviderIDGPS track так Номер GPS-провайдера компанії.
gpsTrackIdentifierGPS track ні Ідентифікатор пристрою, унікальний у межах компанії.

SMS-сповіщення

Якщо ввімкнено SMS про створення запису, повідомлення надсилається на всі його номери з активними SMS, зі списанням балансу компанії. За недостатнього балансу запис усе одно створюється, а відповідь містить додаткове warning поле.

Відповіді

HTTPstatusID Опис
2010 Обліковий запис створено, data містить новий обліковий запис.
400400 Перевірка не пройдена, errors об’єкт указує некоректні поля. Дублікати MAC-адрес і телефонів повідомляються так само.
50099 Запис не вдалося зберегти, нічого не записано.

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Тіло запиту JSON

Тіло запиту
{
    "customerID": 100001,
    "name": "ბინა - ვაჟა-ფშაველას 1",
    "birthDate": "1990-05-17",
    "areaID": 1,
    "address": "ვაჟა-ფშაველას 1",
    "geoLocation": "41.732438,44.7688134",
    "column1": "",
    "column2": "",
    "tariffID": 2,
    "groupID": 1,
    "tagsID": [1, 3],
    "mac": "00:11:22:33:44:55",
    "onuMac": "AA:BB:CC:DD:EE:FF",
    "ipRangeID": 1,
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1
        }
    ]
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/accounts/create' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "customerID": 100001,
    "name": "ბინა - ვაჟა-ფშაველას 1",
    "birthDate": "1990-05-17",
    "areaID": 1,
    "address": "ვაჟა-ფშაველას 1",
    "geoLocation": "41.732438,44.7688134",
    "column1": "",
    "column2": "",
    "tariffID": 2,
    "groupID": 1,
    "tagsID": [1, 3],
    "mac": "00:11:22:33:44:55",
    "onuMac": "AA:BB:CC:DD:EE:FF",
    "ipRangeID": 1,
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1
        }
    ]
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "customerID": 100001,
    "name": "ბინა - ვაჟა-ფშაველას 1",
    "birthDate": "1990-05-17",
    "areaID": 1,
    "address": "ვაჟა-ფშაველას 1",
    "geoLocation": "41.732438,44.7688134",
    "column1": "",
    "column2": "",
    "tariffID": 2,
    "groupID": 1,
    "tagsID": [1, 3],
    "mac": "00:11:22:33:44:55",
    "onuMac": "AA:BB:CC:DD:EE:FF",
    "ipRangeID": 1,
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": 1,
            "smsEnabled": 1
        }
    ]
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts/create',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"customerID\": 100001,\n    \"name\": \"ბინა - ვაჟა-ფშაველას 1\",\n    \"birthDate\": \"1990-05-17\",\n    \"areaID\": 1,\n    \"address\": \"ვაჟა-ფშაველას 1\",\n    \"geoLocation\": \"41.732438,44.7688134\",\n    \"column1\": \"\",\n    \"column2\": \"\",\n    \"tariffID\": 2,\n    \"groupID\": 1,\n    \"tagsID\": [1, 3],\n    \"mac\": \"00:11:22:33:44:55\",\n    \"onuMac\": \"AA:BB:CC:DD:EE:FF\",\n    \"ipRangeID\": 1,\n    \"numbers\": [\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"isPrimary\": 1,\n            \"smsEnabled\": 1\n        }\n    ]\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

4 приклад
Обліковий запис створено 201
Відповідь · JSON
{
    "statusID": 0,
    "message": "Account created",
    "data": {
        "id": 100001,
        "customerID": 100001,
        "name": "ბინა - ვაჟა-ფშაველას 1",
        "mobile": "9955XXXXXXXX",
        "numbers": [
            {
                "mobile": "9955XXXXXXXX",
                "countryCode": "+995",
                "number": "5XXXXXXXX",
                "isPrimary": 1,
                "smsEnabled": 1,
                "note": null
            }
        ],
        "personalNo": "XXXXXXXXXXX",
        "birthDate": "1990-05-17",
        "areaID": 1,
        "area": "თბილისი",
        "address": "ვაჟა-ფშაველას 1",
        "geoLocation": "41.732438,44.7688134",
        "column1": "",
        "column2": "",
        "groupID": 1,
        "tagsID": [1, 3],
        "tariffID": 2,
        "balance": "0.00",
        "statusID": 1,
        "createdAt": "2026-08-26 13:19:39",
        "mac": "00:11:22:33:44:55",
        "onuMac": "AA:BB:CC:DD:EE:FF",
        "ipRangeID": 1,
        "ip": "192.168.5.21"
    }
}
Створено без балансу SMS 201
Відповідь · JSON
{
    "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 მისამართი უკვე მითითებულია სხვა ანგარიშზე"
        ]
    }
}
Billing API / Accounts / Edit Account

Edit Account

Ключ API · Заголовок
POST https://api.ubill.dev /v1/accounts/edit/100001

Updates an existing account in the company associated with your API key. Use the account id returned by the create, search or get endpoints in the URL.

Необхідний дозвіл: accounts.edit. Enable this permission in the API application settings. A Business package is required. Send key: YOUR_API_KEY та Content-Type: application/json headers.

Partial update

Send a non-empty JSON object containing only fields to change. Omitted fields keep their current values. The account ID and balance cannot be changed with this endpoint. Unknown fields and fields of disabled modules are rejected.

Тіло запиту

Поле Тип Опис
namestring/null, max 50Name; null or empty string clears it.
birthDatestring/nullYYYY-MM-DD date; null or empty string clears it.
addressstring/null, max 50Address; null or empty string clears it.
column1, column2string/null, max 50Additional fields; null or empty string clears them.
numbers масив Replacement phone number list; omission preserves existing numbers.
customerID ціле число Customer id returned by the customer endpoints for your company. Cannot be null.
areaIDinteger/nullSettlement ID; null removes the settlement.
geoLocationstring/nullLatitude,longitude with latitude between -90 and 90 and longitude between -180 and 180; null or empty string clears it.
tariffID, groupIDinteger/nullPublic tariff/group IDs in the same company. Null removes the link.
tagsID масив цілих чисел Full replacement list of public tag IDs. [] removes all tags; omission preserves them.
mac, onuMacstring/null, max 45Available only with the Network module. Values must be unique within the company; null or empty string clears them.
ipRangeIDinteger/nullNetwork module only. Public NAS range ID. A changed range assigns the first free IP; if exhausted, the request fails. Null removes both the range and IP. An unchanged range preserves the IP.
stbMacstring/null, max 45IPTV module only. Must be unique within the company.
gpsProviderIDinteger/nullGPS module only. Public GPS provider ID; null clears it.
gpsTrackIdentifierstring/null, max 255GPS module only. Unique device identifier; null or empty string clears it.
statusID ціле число Account status: 1 = Active (აქტიური), 2 = Passive (პასიური), 3 = Suspended (შეჩერებული), 4 = Cancelled (გაუქმებული). Omission keeps the current status; null, strings and unknown IDs are rejected.

Account statuses / ანგარიშის სტატუსები

statusIDMeaningქართული მნიშვნელობა
1Activeაქტიური
2Passiveპასიური
3Suspendedშეჩერებული
4Cancelledგაუქმებული

Надіслати {"statusID":2} to make an account passive. The updated account status is returned in data.statusID, with its catalog label in data.statusName. The top-level statusID: 0 describes API success, not the account status.

Status 4 clears the assigned IP. The account, its ID and phone numbers are preserved. Balance, credit, tariff and billing dates remain unchanged by a status change.

Phone numbers

Omit numbers та mobile to keep existing numbers. Sending either replaces the entire phone number list; include every number you want to keep. Accounts may have no numbers; send numbers: [] to clear the list. Sending numbers: null is invalid. Numbers already assigned to another account in the same company are rejected; keeping a number already on this account is allowed.

Use the same numbers[] objects as for creation: number (local digits) or mobile (full international number), countryCode (default +995), isPrimary, smsEnabled (default true), and note (maximum 100 characters). Boolean flags accept JSON booleans or 0/1. One primary number is selected; without an explicit primary flag the first number is primary. Duplicate numbers in the submitted list are collapsed. A number must have 6 to 15 digits, and country code plus number must not exceed 15 digits.

For a single number use {"mobile":"9955XXXXXXXX","countryCode":"+995","smsEnabled":true,"numberNote":"Main"}. Send either numbers або mobile, never both. The top-level countryCode, smsEnabled, and numberNote shortcuts require mobile.

Update behavior

If the update fails, the previous data remains unchanged. Editing an account does not send the account creation SMS notification.

Відповіді

HTTPstatusID Опис
2000Updated successfully. data contains the updated record and current phone numbers; all related IDs in the response are public IDs.
400400Invalid request or invalid field values. errors identifies the affected fields; data is null.
401401Invalid API key or missing edit permission.
403403The caller IP address is not allowed.
404404The record is missing, deleted, or belongs to another company.
415415The request Content-Type is not application/json.
429429API rate limit exceeded.
50099The update could not be saved. The previous data remains unchanged.

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Тіло запиту JSON

Тіло запиту
{
    "name": "Updated Account",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "address": "Updated service address",
    "statusID": 2
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/accounts/edit/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Account",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "address": "Updated service address",
    "statusID": 2
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts/edit/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "name": "Updated Account",
    "numbers": [
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "isPrimary": true,
            "smsEnabled": true,
            "note": "Main number"
        },
        {
            "number": "5XXXXXXXX",
            "countryCode": "+995",
            "smsEnabled": false,
            "note": "Additional number"
        }
    ],
    "address": "Updated service address",
    "statusID": 2
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts/edit/100001',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"name\": \"Updated Account\",\n    \"numbers\": [\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"isPrimary\": true,\n            \"smsEnabled\": true,\n            \"note\": \"Main number\"\n        },\n        {\n            \"number\": \"5XXXXXXXX\",\n            \"countryCode\": \"+995\",\n            \"smsEnabled\": false,\n            \"note\": \"Additional number\"\n        }\n    ],\n    \"address\": \"Updated service address\",\n    \"statusID\": 2\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

5 приклад
Updated 200
Відповідь · JSON
{
    "statusID": 0,
    "message": "Account updated",
    "data": {
        "id": 100001,
        "name": "Updated Account",
        "birthDate": null,
        "address": "Updated service address",
        "column1": null,
        "column2": null,
        "createdAt": "2026-10-01 10:00:00",
        "updatedAt": "2026-10-27 12:00:00",
        "mobile": "9955XXXXXXXX",
        "numbers": [
            {
                "number": "5XXXXXXXX",
                "countryCode": "+995",
                "isPrimary": 1,
                "smsEnabled": 1,
                "note": "Main number",
                "mobile": "9955XXXXXXXX"
            },
            {
                "number": "5XXXXXXXX",
                "countryCode": "+995",
                "smsEnabled": 0,
                "note": "Additional number",
                "mobile": "9955XXXXXXXX",
                "isPrimary": 0
            }
        ],
        "customerID": 100001,
        "areaID": null,
        "geoLocation": null,
        "balance": "12.34",
        "statusID": 2,
        "tariffID": null,
        "groupID": null,
        "ipRangeID": null,
        "gpsProviderID": null,
        "tagsID": [],
        "mac": null,
        "onuMac": null,
        "stbMac": null,
        "ip": null,
        "gpsTrackIdentifier": null,
        "statusName": "პასიური"
    }
}
Перевірку не пройдено 400
Відповідь · JSON
{
    "statusID": 400,
    "message": "Validation failed",
    "data": null,
    "errors": {
        "numbers": "Phone number is invalid"
    }
}
Not found 404
Відповідь · JSON
{
    "statusID": 404,
    "message": "Account not found",
    "data": null
}
Storage failure 500
Відповідь · JSON
{
    "statusID": 99,
    "message": "Account update failed",
    "data": null
}
Invalid account status 400
Відповідь · JSON
{
    "statusID": 400,
    "message": "Validation failed",
    "data": null,
    "errors": {
        "statusID": "statusID does not exist"
    }
}
Білінг API / Облікові записи / Отримання облікового запису

Отримання облікового запису

Ключ API · Заголовок
GET https://api.ubill.dev /v1/accounts/100001

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/accounts/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts/100001',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Отримання облікового запису Приклад
Відповідь · JSON
{
    "statusID": 0,
    "message": "Success",
    "data": [
        {
            "id": "100001",
            "name": "Example Customer",
            "mobile": "5XXXXXXXX",
            "personalNo": "XXXXXXXXXXX",
            "birthDate": "1991-12-08",
            "areaID": "2",
            "area": "თბილისი",
            "address": "Example Address",
            "column1": "",
            "column2": "",
            "tariffID": "1",
            "tariffName": "test2",
            "tariffPrice": "30.00",
            "balance": "-9.00",
            "statusID": "2",
            "statusName": "პასიური",
            "shutdownDate": null,
            "creditDate": null,
            "mac": "Cc:2d:21:0e:c9:41",
            "ip": "192.168.5.2",
            "createdAt": "2020-07-01 21:32:31"
        }
    ]
}
Білінг API / Облікові записи / Пошук облікових записів

Пошук облікових записів

Ключ API · Заголовок
GET https://api.ubill.dev /v1/accounts/search?type=mobile&value=9955XXXXXXXX

Параметри URL 2

typequerymobile
valuequery9955XXXXXXXX

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/accounts/search?type=mobile&value=9955XXXXXXXX' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts/search?type=mobile&value=9955XXXXXXXX',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts/search?type=mobile&value=9955XXXXXXXX',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

0 приклад
Для цієї кінцевої точки немає прикладу відповіді.
Білінг API / Облікові записи / Установлення кредиту

Установлення кредиту

Ключ API · Заголовок
POST https://api.ubill.dev /v1/accounts/setCredit

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Тіло запиту JSON

Тіло запиту
{
    "accountID": 170114,
    "date": "2023-12-10"
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/accounts/setCredit' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountID": 170114,
    "date": "2023-12-10"
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/accounts/setCredit',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "accountID": 170114,
    "date": "2023-12-10"
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/accounts/setCredit',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"accountID\": 170114,\n    \"date\": \"2023-12-10\"\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Установлення кредиту Приклад
Відповідь · JSON
{
    "statusID": 0,
    "message": "Success"
}
РЕСУРС

Платежі

3 кінцева точка

Білінг API / Платежі / Отримання платежів

Отримання платежів

Ключ API · Заголовок
GET https://api.ubill.dev /v1/payments

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/payments' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/payments',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/payments',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Отримання платежів Приклад
Відповідь · JSON
{
    "status": true,
    "draw": 0,
    "recordsTotal": 9,
    "recordsFiltered": 9,
    "data": [
        {
            "id": "9",
            "accountID": "100001",
            "balance": "0.29",
            "sum": "-10.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "2",
            "typeName": "კორექტირება",
            "admin": "Example Customer",
            "date": "2022-06-11 10:07:13"
        },
        {
            "id": "8",
            "accountID": "100001",
            "balance": "-0.71",
            "sum": "1.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2022-06-10 22:24:14"
        },
        {
            "id": "7",
            "accountID": "170099",
            "balance": "-1.00",
            "sum": "20.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "2",
            "typeName": "კორექტირება",
            "admin": "Example Customer",
            "date": "2022-01-29 16:39:50"
        },
        {
            "id": "6",
            "accountID": "170099",
            "balance": "0.00",
            "sum": "-1.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "2",
            "typeName": "კორექტირება",
            "admin": "Example Customer",
            "date": "2022-01-29 16:39:39"
        },
        {
            "id": "5",
            "accountID": "100001",
            "balance": "39.06",
            "sum": "10.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-12-22 17:16:43"
        },
        {
            "id": "4",
            "accountID": "100001",
            "balance": "-0.94",
            "sum": "20.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-12-22 17:14:57"
        },
        {
            "id": "3",
            "accountID": "100001",
            "balance": "0.06",
            "sum": "1.00",
            "comment": null,
            "transactionID": "t1",
            "paySystem": "TBCPAY",
            "apiStatus": "0",
            "typeID": "5",
            "typeName": "ჩარიცხვა",
            "admin": null,
            "date": "2021-11-13 15:26:53"
        },
        {
            "id": "2",
            "accountID": "100001",
            "balance": "-0.94",
            "sum": "1.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-01-18 10:31:32"
        },
        {
            "id": "1",
            "accountID": "100001",
            "balance": "-1.94",
            "sum": "1.00",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-01-18 10:31:14"
        }
    ]
}
Білінг API / Платежі / Отримання платежів за обліковим записом

Отримання платежів за обліковим записом

Ключ API · Заголовок
GET https://api.ubill.dev /v1/payments/account/100001

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request GET \
  --url 'https://api.ubill.dev/v1/payments/account/100001' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/payments/account/100001',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/payments/account/100001',
  {
  method: 'GET',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Отримання платежів за обліковим записом Приклад
Відповідь · JSON
{
    "statusID": 0,
    "message": "Success",
    "data": [
        {
            "id": "89",
            "accountID": null,
            "balance": "-1.94",
            "sum": "1",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-01-18 10:31:14"
        },
        {
            "id": "90",
            "accountID": null,
            "balance": "-0.94",
            "sum": "1",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-01-18 10:31:32"
        },
        {
            "id": "537",
            "accountID": null,
            "balance": "0.06",
            "sum": "1",
            "comment": null,
            "transactionID": "t1",
            "paySystem": "TBCPAY",
            "apiStatus": "0",
            "typeID": "5",
            "typeName": "ჩარიცხვა",
            "admin": null,
            "date": "2021-11-13 15:26:53"
        },
        {
            "id": "641",
            "accountID": null,
            "balance": "-0.94",
            "sum": "20",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-12-22 17:14:57"
        },
        {
            "id": "642",
            "accountID": null,
            "balance": "39.06",
            "sum": "10",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2021-12-22 17:16:43"
        },
        {
            "id": "1720",
            "accountID": null,
            "balance": "-0.7057142857142757",
            "sum": "1",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "1",
            "typeName": "დამატება",
            "admin": "Example Customer",
            "date": "2022-06-10 22:24:14"
        },
        {
            "id": "1729",
            "accountID": null,
            "balance": "0.29428571428572",
            "sum": "-10",
            "comment": "",
            "transactionID": null,
            "paySystem": null,
            "apiStatus": "0",
            "typeID": "2",
            "typeName": "კორექტირება",
            "admin": "Example Customer",
            "date": "2022-06-11 10:07:13"
        }
    ]
}
Білінг API / Платежі / Додавання платежу

Додавання платежу

Ключ API · Заголовок
POST https://api.ubill.dev /v1/payments/add

Заголовки запиту 2

Ключ Значення Джерело
keyYOUR_API_KEY Автентифікація
Content-Typeapplication/json Заголовок

Тіло запиту JSON

Тіло запиту
{
    "accountID" : 170114,
    "sum" : 1,
    "comment": "text",
    "paySystem": "WEB"
}

Приклади коду

cURL · PHP · JavaScript
cURL
curl --request POST \
  --url 'https://api.ubill.dev/v1/payments/add' \
  --header 'key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountID" : 170114,
    "sum" : 1,
    "comment": "text",
    "paySystem": "WEB"
}'
PHP
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.ubill.dev/v1/payments/add',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => <<<'BODY'
{
    "accountID" : 170114,
    "sum" : 1,
    "comment": "text",
    "paySystem": "WEB"
}
BODY,
    CURLOPT_HTTPHEADER => [
        'key: YOUR_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;
JavaScript
const response = await fetch(
  'https://api.ubill.dev/v1/payments/add',
  {
  method: 'POST',
  headers: {
    'key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: "{\n    \"accountID\" : 170114,\n    \"sum\" : 1,\n    \"comment\": \"text\",\n    \"paySystem\": \"WEB\"\n}"
  }
);

const data = await response.json();
console.log(data);

Приклади відповідей

1 приклад
Додавання платежів Приклад
Відповідь · JSON
{
    "statusID": 0,
    "message": "Success",
    "data": {
        "id": "11521"
    }
}
ПОТРІБНА ДОПОМОГА?

Підтримка інтеграції

Команда uBill допоможе з питаннями інтеграції API.

Зв’язатися з нами
Інфраструктура й технології

Ми використовуємо провідні й надійні технології

uBill побудовано на сучасних інструментах, що забезпечують стабільність, безпеку й зручне масштабування

Нагору