Интеграция по API: вопросы до первого запроса

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

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

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

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

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

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

Продумайте, кто узнает о неудачном обмене и что сможет сделать дальше. Сообщение должно содержать достаточно контекста: время, объект, этап и характер ошибки. Не превращайте журнал в бесконтрольное хранилище паролей, токенов и личных сведений.

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

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

Заранее определите, как восстановить обмен после исправления. Нужно ли повторить конкретную операцию, сверить состояние или выполнить безопасную синхронизацию? Ответ лучше получить до запуска. В аварийный момент импровизированный массовый повтор может создать больше проблем, чем исходный сбой.

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

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

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