SMSBAT REST API: Організації, Гаманці та Альфа-імена

Документація REST API для управління організаціями клієнтів, генерації договорів, подачі заявок на реєстрацію SMS Альфа-імен, перегляду балансу гаманця та вивантаження фінансової звітності.

---

1. Загальна Інформація та Авторизація

1.1 Базова адреса API

https://restapi.smsbat.com/api

1.2 Авторизація

Для всіх методів використовується Basic Authorization:

Authorization: Basic base64(login:password)

1.3 Формат даних

• Content-Type: application/json (якщо не вказано інше, наприклад ZIP для звітів)
• Кодування: UTF-8
• Формат дат: ISO 8601 у часовому поясі UTC.

1.4 HTTP коди відповіді

Код	Опис
200	Успішне виконання запиту
400	Помилка в параметрах запиту
401	Помилка авторизації
403	Доступ заборонений
404	Ресурс не знайдено
500	Внутрішня помилка сервера

---

2. Управління Організаціями

2.1 Створення організації

Створює нову організацію в системі SMSBAT та автоматично генерує юридичний договір для неї.

• Метод: POST
• URL: https://restapi.smsbat.com/api/client/organization
• Headers: Authorization: Basic base64(login:password), Content-Type: application/json

Параметри тіла запиту:

Поле	Тип	Обов’язкове	Опис
nameLocal	string	Так	Назва організації локальною мовою
nameEn	string	Так	Назва організації англійською
email	string	Так	Контактний email організації
organizationType	int	Так	Юридичний тип організації (див. enum нижче)
phone	string	Так	Номер телефону (нечислові символи вилучаються автоматично)
authorizedPersonDocument	string	Ні	Документ, що підтверджує повноваження (наприклад, Статут)
authorizedPersonName	string	Ні	ПІБ уповноваженої особи
authorizedPersonPosition	string	Ні	Посада уповноваженої особи (наприклад, Директор)
bankAccount	string	Ні	Рахунок IBAN
bankName	string	Ні	Назва банку
code	string	Ні	Код ЄДРПОУ / ІПН / РНОКПП
fullLegalName	string	Ні	Повне юридичне найменування
shortLegalName	string	Ні	Скорочене юридичне найменування
isTaxPayer	bool	Ні	Ознака платника ПДВ
passportIssuedDate	datetime	Ні	Дата видачі паспорта
passportNumber	string	Ні	Номер паспорта
unzr	string	Ні	УНЗР (Унікальний номер запису в Реєстрі)
authToken	object	Ні	Опціональний об’єкт для створення токена організації
authToken.name	string	Умовно	Назва токена (макс. 255 символів)
authToken.description	string	Умовно	Опис токена (макс. 1000 символів)
authToken.expireDate	datetime	Умовно	Дата закінчення дії токена (UTC, має бути у майбутньому)

Перелік типів організацій (organizationType):

Значення	Enum	Опис
1	JuridicalPerson	Юридична особа
2	SoleTrader	ФОП (Фізична особа-підприємець)
3	Individual	Фізична особа

Приклад тіла запиту:

{
  "nameLocal": "ТОВ Ромашка",
  "nameEn": "Romashka LLC",
  "email": "office@romashka.ua",
  "organizationType": 1,
  "phone": "+38 (099) 123-45-67",
  "authorizedPersonDocument": "Статут",
  "authorizedPersonName": "Іван Петренко",
  "authorizedPersonPosition": "Директор",
  "bankAccount": "UA123456789012345678901234567",
  "bankName": "ПриватБанк",
  "code": "12345678",
  "fullLegalName": "Товариство з обмеженою відповідальністю \"Ромашка\"",
  "shortLegalName": "ТОВ Ромашка",
  "isTaxPayer": true,
  "passportIssuedDate": "2020-01-01T00:00:00",
  "passportNumber": "МК123456",
  "unzr": "12345678-12345",
  "authToken": {
    "name": "Main API token",
    "description": "Основний токен для інтеграції",
    "expireDate": "2027-08-13T00:00:00"
  }
}

Приклад успішної відповіді (200 OK):

{
  "id": "5f7f9a13-f4ec-49e2-bf7f-80b60c7f55aa",
  "contractNumber": "SBT26UVBR00001",
  "nameLocal": "ТОВ Ромашка",
  "nameEn": "Romashka LLC",
  "email": "office@romashka.ua",
  "organizationType": 1,
  "phone": "380991234567",
  "authorizedPersonDocument": "Статут",
  "authorizedPersonName": "Іван Петренко",
  "authorizedPersonPosition": "Директор",
  "bankAccount": "UA123456789012345678901234567",
  "bankName": "ПриватБанк",
  "code": "12345678",
  "fullLegalName": "Товариство з обмеженою відповідальністю \"Ромашка\"",
  "shortLegalName": "ТОВ Ромашка",
  "isTaxPayer": true,
  "passportIssuedDate": "2020-01-01T00:00:00",
  "passportNumber": "МК123456",
  "unzr": "12345678-12345",
  "authToken": "9f2c1e7a4b8d3f6e2a5c8b1d4f7a3e9c2b5d8f1a"
}

