Интеграция по API — что это и для чего используется

API или Application Programming Interface, что переводится как «программный интерфейс приложения», обеспечивает взаимодействие между приложением (сервером), предоставляющим его, и внешними системами (ПО, приложениями), которые принято называть клиентами. Давайте рассмотрим, как это все работает на примере API телефонии от Телфин. Мы все расскажем и покажем на реальных примерах, опираясь на наше API для интеграции с внешними системами.

• Зачем нужна API-интеграция, если есть эти варианты?
• Интеграция через API данные: подходы, технологии, основные понятия
• Аутентификация, методы, форматы передачи данных при интеграции через API IP телефонии
• Возможности API сервиса виртуальной телефонии Телфин
• Как сделать интеграцию по API?

Почему API интеграция с IP-телефонией лучше, чем при использовании других вариантов? А есть ли варианты, помимо API? Да, есть. Давайте кратко их рассмотрим.

Готовые модули интеграции

Любой разработчик какого-то продукта или сервиса стремится сделать его интеграцию для клиентов со сторонними решениями проще и комфортнее. Мы в Телфин тоже придерживаемся этого подхода и предлагаем готовые интеграции с такими популярными продуктами.

Если вам нужно «подружить» IP-телефонию с каким-то из продуктов, для которых есть готовые интеграции, сделать это легко: нужно просто выполнить несколько несложных действий в личных кабинетах: никакого кодинга не требуется.

Инструкция по настройке интеграции с Битрикс24

Инструкция по настройке интеграции с amoCRM

Интеграция через сторонние сервисы

Все происходит через сервисы-«посредники», которые еще называют коннекторами. Нужно в них зарегистрироваться, выбрать «источник» и «приемник» данных и все, можно работать.

Зачем нужна API-интеграция, если есть эти варианты?

У рассмотренных выше способов есть ряд ограничений, из-за чего использовать их могут не все. Например, готовые модули для интеграции разрабатываются только для небольшого количества сторонних программ и сервисов. И если у вас какое-то ПО, которого нет в этом списке, придется использовать другой способ. У посредников список поддерживаемых программ и сервисов зачастую намного шире. И здесь есть свои нюансы:

• Во-первых, возможности при такой интеграции могут быть ограничены: вы получаете решение «как есть», часто без возможности кастомизации под себя;
• Во-вторых — наличие посредника в цепочке взаимодействия между API сервиса телефонии и вашего ПО (сервиса, решения) ведет к повышению рисков информационной безопасности.

API интеграция лишена этих недостатков. При использовании этого способа интеграции вы можете настраивать взаимодействие максимально гибко, адаптировать решение под себя. Ну и к безопасности вопросов меньше: никаких посредников, а значит и угроз попадания важных для компании данных в третьи руки. Скорость работы в этом случае выше, так как в цепочке взаимодействия отсутствуют посредники.

Интеграция через API данные: подходы, технологии, основные понятия

В Телфин при проектировании API выбрали архитектурный стиль REST. Он в последнее время набирает все большую популярность при проектировании программных интерфейсов WEB-приложений. За счет его использования обеспечивается гибкость и отказоустойчивость API, высокая производительность, простота масштабирования.

REST API базируется на пяти основных принципах:

1. Использование клиент-серверной архитектуры. Сервер, предоставляющий API данные, реализует в себе всю логику хранения данных. На стороне клиента (приложения или сервиса, обращающегося к API) реализуется только функциональное взаимодействие с сервером и интерпретация полученных от него сведений. За счет этого обеспечивается масштабируемость, а также простота внесения изменений в систему (логику обработки данных): все при необходимости делается на сервере, не касаясь при этом каждого клиента.
2. Применение кэширования. Это позволяет добиться высокой скорости обработки запросов при API-интеграции. Если изменения в нужных клиенту данных не происходит, при очередном запросе отдается то, что хранится в кэше — серверу не нужно «ходить» в базу данных, что положительно влияет на скорость.
3. Использование принципа stateless. При его реализации информация о клиентских сессиях не хранится на сервере. За счет этого уменьшается время обработки запросов, обеспечивается возможность организации кэширования, создаются условия для эффективного масштабирования системы.
4. Принцип Code on demand. Подразумевает передачу клиенту исполняемого кода (например, код страницы при обращении браузера к сайту по адресу). Это, опять же, обеспечивает гибкость взаимодействия и дает широкие возможности по масштабированию.
5. Поддержка слоистой архитектуры (Layered system). Подразумевает, что сервер и клиент не должны знать, по какой цепочке проходят запросы и ответы, и изменения поведения посредников (прокси и пр.) не оказывают влияния на логику сервера и клиента. За счет этого изменения в общую инфраструктуру и логику работы сложных систем можно вносить без изменений на стороне клиента и сервера.

