Рекомендации

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

Единообразно идентифицируйте объекты

Выберите способ связи, настроенный для вашей партнерской учетной записи, и используйте его единообразно:

Direct Link — используйте facility_id Performance Hub, возвращаемый конечной точкой объектов.
Linking Identifier — используйте собственный идентификатор площадки, например идентификатор филиала, код площадки или номер магазина.

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

Инструкции по настройке см. в разделе Способы связи партнера.

Тщательно формируйте пакетные операции записи

Partner API принимает тела запросов в формате JSON и, где это указано в документации, рассчитан на пакетные процессы синхронизации. Ограничивайте размер пакетов и обеспечивайте возможность их повторной отправки.

Рекомендации по умолчанию:

Для оптимальной производительности используйте не более 1000 элементов в одном пакетном запросе.
Размер полезной нагрузки не должен превышать 10MB.
Не превышайте 5 запросов в секунду на конечную точку.

Ограничения частоты запросов можно изменить: ваш менеджер партнерской учетной записи Performance Hub настраивает их индивидуально. Если вы ожидаете импорт больших объемов, всплеск трафика при запуске или загрузку исторических данных для отчетов, согласуйте необходимую пропускную способность до начала окна изменений.

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

Безопасно повторяйте попытки

Для временных ошибок, таких как 429, 500, 502, 503 и 504, используйте экспоненциальную задержку.

Избегайте частых циклов повторных попыток. Для начала подойдет такая схема:

Повторите попытку через 1 секунду.
Повторите попытку через 2 секунды.
Повторите попытку через 4 секунды.
Если операция по-прежнему завершается ошибкой, остановитесь и отправьте оповещение.

При ошибках проверки, таких как 400 или 422, исправьте запрос, прежде чем повторять попытку.

Используйте идемпотентность там, где она поддерживается

Конечная точка разблокировки контроллера Door/Gate Controller поддерживает необязательный параметр idempotency_key. При повторном использовании того же ключа для того же партнера, объекта и двери возвращается существующий результат, если он доступен.

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

Не рассчитывайте, что каждая конечная точка записи поддерживает идемпотентность, если это не указано в документации для этой конечной точки.

Поддерживайте чистоту исходных данных

По возможности отправляйте стабильные нормализованные значения:

Используйте согласованные идентификаторы участников, планов, объектов и посещений из исходной системы.
Используйте метки времени ISO 8601 для дат и времени.
По возможности отправляйте номера телефонов в международном формате.
Передавайте валюты в полях, указанных в документации для каждой конечной точки.
Не перегружайте поля свободного текста данными, которые должны находиться в структурированных полях.

Предусмотрите инкрементную и полную синхронизацию

Большинству партнерских интеграций нужны оба варианта:

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

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

Безопасно публикуйте Access Time Windows

Рассматривайте значение access_time_windows каждого участника как полный снимок с независимой нумерацией ревизий:

Согласуйте единый монотонно возрастающий поток access_time_windows_revision между обработчиками инкрементной и сверочной синхронизации.
Повторяйте неподтвержденную или временно неудачную доставку с той же ревизией и той же нормализованной полезной нагрузкой.
Не указывайте access_time_windows, если не обновляете это значение.
Отправляйте [] только после того, как успешное получение данных из основного источника подтвердит, что окон не осталось. Никогда не превращайте тайм-аут вышестоящей системы, неполный результат или ошибку разбора в отзыв доступа.
Сохраняйте external_id и scope_key стабильными и сертифицируйте каждое сопоставление областей перед запуском в рабочей среде.
Отслеживайте давность исходных данных в соответствии с политикой актуальности, согласованной для этой интеграции.

Сведения о полных снимках, часовых поясах, переходе на летнее время, отмене и тестовых векторах см. в официальном руководстве для поставщиков данных Access Time Windows.

Относитесь к контролю доступа как к критически важной для безопасности функции

Для разблокировки контроллеров Door/Gate Controller:

Ваша система должна решить, разрешен ли человеку вход, до вызова Performance Hub.
Performance Hub возвращает 200 только после того, как контроллер на площадке подтвердит, что реле физически разблокировано.
Обычно подтверждение приходит за 3-5 секунд.
Тайм-аут означает явную неудачу разблокировки, а не успешное выполнение в фоновом режиме.
Повторяйте попытки только в соответствии с собственными правилами доступа и безопасности.

Всегда регистрируйте значения event_id и command_id, возвращаемые конечной точкой разблокировки.

Отслеживайте работу интеграции

Во время разработки и запуска используйте журналы запросов в Partner Console. В рабочей среде также ведите собственные журналы со следующими данными:

Время запроса.
Конечная точка.
Идентификатор исходной записи.
Идентификатор объекта.
Код состояния HTTP.
Тело ответа Performance Hub или сообщение об ошибке.

Эти поля значительно ускоряют поддержку и сверку, когда клиент спрашивает, что произошло.