Какая система хранит главную запись?
Для каждой сущности, которая передаётся между системами, — клиента, заказа, наряда на работы — запишите, какая система за неё отвечает и по каким идентификаторам она находится в остальных. Если номер телефона клиента можно изменить и в приложении, и в CRM, кто-то должен решить, чьё изменение главнее, а интеграция должна знать об этом решении. Чем раньше такие правила записаны, тем меньше спорных случаев потом приходится разбирать вручную.
Опишите обязательные поля, их форматы и допустимые переходы между статусами. Бриф на интеграцию должен описывать события и результаты, а не только список адресов API: «когда заказ подтверждён на портале, в учётной системе появляется наряд с такими-то полями, а портал показывает его номер». Такую формулировку можно проверить, а список адресов — нет.
Заранее решите, что происходит, если записи противоречат друг другу или одно и то же поле меняется в обеих системах одновременно. Затем уточните права доступа, ограничения на число запросов и различия между тестовой и рабочей средой по актуальной документации поставщика, не по коду, скопированному из старого проекта.
Что происходит, если запрос не прошёл или повторился?
Сеть подводит самым неудобным образом. Запрос может успешно выполниться на удалённой стороне, а ваша система так и не получит ответа — и для неё это будет выглядеть как сбой. Если программа просто отправит запрос ещё раз, у клиента может появиться два заказа или два платежа.
Защититься от этого помогают постоянные идентификаторы операций (их часто называют ключами идемпотентности): по ним принимающая система узнаёт повтор. Добавьте и сверку: прежде чем повторять действие, которое, возможно, уже выполнено, проверьте его фактическое состояние. Многие сервисы могут прислать одно и то же уведомление (webhook) несколько раз, поэтому принимающая сторона должна спокойно обрабатывать повторы.
Если объём это оправдывает, опишите очереди, тайм-ауты и отдельное место, где неудачные сообщения ждут разбора. Статусы, которые видит пользователь, должны быть честными: неудавшаяся передача ни в коем случае не должна отображаться как выполненная. И заранее определите, что нужно оператору, чтобы довести дело до конца вручную: какая запись затронута, что было отправлено и что пришло в ответ.
Как проверить, что интеграция работает?
Опишите сквозные сценарии приёмки и прогоните их в среде, максимально близкой к рабочей. Включите новые и уже существующие записи, отсутствующие или неправильные данные, истёкшие токены доступа, уведомления, пришедшие дважды, и временно недоступный сервис поставщика. Хорошо, если эти сценарии сохраняются и после запуска: их можно повторять после любого изменения — на вашей стороне или у поставщика.
В каждом сценарии смотрите на итоговое состояние в обеих системах. Успешный HTTP-код говорит лишь о том, что запрос принят, а появилась ли нужная запись с правильными полями — это отдельный вопрос. Затем решите, что записывается в журнал, кто получает оповещения и как обновляются доступы до того, как истечёт их срок.
И наконец, относитесь к описанию интеграции как к живому документу. Поставщики меняют свои API, отключают старые версии и вводят новые ограничения, поэтому назначьте человека, который следит за этими изменениями. Иначе удачный пилот после очередного обновления API может превратиться в хрупкую зависимость. Интеграции стоит планировать с самого начала разработки приложения на заказ.
Чек-лист: интеграция приложения
- Запишите, какая система отвечает за каждую сущность, по каким идентификаторам записи совпадают и в каком формате поля.
- Решите, что происходит, если записи в системах противоречат друг другу.
- Защитите повторные операции постоянными идентификаторами и сверкой.
- Проверяйте не только коды ответа, но и итоговые записи в обеих системах.
- Назначьте ответственных за мониторинг, обновление доступов и изменения у поставщиков.
Пример: передача наряда без дублей
Клиентский портал передаёт подтверждённый наряд на работы в учётную систему. У каждой передачи есть постоянный идентификатор операции, поэтому, когда после тайм-аута запрос отправляется повторно, учётная система узнаёт повтор и не создаёт второй наряд.
Пока принимающая система не подтвердит запись, портал показывает статус «передаётся», а не «готово». Если результат так и остаётся неясным, оператор видит наряд, отправленные данные и последний ответ и может вручную сверить обе системы. Так даже редкий сбой не превращается в загадку: видно, что произошло и на каком шаге.