Аутентификация, методы, форматы передачи данных при интеграции через API IP телефонии

Эксперты Телфин используют архитектуру REST API и протокол HTTP. В этом случае запрос имеет типовую структуру, которая включает: URL, указывающий на адрес API, метод API, который сообщает серверу, какие действия от него требуются для клиента, заголовок со служебной информацией и тело запроса.

Пример запроса на получение информации об авторизованном пользователе

```shell
  curl -H "Authorization: Bearer 1sz9xnbNsgIXF5uGEeL0df2Iyec29W" https://hostname/api/ver1.0/user/
  {
    "admin": false,
    "client_id": 12,
    "dealer_id": null,
    "extension_group_id": null,
    "extension_id": null,
    "id": 20,
    "login": "client1"
  }
```

Здесь Authorization:

• Токен для авторизации клиента;

  Bearer 1sz9xnbNsgIXF5uGEeL0df2Iyec29W

• URL для доступа к API;

  https://hostname/api/ver1.0/

• Метод или ресурс, который запрашивает клиент;

  ... user/

• Все, что далее заключено в скобки { } — тело запроса.

В API телефонии Телфин (как и большинстве других, разработанных в соответствии с подходом REST API) применяются следующие типы методов:

• GET. Используются для получения какой-то информации от API. Никаких изменений при вызове таких методов в БД сервера или еще где-либо не происходит. Пример такого метода нашего API.

  `GET /api/ver1.0/client/client_info/{client_id}`

  (подробнее о нем и других методах — здесь);
• POST. Используются для создания ресурсов (записей в БД). Пример из нашего API;

  `POST /api/ver1.0/client/{client_id}/agent/local`

• DELETE. Используются для удаления ресурсов (записей в БД). Пример из API Телфин;

  `DELETE /api/ver1.0/client/{client_id}/agent/local/{agent_id}`

• PUT. С помощью таких методов производится редактирование (обновление) ресурсов (отдельных полей в записях в БД). Пример.

  `PUT /api/ver1.0/client/client-info/{client_id}`

Посмотреть примеры запросов/ответов вы можете с помощью специального интерфейса.

Для обмена данными в API, созданных в соответствии с архитектурой REST, используются форматы JSON и XML. Причем, они могут применяться параллельно: например, тела запросов POST и PUT передаются в формате JSON, а некоторые типы ответов, например, об ошибке, — в виде XML-структур, включающих код ошибки и ее описание. С обоими форматами без каких-либо проблем работают любые современные языки программирования, приложения и сервисы.

Возможности API сервиса виртуальной телефонии Телфин

В API Телфин реализовано огромное количество методов для эффективного взаимодействия с внешними системами (клиентами). Предлагаемый нами API-интерфейс позволяет реализовать следующие функции и возможности:

• Формирование уведомлений о поступающих входящих вызовах;
• Инициирование с помощью сторонней системы исходящих звонков;
• Формирование и отправка клиенту (приложению или сервису) истории вызовов абонентов IP-телефонии;
• Выгрузка по запросу записей совершенных и входящих звонков;
• Реализация функционала для настройки параметров добавочных номеров для сотрудников;
• Управление очередями звонков;
• Функция перехвата вызовов;
• Прослушивание телефонных разговоров;
• Перевод звонка на указанный номер;
• Реализация суфлера;
• Функционал для организации конференции;
• Постановка осуществляющихся звонков на удержание и их снятие с удержания;
• Парковка вызова;
• Обработка вызова в интерактивном режиме, в зависимости от его параметров. В качестве параметров могут выступать: номер звонящего или вызываемого абонента и т.п.);
• Получение перечня назначенных сотрудникам компании добавочных номеров;
• Формирование оповещений о балансе лицевого счета.

Как сделать интеграцию по API?

Подключение к IP-телефонии по API осуществляется в несколько этапов.

1. Для начала приложение, которое будет обращаться к серверу, должно быть определено как доверенное. При этом необходимо установить уровни доступа. Делается это на стороне «поставщика» API через web-интерфейс.
2. Затем необходимо на стороне клиента организовать отправку запросов к API в соответствии с требованиями, описанными в спецификации поставщика услуг. Это сводится к организации формирования заголовка с токеном (либо логином/паролем, в зависимости от того, какой способ аутентификации предусмотрен разработчиками API).
3. После необходимо организовать прием ответов от API и их интерпретацию.

API — это «переводчик», который позволяет обеспечить взаимопонимание между клиентом и сервером, предоставляющим его. Это гибкий и удобный способ обеспечить качественное эффективное взаимодействие между программами (сервисами).

Иван

руководитель проектов

Работаю в Телфин более 10 лет, провожу вебинары, представляю компанию на конференциях, руковожу группой менеджеров по продажам.