Сначала опишите поток данных
До кода ответьте на бумаге: какая система — источник истины для каждого фрагмента данных, какое событие запускает обмен, в какую сторону идут данные и как быстро они должны дойти. Большинство ошибок интеграций возникает, когда две системы считают своим одно и то же поле.
Опрос или вебхуки
При опросе вы по расписанию спрашиваете у другой системы изменения: просто и предсказуемо, но с задержкой и лишней нагрузкой. С вебхуками другая система сама обращается к вам, когда что-то происходит: быстро, но вы должны уметь принимать запросы в любой момент и справляться с пропущенными.
Надёжная схема часто использует оба: вебхуки для скорости и периодическую сверку, которая подбирает потерянное.
Сделайте операции идемпотентными
Сети повторяют запросы, и вы тоже будете. Если одно событие пришло дважды, результат должен быть таким же, как при однократном получении. Сохраняйте внешний идентификатор события или запроса и игнорируйте повторы, либо проектируйте обновления как «установить состояние X», а не «прибавить единицу». Без этого повторы превращаются в дубли заказов и двойные платежи.
Поставьте очередь между системами
Не заставляйте пользователя ждать медленный сторонний API. Примите событие, сохраните его, быстро ответьте и обработайте в фоне через очередь. Очередь также сглаживает всплески, позволяет приостановить обработку, пока другая сторона недоступна, и показывает, что ожидает.
Повторы, лимиты и сбои
Временные ошибки повторяйте с растущими паузами; ошибки, которые никогда не исправятся, например некорректные данные, не повторяйте. Соблюдайте лимиты запросов чужого API. События, которые продолжают падать, должны попадать в отдельное место, где человек сможет их изучить и перезапустить, чтобы одна плохая запись не блокировала всё, что за ней.
Безопасность и наблюдаемость
Проверяйте подписи или секреты вебхуков, не храните ключи API в коде и давайте каждой интеграции только нужные права. Логируйте каждый обмен с идентификатором и настраивайте оповещения на рост очереди и повторяющиеся ошибки. Интеграция, за которой никто не следит, ломается молча, и клиенты замечают это раньше вас. Подробный пример для CRM и ERP — в статье интеграция CRM и ERP.