---

3. Заявки на SMS Альфа-імена

3.1 Створення заявки на реєстрацію Альфа-імені

Подає заявку на реєстрацію SMS Альфа-імені для конкретної організації.

• Метод: POST
• URL: https://restapi.smsbat.com/api/AlphaName/sms/application
• Headers: Authorization: Basic base64(username:password), Content-Type: application/json

Параметри тіла запиту:

Поле	Тип	Обов’язкове	Опис
organizationId	guid	Так	ID організації у системі
alphaNameIn	string	Так	Текст Альфа-імені для реєстрації
edrpou	string	Так	ЄДРПОУ / ІПН
companyDetails	string	Так	Короткий опис діяльності компанії
companyWebsite	string	Так	Веб-сайт компанії
messageExample	string	Так	Приклад SMS-повідомлення
countries	array[string]	Так	Масив ISO-кодів країн (наприклад ["UA"])
callbackUrl	string	Ні	Callback URL для сповіщень про статус

Приклад тіла запиту:

{
  "organizationId": "f33cd09e-8796-4eba-906e-6905dea0ffb9",
  "alphaNameIn": "test_alpha",
  "edrpou": "12345678",
  "companyDetails": "Інтернет-магазин",
  "companyWebsite": "https://example.com",
  "messageExample": "Ваш код підтвердження: 1234",
  "countries": [
    "UA"
  ],
  "callbackUrl": "https://example.com/callback"
}

Успішна відповідь (200 OK):

{
  "success": true
}

---

4. Баланс та Історія Поповнень Гаманця

4.1 Отримання балансу та історії поповнень

Повертає поточний баланс SMS-гаманця для заданого Альфа-імені та історію транзакцій з пагінацією.

• Метод: GET
• URL: https://restapi.smsbat.com/api/alphaname/wallet/info
• Headers: Authorization: Basic base64(login:password)

Параметри запиту (Query Parameters):

Параметр	Тип	Обов’язковий	Значення за замовчуванням	Опис
externalAlphaName	string	Так	—	Альфа-ім’я, для якого запитується баланс (наприклад ABC123)
transactionTypes	string[]	Ні	credit	Фільтр транзакцій. Дозволені значення: credit, debit. Приклад: ?transactionTypes=credit&transactionTypes=debit
page	int	Ні	1	Номер сторінки
pageSize	int	Ні	20	Кількість транзакцій на сторінці

Типи транзакцій (transactionTypes):

Значення	Опис
credit	Поповнення балансу SMS-гаманця
debit	Списання коштів з SMS-гаманця

Приклад успішної відповіді (200 OK):

{
  "externalAlphaName": "ABC123",
  "balance": {
    "amount": 125.50,
    "currency": "EUR",
    "lastTransactionAt": "2026-05-19T10:20:00Z"
  },
  "transactions": {
    "total": 42,
    "items": [
      {
        "occurredAt": "2026-05-19T10:20:00Z",
        "type": "credit",
        "amount": 50.00,
        "currency": "EUR"
      },
      {
        "occurredAt": "2026-05-15T08:15:00Z",
        "type": "credit",
        "amount": 100.00,
        "currency": "EUR"
      },
      {
        "occurredAt": "2026-05-12T14:30:00Z",
        "type": "debit",
        "amount": 24.50,
        "currency": "EUR"
      }
    ]
  }
}

---

5. Вивантаження Витрат та Статусів SMS

5.1 Отримання статистики та звітів по SMS

Повертає ZIP-архів із CSV-файлом, який містить деталізовану статистику SMS-повідомлень, кількість доставлених/недоставлених SMS, тарифи та суму витрат.

• Метод: GET
• URL: https://restapi.smsbat.com/api/AlphaName/sms/status
• Headers: Authorization: Basic base64(login:password)

Параметри запиту (Query Parameters):

Параметр	Тип	Обов’язковий	Опис
dateFrom	date	Так	Початкова дата періоду (YYYY-MM-DD)
dateTo	date	Так	Кінцева дата періоду (YYYY-MM-DD)
alphaName	string	Ні	Фільтр по конкретному Alpha Name

Успішна відповідь (200 OK):

• Content-Type: application/zip

Колонки у CSV-файлі:

Колонка	Опис
AlphaName	Назва Альфа-імені
Country	Назва / код країни
Date	Дата відправки
Count	Загальна кількість повідомлень
Delivered	Кількість успішно доставлених повідомлень
Failed	Кількість недоставлених повідомлень
Rate	Тариф за 1 повідомлення
Spent	Загальна сума витрат