API для интеграции пользовательских систем

Вы можете интегрировать Вашу информационную систему с «Виртуальной мобильной АТС» воспользовавшись HTTP API.

Примечание

Для использования API Вам понадобится токен авторизации (FMC Token), который Вы можете получить в раздере «Настройки» на Веб-портале интеграции вашей «Виртуальной мобильной АТС», доступном по ссылке https://fmc.kyivstar.ua/api/webportal (используйте логин и пароль администатора вашей «Виртуальной мобильной АТС»).

Детализированная информация о звонках

Интерфейс позволяет получить детализированную информацию о звонках совершённых абонентами Вашей «Виртуальной мобильной АТС» за определённый период времени.

Примечание

Детализированная информация о звонках предоставляется только по номерам, на которых подключен пакет «Конвергентный».

Информация предоставляется в нескольких форматах: 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»

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

Примечания:

  • Отметки времени указываются в часовом поясе Европа/Киев (EET/EEST)
  • Максимальный промежуток времени для одного запроса составляет 7 суток
  • Параметр from не может быть «старше» чем 30 суток
  • Один из параметров 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 FMC».

Также на Веб-портале интеграции Вашей «Виртуальной мобильной АТС», в разделе «Настройки», должен быть выбран «OneBox» в выпадающем меню «CRM Тип».

Инициация звонка происходит по следующему сценарию:

  1. АТС делает вызов на абонента Вашей «Виртуальной мобильной АТС», от имени которого инициируется звонок;
  2. Абонент Вашей «Виртуальной мобильной АТС» принимает вызов (снимает трубку);
  3. АТС делает вызов на номер телефона назначения;
  4. Далее поведение звонка полностью аналогично тому, если бы абонент совершил звонок со своего телефонного аппарата.
HTTP метод:
GET
URL метода:
https://fmc.kyivstar.ua/api/onebox/v1/originate
Параметры:
token (обязательный)

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

Пример: «868b26d121e50f3b9e715bd86e77f2d6dbef354e7a9bcdb0aae0a0868a32e4a1»

calling_number (обязательный)

Номер телефона абонента Вашей «Виртуальной мобильной АТС», от имени которого инициировать звонок

Пример: «0671234567», «380987654321» или «+380441111111»

called_number (обязательный)

Номер телефона, на который инициировать звонок

Пример: «0671234567», «380987654321» или «+380441111111»

Коды состояния:
200 OK
Успешный запрос, «Виртуальная мобильная АТС» инициирует телефонный звонок
400 Bad Request
Не указан один из обязательных параметров, либо один из параметров имеет недопустимое значение
403 Forbidden
Указан неверный ключ авторизации, либо на номере абонента Вашей «Виртуальной мобильной АТС» не активирована функциональность API
500 Internal Server Error
Внутренняя ошибка сервера интеграции

Пример запроса:

GET /api/onebox/v1/originate?token=868b26...32e4a1&calling_number=0671234567&called_number=%2B380441111111 HTTP/1.1
Host: fmc.kyivstar.ua

Пример ответа:

HTTP/1.1 200 OK

Пример запроса с использованием утилиты cURL:

curl -X GET \
  'https://fmc.kyivstar.ua/api/onebox/v1/originate?token=868b26...32e4a1&calling_number=0671234567&called_number=+380441111111'

Пример запроса на PHP:

<?php

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

$request->setQueryData(array(
  'token' => '868b26...32e4a1',
  'calling_number' => '0671234567',
  'called_number' => '+380441111111'
));

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

} catch (HttpException $ex) {
  echo $ex;
}

Пример запроса на Python:

import requests

url = "https://fmc.kyivstar.ua/api/onebox/v1/originate"

querystring = {
    "token": "868b26...32e4a1",
    "calling_number": "0671234567",
    "called_number": "+380441111111"
}

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

Пример запроса на Java:

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://fmc.kyivstar.ua/api/onebox/v1/originate?token=868b26....32e4a1&calling_number=0671234567&called_number=+380441111111")
  .get()
  .build();

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