API для розробників¶

Якщо Ви розробник або інтегратор, Ви можете інтегрувати Вашу інформаційну систему або бізнес-застосунок з «Віртуальною мобільною АТС» скориставшись цим HTTP API.

Базова інформація про дзвінки¶

Інтерфейс дозволяє отримати базову інформацію про дзвінки, що були здійснені абонентами Вашої «Віртуальної мобільної АТС» за певний період часу.

Примітка

Базова інформація про дзвінки надається тільки по номерам, на яких підключено пакет «Конвергентний». Використання цього методу не потребує активації пакету “API FMC”.

Примітка

Для використання API Вам знадобиться токен авторизації (FMC Token), який Ви можете отримати у розділі «Інтеграція з CRM» на Веб-порталі інтеграції вашої «Віртуальної мобільної АТС» за адресою https://fmc.kyivstar.ua/crm-integration (використовуйте логін та пароль адміністратора підприємства «Віртуальної мобільної АТС»).

Інформація надається у декілька форматах: CSV, JSON та XML. Для вибору необхідного Вам формату даних використовуйте URL з відповідним суфіксом методу.

HTTP метод:

GET

URL метода:

https://fmc.kyivstar.ua/api/cdr/v1/callstat.csv

або

https://fmc.kyivstar.ua/api/cdr/v1/callstat.json

або

https://fmc.kyivstar.ua/api/cdr/v1/callstat.xml

Параметри:

token (обов’язковий)

64-х символьний ключ авторизації

Приклад: «868b26d121e50f3b9e715bd86e77f2d6dbef354e7a9bcdb0aae0a0868a32e4a1»

from (обов’язковий)

Відмітка часу у форматі «YYYY-MM-DDTHH:MM:SS»

Початок часового проміжку

Наприклад: «2017-04-29T14:25:00»

to (обов’язковий)

Відмітка часу у форматі «YYYY-MM-DDTHH:MM:SS»

Кінець часового проміжку

Наприклад: «2017-05-03T17:24:55»

names (опціональний)

Флаг (приймає значення «on» або «off»)

Додає в дані імена абонентів, що були знайдені в адресній книзі Вашої «Віртуальної мобільної АТС»

Значення за замовченням- «off»

departments (опціональний)

Флаг (приймає значення «on» або «off»)

Додає в дані назви відділов абонентів, що були знайдені в адресній книзі Вашої «Віртуальної мобільної АТС»

Значення за замовченням - «off»

ownership (опціональний)

Флаг (приймає значення «on» або «off»)

Додає в дані ознаку приналежності абонента до підприємства Вашої «Віртуальної мобільної АТС»

Значення за замовченням - «off»

direction (опціональний)

Флаг (приймає значення «on» або «off»)

Додає в дані тип дзвінка: вхідний або вихідний

Значення за замовченням - «off»

Коди стану:

200 OK: Успішний запит, у відповіді міститься файл з даними в обраному форматі
400 Bad Request: Не вказаний один з обов’язкових параметрів, або один з параметрів має неприпустиме значення
403 Forbidden: Вказано невірний ключ авторизації
500 Internal Server Error: Внутрішня помилка серверу інтеграції

Примітки:

Відмітки часу вказуються у часовому поясі Європа/Київ (EET/EEST);
Максимальний проміжок часу для одного запиту складає 7 діб;
Параметр from не може бути «старшим» ніж 30 діб;
Параметру to не може бути присвоєне значення у «майбутньому». to <= now();
Один з параметрів from або to може бути не вказаний. В такому випадку він буде вирахуваний автоматично по одній з наступних формул:
- from = to - 7 діб
- to = min(from + 7 діб, now())

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

GET /api/cdr/v1/callstat.json?token=868b26...32e4a1&from=2017-04-29T14:25:00&to=2017-05-03T17:24:55 HTTP/1.1
Host: fmc.kyivstar.ua

Приклад відповіді:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Content-Disposition: attachment; filename="callstat_2017-04-29T14:25:00_2017-05-03T17:24:55.json"

{
    "calls": [
        {
            "end_timestamp": "2017-04-29 21:39:48",
            "start_timestamp": "2017-04-29 21:39:35",
            "calling_number": "0675376761",
            "duration": 14,
            "called_number": "0671234567",
        }
    ]
}

Приклад запиту з використанням утиліти cURL:

curl -X GET \
  'https://fmc.kyivstar.ua/api/cdr/v1/callstat.csv?token=868b26...32e4a1&from=2017-04-29T14:25:00&to=2017-05-03T17:24:55'

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

<?php

$request = new HttpRequest();
$request->setUrl('https://fmc.kyivstar.ua/api/cdr/v1/callstat.csv');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'token' => '868b26...32e4a1',
  'from' => '2017-04-29T14:25:00',
  'to' => '2017-05-03T17:24:55'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

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

