Точка запуска
Действие сотрудника, событие системы, webhook, очередь или расписание.
API-интеграции: связываем системы вокруг бизнес-процесса
Проектируем интеграцию не как набор отдельных запросов, а как управляемый обмен между системами: определяем владельца данных, точки запуска, идентификаторы объектов, правила повторов и результат, который должен увидеть сотрудник.
Система A ↔ API ↔ система B
Источникобъект и событие процесса
→API-адаптерконтракт, авторизация, проверки
→Внешняя системаоперация или данные
→РезультатID, статус или ошибка
→С чего начинаем
Сначала описываем бизнес-операцию, потом выбираем API-методы
Один и тот же сервис может предоставлять десятки методов, но рабочему процессу обычно нужен небольшой согласованный набор.
Источник данных
Для каждого значения фиксируем систему-владельца и не создаём двустороннее редактирование без правила конфликта.
Связь объектов
Сохраняем внешние идентификаторы, чтобы обновлять тот же заказ, документ или клиента, а не искать его заново по названию.
Бизнес-результат
После вызова сотрудник получает понятный итог: объект создан, статус обновлён, требуется исправление или повтор.
Контракт
Передача данных должна быть воспроизводимой при повторном запуске
Интеграция должна понимать, что уже создано, что можно обновить и какая операция безопасна для повторного вызова.
Событие→Проверка входных данных→Поиск связи→API-запрос→Сохранение внешнего ID→Возврат результата
Архитектура
Что определяем для каждого внешнего API
Технические детали зависят от конкретного сервиса, но набор архитектурных вопросов остаётся похожим.
Авторизация
Храним токены и ключи вне public-кода, учитываем срок действия и минимально необходимые права.
Лимиты и пагинация
Не предполагаем, что один запрос вернёт все данные; объём и частоту запросов подстраиваем под ограничения сервиса.
Идемпотентность
Для операций создания используем внешний ключ, собственный журнал или поддерживаемый сервисом механизм защиты от дублей.
Timeout и ошибки
Различаем временную недоступность, ошибку авторизации, неверные данные и бизнес-отказ внешней системы.
Версия API
Контракт интеграции фиксируем так, чтобы изменение внешней версии можно было локализовать в одном адаптере.
Надёжность
Успешный HTTP-ответ ещё не всегда означает завершённую бизнес-операцию
Некоторые сервисы принимают запрос в обработку и возвращают окончательный результат позже. Поэтому технический ответ и бизнес-статус храним отдельно.
Асинхронные операции
После создания сохраняем внешний ID и проверяем дальнейшее состояние через webhook или API.
Очередь
Критичные задания сначала фиксируем, затем выполняем внешний вызов и сохраняем число попыток.
Retry
Повторяем только операции, для которых это безопасно, с ограничением числа попыток и интервалом между ними.
Мониторинг
Видим не только исключение в логе, но и зависшие задания, частые ошибки и результат конкретной операции.
API или webhook
API отвечает на наш запрос, webhook сообщает о событии со стороны другой системы
Во многих проектах они работают вместе: API создаёт или читает объект, webhook возвращает изменение его состояния.
Создаём объект
Наш сервис вызывает API.
Сохраняем связь
Внешний ID относится к объекту CRM или ERP.
Ждём событие
Внешняя система сообщает об изменении.
Проверяем состояние
При необходимости запрашиваем актуальные данные через API.
Обновляем процесс
Возвращаем сотруднику подтверждённый бизнес-статус.
Масштабирование
Новый сервис не должен требовать переписывать весь процесс
Общую бизнес-логику отделяем от адаптера конкретного поставщика, когда процесс предполагает несколько внешних систем одного типа.
Подход
Один процесс — несколько изолированных API-адаптеров
CRM или внутренний сервис работает с единым набором бизнес-команд, а особенности авторизации, полей и ответов каждого API остаются внутри своего адаптера.
Вопросы
Частые вопросы
Можно интегрировать сервис, если у него есть API?
Наличие API — необходимое, но не достаточное условие. Проверяем, доступны ли именно нужные операции, данные, события, права и ограничения для вашего сценария.
Нужно синхронизировать все поля в обе стороны?
Обычно нет. Для каждого значения лучше определить владельца и передавать только то, что нужно следующему этапу процесса.
Как защищаться от дублей при повторном запросе?
Используем поддерживаемый API механизм идемпотентности либо собственную связь объектов и журнал выполненных операций.
Что происходит, если внешний API временно недоступен?
Критичное задание не теряем: сохраняем ошибку, выполняем безопасный повтор по правилам и показываем итоговый статус сотруднику.
Когда нужен webhook?
Когда внешний сервис может сам сообщить о результате или изменении. Это позволяет не опрашивать API постоянно и быстрее продолжать процесс.
Можно подключить несколько поставщиков одного типа?
Да. Если бизнес-процесс общий, целесообразно оставить единый интерфейс и вынести особенности каждого поставщика в отдельный адаптер.
Какие две системы сейчас приходится связывать вручную?
Покажите один объект и его путь: что создаётся, какие данные передаются и какой результат должен вернуться. Этого достаточно, чтобы определить минимальный API-контракт.