Настройка интеграции API: как связать системы надёжно

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

Что такое интеграция систем через API

API-интеграция позволяет двум или нескольким системам автоматически обмениваться данными и запускать связанные процессы: передавать заказы с сайта в CRM, синхронизировать остатки с ERP, получать статусы доставки.

Что решить до настройки

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

Сопоставление данных

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

Webhooks или периодическая синхронизация

Webhooks используют, когда изменение нужно передать сразу после события. Например, изменение статуса платежа автоматически меняет статус заказа и запускает дальнейшие действия.

Приёмник webhook должен:

• проверять подпись или секрет внешнего сервиса;
• проверять метку времени, если она входит в протокол подписи;
• не доверять данным без серверной проверки;
• не обрабатывать одно событие дважды;
• возвращать корректные HTTP-коды.

Если внешняя система webhooks не умеет, используют периодическую синхронизацию с учётом лимитов API и допустимой задержки.

Авторизация и секреты

При интеграции с внешними API способ авторизации задаёт внешний сервис: API-ключ, OAuth 2.0, bearer token, подписанный запрос. Секреты хранят только на сервере. При OAuth токены доступа и обновления тоже хранятся на сервере, а система умеет обновлять токен и корректно реагировать, если доступ отозван. Ключи никогда не попадают в клиентский JavaScript.

Как KORVENIQ описывает настройку API-интеграций — на странице услуги.

Ошибки, повторы и очереди

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

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

Логи и мониторинг

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

Когда нужен свой REST API

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

Прямой обмен или отдельный слой

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

Если у системы нет API

Сначала изучают альтернативы: SOAP, файлы, экспорт, очередь сообщений или доступ к базе данных. Файлы в CSV, XML или JSON допустимы при пакетном обновлении, а прямой доступ к чужой базе — только при обоснованной необходимости. Программных роботов, которые работают через интерфейс, рассматривают в последнюю очередь; об этом статья RPA-автоматизация.

Этапы настройки интеграции

1. Анализ систем: процесс, доступные API и их ограничения, источники данных, места ручного переноса.
2. Проектирование интеграции API: сущности, направления, главная система, сопоставление полей, события, ошибки, скорость обновления.
3. Прототип: доступ к API, авторизация и критичные операции на тестовом контуре.
4. Реализация: клиенты API, преобразования, webhooks, фоновые задачи, очереди.
5. Тестирование: ошибки, повторные события, потеря связи, лимиты, дубли.
6. Запуск и мониторинг: поэтапное включение и контроль логов.

Стоимость

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

Частые вопросы