import requests

url = "https://fmc.kyivstar.ua/api/cdr/v1/callstat.csv"

querystring = {
    "token": "868b26...32e4a1",
    "from": "2017-04-29T14:25:00",
    "to": "2017-05-03T17:24:55"
}

response = requests.request("GET", url, params=querystring)

print(response.text)

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

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://fmc.kyivstar.ua/api/cdr/v1/callstat.csv?token=868b26....32e4a1&from=2017-04-29T14%3A25%3A00&to=2017-05-03T17%3A24%3A55")
  .get()
  .build();

Response response = client.newCall(request).execute();

Розширена функціональність¶

Якщо Вам потрібні додаткові API методи, що дозволять Вам розробляти більш глибоку інтеграцію з «Віртуальною мобільною АТС» Ви можете використовувати послугу Generic FMC API, що надає великий перелік методів для інтеграції Вашого бізнес-застосунку (як то CRM, BPM, тощо) з мобільною телефонією.

Детальна технічна документація у форматі OpenAPI доступна за посиланням: https://fmc.kyivstar.ua/manual/openapi.html

Примітка

Послуга надається тільки для номерів, на яких підключено пакет «Конвергентний» + «API FMC». Список телефонів Київстар, для яких в «Віртуальній мобільній АТС» активовано пакет «API FMC», можна подивитися на веб-порталі «Віртуальної мобільної АТС» у розділі «Додаткові послуги» за адресою https://fmc.kyivstar.ua/provisioning.

Інтеграція «Віртуальної мобільної АТС» з Generic FMC API надає наступні переваги:

Реєстрація webhook Вашого застосунку для отримання інформації про стани телефонного дзвінка в онлайн режимі;
Керування телефонними дзвінками (відбій, тощо);
Отримання розширеної історії дзвінків;
Скачування mp3 файлу з записом розмови;
Ініціація вихідного дзвінка (click2dial);
«CLIP» - Зміна номеру презентації через API;
«DND» - Зміна налаштувань DND (Do Not Disturb) через API;
Отримання інформації про стан телефону (вільний/зайнятий) та стан DND (вкл/викл);

Примітка

Інформація щодо налаштування інтеграції Generic FMC API представлена в розділі Інтеграція з Generic FMC API.

Стани дзвінка¶

Generic FMC API буде надсилати у webhook Вашого бізнес-застосунку інформацію про стан телефонних дзвінків (alerting, established, finished). Кожне повідомлення зі станом містить корисну інформацію, що може бути використана для інтеграції Вашого застосунку з мобільною мережею. Наприклад call_control_id яке може бути використане для керування телефонним дзвінком, тощо.

Керування дзвінком¶

Цей метод дозволяє Вам керувати дзвінком. Ви можете завершити дзвінок - або відбити його на фазі виклику (alerting) або розірвати з’єднання на фазі розмови. Для керування дзвінком Вам необхідно мати ідентифікатор call_control_id який Ви можете отримати або з повідомлення про стан дзвінку або з методу Click2Dial.

Історія дзвінків¶

Основна перевага розширеної історії дзвінків над базовою версією, описаної у розділі Базова інформація про дзвінки, наступна:

Розширена історія дзвінків інтегрована з Записом розмов. Якщо дзвінок був записаний, ви отримаєте унікальний ідентифікатор запису record_id, який зможете використати для скачування mp3 файлу з записом розмови в методі Запис дзвінків;
Присутня інформація з тривалістю сигналу виклику (час коли телефон «дзвенів» до тих пір, поки дзвінок не був прийняти або скинутий);
Надається інформація про причину завершення дзвінка (код завершення, згідно специфікації ITU-T Q.850 https://www.itu.int/rec/T-REC-Q.850/ );

Запис дзвінків¶

Цей метод дозволяє скачати mp3 файл з записом дзвінка.

Примітка

Сервіс запису дзвінків надається тільки для номерів, для яких придбано додаткову послугу «Запис розмов».

Click2Dial¶

Ця функція дозволяє Вам ініціювати телефонний дзвінок з Вашого телефону на будь-який інший телефонний номер. За допомогою цього методу Ви можете реалізувати функцію Click2Dial у Вашому застосунку.

CLIP¶

Деякі бізнес-процеси вимагають зміни презентації номеру телефону співробітника на «загальний» / «груповий» / «віртуальний» номер Компанії. За допомогою даного метода це можна зробити автоматично із Вашого застосунку.

DND¶

Ця функціональність дозволяє за допомогою API включати та виключати функцію «Не турбувати» (Do not disturb) на номері телефону.

Отримання стану телефонного номеру¶

За допомогою API методу ви можете дізнатись, чи розмоляє зараз абонент по телефону, або чи включено у нього режим DND.