API-интеграция: что это и как поставить задачу разработчику

Системы обмениваются действиями и данными

API-интеграция связывает программы по правилам, которые позволяют одной системе запрашивать данные или выполнять действие в другой. Для заказчика смысл в том, чтобы событие бизнеса дошло до нужного сотрудника без повторного ручного ввода. Покупать такое подключение только по названиям двух сервисов рискованно: возможность связать их ещё не описывает, что именно станет происходить. Возьмём сайт с запросом на расчёт и CRM, где менеджер обрабатывает обращения. Здесь нужна передача заявки и понятный результат, если CRM недоступна. Подключение не заканчивается на появлении тестовой карточки: компания должна видеть судьбу каждой отправки, иначе часть обращений потеряется между зелёной кнопкой на сайте и списком задач отдела продаж.

API можно представить как набор разрешённых обращений к программе. В справочнике Битрикс24 метод crm.item.add создаёт элемент CRM, в том числе сделку. Название разработчику помогает найти команду, а руководителю полезен результат: новая заявка становится записью с данными для работы. Прямого доступа к базе ради такого действия обычно не требуется. Это уменьшает число внутренних деталей, которые придётся поддерживать при изменении сервиса.

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

Сначала описывают событие бизнеса

Фраза о синхронизации сайта и CRM слишком широка, потому что под ней может скрываться передача нового обращения, обновление контактов, возврат статуса на сайт или выгрузка всей истории. Исполнитель сможет оценить разные работы, если видит начало события, получателя данных и ожидаемое действие, а также понимает, какие части явно остаются за пределами первого запуска и не входят в стоимость.

Для цветочного гипермаркета ШТАБ ИТ занимался сайтом на 1С-Битрикс, Битрикс24 и программами 1С. Между сайтом и учётной системой передавались заказы; УНФ и Бухгалтерия были связаны также с CRM. Такой перечень описывает состав внедрения, но по нему ещё нельзя оценить новую интеграцию. В задании нужно назвать отдельное действие: создать обращение, передать заказ или обновить поле, потому что исполнителю нужны поля, получатель и способ разбора отказа для каждого события. Подключение тех же продуктов не означает повторение того же объёма работ.

Для запроса на расчёт событие можно описать так: «После подтверждённой отправки формы создать обращение в CRM и назначить обработку по принятому правилу. На сайте сообщить о принятии запроса только после его надёжного сохранения. Если CRM временно недоступна, сохранить отправку для повторной передачи и уведомить ответственного о длительной задержке». Это образец задания, а не описание внедрённого проекта.

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

Какая система отвечает за значение

Двусторонняя связь требует права последнего слова: если телефон изменили на сайте и в CRM, простая команда обновить запись оставляет неясным, какое значение сохранить в обеих системах. Поэтому для каждого поля называют систему, в которой его редактируют, и условия переноса изменений. Иначе обмен начнёт возвращать старые сведения сотруднику сразу после того, как он их исправил. Идентификатор связывает записи. Внешне одинаковые имя и телефон не всегда означают одну заявку: человек вправе обратиться повторно по другой услуге. Лучше хранить отдельный номер обращения сайта и связь с карточкой CRM, чем использовать телефон как универсальный ключ. По этой связи поддержка найдёт передачу, а менеджер увидит контекст, который относится именно к текущему запросу.

Форматы тоже влияют на результат. Дата может включать время и часовой пояс, сумма — валюту и правила округления, файл — ограничения размера. В описании API ЮKassa ответ передаётся в формате JSON, то есть в структурированном виде с именами полей и значениями. Заказчику не нужно писать этот текст вручную. Достаточно получить карту преобразований: что отправляет сайт и где это оказывается в принимающей системе.

Доступ ограничен задачей

Программа действует с выданными правами. Для локальной связи Битрикс24 предлагает вебхук, а для решений, которые устанавливают на разных порталах, — приложение с OAuth 2.0. Различие описано в порядке работы с REST API, и это способы разрешить обращения, которые ещё не открывают интеграции все данные портала: даже при правильно настроенном подключении она видит только те записи, к которым допущен выполняющий запрос пользователь. Доступ на чтение безопаснее полного, когда требуется только получить сведения. Для создания обращения нужны соответствующие операции записи, но удаление клиентов или изменение всех разделов портала такой задаче не помогает. Чрезмерные права увеличивают последствия ошибки. Их сокращают до нужного объёма до запуска, чтобы случайный дефект обмена не стал массовым изменением чужих карточек.

Секрет подключения не размещают в браузере посетителя. Разработчик хранит его на защищённой стороне и объясняет владельцу порядок замены, потому что опубликованный ключ позволяет постороннему действовать от имени интеграции в пределах выданных прав. Отзыв доступа должен быть возможен без поиска бывшего подрядчика. Компания получает собственное управление подключением и инструкцию, как восстановить работу после замены ключа.

В журнал не складывают полный текст каждого запроса без разбора. Для поддержки полезны время, номер обращения, результат и понятная причина ошибки. Персональные сведения оставляют только там, где они нужны по принятому порядку обработки и хранения. Такой журнал позволяет найти потерянную заявку, не превращаясь в бесконтрольную копию клиентской базы, которую затем трудно защитить и удалить.

Обмен выдерживает повтор и задержку

