Аутентификация и подпись

В этом разделе описано, как клиентские системы аутентифицируются в HighHelp API и как формируется цифровая подпись запросов и оповещений.

Поддерживаются два алгоритма подписи:

  • RSA (RSA-SHA256) — асимметричный алгоритм с парой ключей (публичный и приватный).

  • HMAC (HMAC-SHA512) — симметричный алгоритм с одним секретным ключом.

Конкретный алгоритм и ключи задаются для кассы в панели администратора. Фактическая конфигурация кассы предоставляется специалистом HighHelp.

Структура документации по аутентификации

Подпись запросов

Подпись оповещений

  • RSA подпись оповещений
    Алгоритм формирования и проверки RSA-подписи для HTTP-оповещений, формат нормализованных данных и примеры валидации на стороне мерчанта.

  • HMAC подпись оповещений
    Алгоритм формирования и проверки HMAC-подписи для HTTP-оповещений, нормализация данных и примеры проверки подписи.

Выбор алгоритма

RSA:

  • используется, когда требуется асимметричная схема с разделением приватного и публичного ключей;

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

HMAC:

  • использует один общий секретный ключ на стороне мерчанта и платформы;

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

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

Смена алгоритма подписи

Для каждой кассы настраивается алгоритм подписи запросов и оповещений. Алгоритм определяется настройками кассы и не может быть изменен мерчантом самостоятельно. Для новых касс по умолчанию используется алгоритм RSA-SHA256. При создании новой кассы автоматически генерируется пара RSA-ключей и HMAC-ключ.

Переключение между алгоритмами

Для переключения с RSA на HMAC или обратно обратитесь к менеджеру HighHelp. Смена алгоритма выполняется на стороне платформы после согласования.

Перед переключением на HMAC убедитесь, что:

  • HMAC-ключ для кассы сгенерирован;

  • интеграция на стороне мерчанта готова к работе с HMAC-подписью;

  • обновлены скрипты для формирования подписи запросов и проверки подписи оповещений.

После смены алгоритма:

  • в личном кабинете отображается ключ настроенного для кассы алгоритма подписи: Public Key для RSA или HMAC Key для HMAC;

  • в настройках колбеков отображается текущий алгоритм (RSA или HMAC).

Получение API-ключей

API-ключи используются для аутентификации запросов к API и проверки подписи оповещений от HighHelp. В зависимости от настроенного алгоритма подписи вам потребуются разные ключи.

Порядок получения ключей зависит от настроенного для кассы алгоритма подписи:

Для RSA-SHA256:

  • Приватный RSA-ключ используется для формирования подписи запросов к API

  • Публичный RSA-ключ используется для проверки подписи оповещений от HighHelp

Инструкции по получению RSA-ключей приведены в разделе RSA аутентификация и подпись запросов.

Для HMAC-SHA512:

  • Секретный HMAC-ключ используется как для формирования подписи запросов к API, так и для проверки подписи оповещений от HighHelp

Инструкции по получению HMAC-ключа приведены в разделе HMAC аутентификация и подпись запросов.

Определение активного алгоритма

Чтобы узнать, какой алгоритм подписи настроен для кассы:

  1. Откройте личный кабинет мерчанта.

  2. Перейдите в раздел API → Настройки Callback.

  3. В модальном окне внизу отображается текущий алгоритм: Алгоритм: RSA или Алгоритм: HMAC.

  4. В зависимости от настроенного алгоритма в модальном окне будет доступен Public key (для RSA) или HMAC key (для HMAC).

При создании ключей кассы формируются HMAC-ключ и пара RSA-ключей.

При настроенном алгоритме RSA в блоке HMAC key доступна генерация ключа, если он не был сгенерирован ранее.

Секретный HMAC-ключ доступен для скачивания только в момент генерации или обновления. После скачивания в разделе API → Настройки Callback отображается маскированное значение ключа; повторное скачивание недоступно, доступно только обновление ключа.

Обновление API-ключей

Если требуется обновить API-ключи кассы, выполните следующие действия:

  1. Откройте личный кабинет мерчанта.

  2. Перейдите во вкладку API.

  3. Найдите нужную кассу и нажмите на иконку шестеренки.

  4. В открывшемся окне настроек кассы нажмите кнопку Обновить API ключи.

  5. В модальном окне проверьте информацию о кассе.

  6. Нажмите и удерживайте кнопку Сгенерировать ключи до завершения генерации.

  7. Сохраните новые ключи:

    • Private key (RSA) — новый приватный RSA-ключ;

    • Public key (RSA) — новый публичный RSA-ключ;

    • Private key (HMAC) — новый секретный HMAC-ключ.

  8. Обновите конфигурацию интеграции на стороне мерчанта, заменив старые ключи на новые.

После обновления API-ключей старые ключи перестанут работать немедленно. Убедитесь, что новые ключи корректно настроены на стороне мерчанта до начала использования. Рекомендуется выполнять обновление в период минимальной нагрузки на систему.

Обновление через кнопку Обновить API ключ заменяет все ключи: RSA Private/Public и HMAC Private. Если требуется обновить только HMAC-ключ, используйте функцию обновления в разделе Настройки Callback (см. HMAC аутентификация и подпись запросов).