API-интеграция сайта с внешними сервисами: как спроектировать обмен без хаоса

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

Зафиксируйте направление данных

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

Согласуйте формат и обязательные поля

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

Интеграция должна быть идемпотентной

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

Продумайте повторные попытки

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

Не храните секреты в публичном коде

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

Что должно быть в техническом описании

• список методов и событий;
• схемы запросов и ответов;
• правила авторизации;
• лимиты и таймауты;
• правила повторов;
• обработка ошибок;
• ответственные системы за каждое поле.

Если интеграция затрагивает 1С, полезно отдельно определить правила синхронизации товаров, цен, остатков и заказов. Подробнее — на странице интеграции сайта с 1С. До разработки сложного обмена также имеет смысл подготовить техническое задание.