Сеть может оборваться после выполнения действия. В этот момент отправитель ещё не знает результата, хотя принимающая система уже создала карточку. Если просто повторить команду создания, появится дубль. Это отдельный сценарий. Его обсуждают до оценки, потому что защита от повторного действия меняет устройство обмена и проверяется иначе, чем обычная успешная отправка.

Идемпотентностью называют поведение, при котором повтор той же операции не создаёт лишнего результата. В документации ЮKassa для этого используется ключ Idempotence-Key. Его длина ограничена 64 символами, но такая поддержка есть не у каждого метода любого сервиса, поэтому разработчик сначала читает документацию нужной операции, а затем выбирает защиту от повторов для заявки сайта. ЮKassa обеспечивает это поведение в течение 24 часов после первого запроса. Этот срок нельзя переносить на CRM: он относится к названному API. Пример полезен другим выводом. У защиты от повторов есть конкретные правила, которые исполнитель указывает в задании, а если готовой поддержки нет, он сохраняет соответствие номера обращения и созданной записи на своей стороне.

Задержка требует очереди. Отправка сохраняется, получает состояние обработки и возвращается к передаче после временного сбоя, а ответственному становится видно, что заявка ещё не появилась в CRM. Мгновенное повторение без паузы хуже управляемых попыток: оно увеличивает нагрузку на недоступный сервис и затрудняет разбор, не приближая менеджера к получению обращения. Для длительной остановки нужен отдельный сигнал и понятное действие сотрудника.

Полная выгрузка отличается от одной записи

Демонстрация одной карточки не доказывает полноту обмена. Списки могут приходить частями. Для старой версии REST API Битрикс24 в справочнике указан максимум 50 элементов за ответ списочного метода. Продолжение получают через поле next. Если исполнитель обработал лишь первую страницу, небольшой тест пройдёт, а реальная история окажется неполной без заметной ошибки на экране.

Пакет запросов решает другую задачу: метод batch позволяет объединить до 50 вызовов в один запрос. Он сокращает число отдельных обращений, но не отменяет правила каждой операции и не решает задачу сверки данных. Для заказчика важнее получить полное число записей и объяснение пропусков, чем услышать название способа ускорения обмена. Версию API фиксируют в документации подключения. У одного продукта могут одновременно существовать несколько версий с разными параметрами, поэтому копирование старого примера в новый метод способно изменить и состав ответа, и обработку ошибок. В Битрикс24 эти различия прямо описаны в сравнении версий справочника. Проверять нужно страницу выбранного метода, а не переносить общий лимит из статьи на любое действие портала.

При первоначальном переносе истории выбирают границу: какие записи нужны, за какой период и с каким состоянием. Затем отдельно запускают передачу новых событий. Так можно сверить число перенесённых обращений до включения регулярного потока, а ошибка старой выгрузки не смешается с сегодняшними заявками, которые отдел продаж ждёт уже сейчас. Это дешевле бесконечного ручного поиска недостающих карточек.

Приёмку строят по сбоям

Получатель может вернуть отказ вместо данных: в старой версии REST API Битрикс24 ошибки представлены полями error и error_description. Они нужны для разбора причины. Однако сотруднику удобнее сообщение о недостающем обязательном поле или отозванном доступе, а технический ответ сохраняют рядом с номером обращения для разработчика.

Лист приёмки связывают с бизнес-событием. Исполнитель демонстрирует обычную заявку, повторную доставку, недоступную CRM и отказ из-за неверных данных, а заказчик видит, где сохранилась каждая отправка и как она вернулась в работу после исправления. Ни один сценарий не заканчивается молчаливой потерей обращения. Если автоматическое продолжение невозможно, назначается ручное действие с конкретным ответственным.

Для файлов отдельно смотрят название, доступ и связь с обращением. Вложение, которое существует в хранилище, но недоступно менеджеру, не решает задачу расчёта. При испытаниях используют согласованные тестовые данные. Ради быстрого показа результата не стоит рассылать реальные заявки с персональными сведениями по сторонним кабинетам. После демонстрации полезно получить перечень контрольных обращений. По ним сотрудник поддержки сможет повторить поиск и увидеть весь путь от формы до карточки CRM, если через месяц возникнет похожий сбой. Для выбора уровня поддержки пригодится обсуждение интеграций сайта и CRM: результатом становится обслуживаемый процесс, а не набор команд без владельца.

Описание, которое можно оценить

Хорошая заявка на разработку умещает бизнес-событие в понятные условия. Она называет отправителя и получателя, поля, ответственного за каждое значение и действие при сбое. Объём кода появится в оценке исполнителя. Со стороны компании нужно закрыть те решения, которые нельзя извлечь из документации сервиса: кому нужна заявка, когда она считается принятой и кто разберёт исключение.

Перед оценкой приложите карту полей и образцы разрешённых тестовых обращений. Включите правило против дублей, порядок повторных попыток, доступы, журнал и сценарии приёмки, потому что пропущенный пункт вернётся после запуска в виде отдельной работы именно тогда, когда отдел продаж уже будет зависеть от обмена.

Формулировка результата может быть короткой: «Каждое сохранённое обращение сайта доходит до CRM один раз либо остаётся в видимой очереди разбора с причиной и ответственным». Её можно проверить. Такое требование позволит оценить, как разработчик обеспечит передачу обращений и организует сопровождение, даже если каждое предложение обещает подключить API двух известных продуктов.