API для телефонних номерів та документів

За допомогою API ви можете реалізувати підключення і управління віртуальними номерами з власного інтерфейсу (адмін панелі) без необхідності входу в особистий кабінет Zadarma.

Всі можливості і методи API Zadarma - https://zadarma.com/ua/support/api/

У більшості країн, для підключення номеру потрібна ідентифікація кінцевого користувача. Призначені для користувача документи також завантажуються по API.

Можливості API:

• вибір і підключення віртуальних номерів
• налаштування вже підключених номерів
• робота з документами для підключення номерів (інформація про вимоги для підключення, завантаження документів, перевірка раніше завантажених документів для замовлення певного номера)

Послідовність дій для замовлення номера через API:

1. Отримання актуального списку країн і напрямків для замовлення, відображення їх користувачеві
2. Отримання і відображення списку номерів доступних для замовлення
3. Створення групи документів для користувача (якщо не була створена раніше) і завантаження документів (якщо потрібні).
4. Підключення обраного номера на групу документів.
5. Напрямок номера на SIP логін або SIP URI (set_sip_id)

Підключення нових номерів

Метод GET /v1/direct_numbers/countries/ отримання списку країн в яких можна замовити номер, якщо запит відправлено без параметрів, відповідь буде на мові особистого кабінету, додавши необов'язковий параметр language можна отримати відповідь на одній з мов особистого кабінету.

Метод GET /v1/direct_numbers/country/ для отримання списку напрямків в країні, в яких можна замовити номер. Обов'язковий параметр country - iso код країни (ISO 3166-1 alpha-2); Необов'язкові параметри language та direction_id. У відповіді буде наданий масив даних з описом номеру: країна, місто, вартість підключення, щомісячна абонентська плата, особливості, можливість прийому смс і т.і.

Отримання списку номерів доступних для замовлення, метод GET /v1/direct_numbers/available/<DIRECTION_ID>/ з параметрами DIRECTION_ID - ID нампрямку або ru495; та mask - необов'язковий параметр, для пошуку збігів за номерами.

Замовити номер можна за допомогою методу POST /v1/direct_numbers/order/ .

Вже підключений номер можна при необхідності подовжити на кілька місяців вперед методом POST /v1/direct_numbers/prolong/

Обов'язкові параметри запиту number та months.

Взаємодія з уже підключеними номерами

Метод GET /v1/direct_numbers/ (без параметрів) повертає масив з інформацією про вже підключені номери.

Методом GET /v1/direct_numbers/number/ можна отримати інформацію про певний підключений номер, запит відправляється з параметрами type та number

Статус автоподовження номера (чи буде він автоматично подовжений на наступний період або відключиться після закінчення терміну дії) можна дізнатися методом GET /v1/direct_numbers/autoprolongation/ з параметрами запиту type та number.

Для зміни статусу автоподовження метод PUT /v1/direct_numbers/autoprolongation/ з параметрами запиту type, number та value.

Метод PUT /v1/direct_numbers/set_caller_name/ - встановлення або включення Імені номеру (латиниця і цифри, до 30 знаків) текстовий опис номера, також при вхідному дзвінку відправляється в заголовку From в якості CALLERID(name).

Методом PUT /v1/direct_numbers/set_sip_id/ можна направити дзвінки з віртуального номера на певний sip логін, зовнішній сервер по SIP URI або включити режим тесту. Обов'язкові параметри запиту type, number та sip_id - sip номер або адреса зовнішнього сервера, наприклад 1234567890@myserver.com test_mode - опціонально, (on|off) - для включення тестового режиму.

Робота з документами

Група документів - це дані людини або компанії, яка буде використовувати віртуальний номер. Груп може бути декілька.

Створення нової групи документів, метод /v1/documents/groups/create/ .

Оновити дані у вже існуючій групі документів можна методом PUT /v1/documents/groups/update/<GROUPID>/ .

Завантаження файлу документа для групи документів виконується методом POST /v1/documents/upload/ .

Методом GET /v1/documents/files можна отримати список груп документів, а методом GET /v1/documents/groups/get/<ID>/ , де ID это ідентифікатор групи, 0 - основна група документів, можна отримати інформацію про певну групу документів.

Метод GET /v1/documents/files поверне список раніше завантажених файлів/документів в групі документів. group_id - необов'язковий параметр, ID групи документів, (0 або не вказано - основна група документів).

Перевірка: чи підходить група документів для замовлення номера в конкретному місті/напрямку виконується методом GET /v1/documents/groups/valid/<ID>/ .