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

Начните с одного бизнес-события

Фраза «связать сайт и CRM» оставляет слишком много вариантов. Одна компания хочет передавать только новое обращение, другая — двусторонне обновлять клиента, заказ, оплату и документы. Выберите первое событие и опишите результат: «После принятия формы в системе появляется обращение с источником и ответственным».

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

Укажите, кто использует результат. Менеджеру может быть важен контакт и комментарий, аналитике — устойчивый идентификатор обращения и источник, клиенту — подтверждение приёма. Эти потребности связаны одним событием, но не обязательно выполняются одновременно. Разделение поможет правильно объяснить задержку внешней системы.

Составьте карту данных

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

Если обе системы могут менять поле, нужен порядок разрешения конфликтов. Правило «берём последнее» требует определить, что считается временем изменения и насколько надёжны часы источников. Часто проще назначить одного владельца поля и разрешить остальным системам только чтение.

Выберите способ запуска обмена

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

Проверьте гарантии конкретного API. Например, документация Stripe описывает повторы доставки, проверку подписи и отсутствие гарантированного порядка событий. Это пример поведения одного поставщика, а не утверждение, что все webhook устроены одинаково. В вашем контракте нужны фактически доступные гарантии двух выбранных систем.

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

Спроектируйте повторы до первой ошибки

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

У поставщиков различаются правила ключей, сроки хранения и реакции на изменившееся тело запроса. Документация идемпотентных запросов Stripe показывает один конкретный контракт. Для собственной интеграции письменно задайте область уникальности ключа, срок хранения результата и поведение конфликтующего повтора.

Разделите временные ошибки и ошибки данных. Недоступность сервиса допускает управляемый повтор с паузой; неверный обязательный идентификатор обычно требует исправления. Бесконечно повторять любой неуспех нельзя: нужен предел попыток, очередь проблемных событий и ответственный за разбор.

Защитите доступ и сделайте обмен наблюдаемым

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

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

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

Подготовьте таблицу приёмки

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

Приёмка должна проверять конечный результат в обеих системах. HTTP-ответ без сохранённой записи недостаточен; запись без связи с исходным событием затруднит последующую сверку. Для формы отдельно полезен протокол проверки принятой заявки и цели Метрики.

Что передать разработчику

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

Результат проектирования API-интеграции — контракт обмена и проверяемые сценарии. Если одновременно выбирается система, используйте матрицу готовой и заказной CRM. Если данные будут показываться клиенту, заранее согласуйте границы личного кабинета, чтобы интерфейс не обещал больше, чем способен предоставить источник.