Содержание

API Оркестратор

С целью упрощения установки и сокращения выделение мощностей на стороне клиента был разработан сервис, объединяющий все адаптеры - API Оркестратор. Данный сервис представляет собой группу адаптеров для взаимодействия напрямую с API банков.

Терминал Транзита, начиная с 21ой версии работает только с адаптерами в новой конфигурации. Ввиду этого при переходе на 21 версию (или последующие) потребуется выполнить ряд манипуляций для восстановления корректной работы адаптеров.

Предусмотрен следующий порядок действий:

Внимание: если настройка адаптеров банков является первичной (и не связана с переходом на 21 версию), необходимо ввести дополнительные настройки в Терминале Транзита:

Инсталляция сервиса

Системные требования для установки API Оркестратора

Для установки в ОС Astra Linux должны учитываться следующие системные требования:

  1. ОС Astra Linux Special Edition (Исполнение 1.7)
  2. СУБД PostgreSQL (14+)

Порядок установки

Для установки следует выполнить следующие действия:

  1. Скачать дистрибутив на сайте НРД
  2. Выполнить команду sudo dpkg -i nsdt-orchestrator_22.0-25_amd64.deb

После того как инсталляция была успешно выполнена, необходимо перейти к настройке Терминала Транзита (см. Введение настроек в Терминале Транзита).

Введение настроек в Терминале Транзита

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

  1. В Терминале Транзита авторизоваться под пользователем с правами Администратора и перейти в панель настроек администратора в раздел Адаптеры, здесь на начальном этапе будет отображаться только один подраздел – Терминал.
    Настройки Терминала

    В подразделе Терминал в поле Шаблоны для предзаполнения настроек (заполняются только пустые поля) следует выбрать готовый шаблон – По умолчанию (localhost), после чего автоматически будет заполнен блок Настройки подключения к шлюзу.
    Выбор шаблона при настройке Терминала

    Внимание: если адрес шлюза не соответствует значению localhost, то необходимо ввести нужный адрес. В качестве адреса указывается DNS-имя сервера либо IP адрес (при этом обязательно нужно указать протокол https://<DNS-имя или IP-адрес>). Допустимо использование исключительно протокола https, протокол http не поддерживается.

    После того как все настройки были перепроверены и введены, необходимо нажать на кнопку Отправить, после чего должны появиться подразделы Шлюз, и подразделы Адаптеров банков. Индикаторы серого цвета напротив появившихся подразделов означают, что шлюз и адаптеры еще не были сконфигурированы. Дальнейшая настройка осуществляется на шагах 2 и 3.
    Подразделы Шлюз и Адаптеры банков

  2. Необходимо перейти в подраздел Шлюз. Здесь также следует выбрать готовый шаблон в поле Шаблоны для предзаполнения настроек (заполняются только пустые поля) - поля с настройками будут заполнены автоматически. Далее важно перепроверить заполненные поля. Например, адрес сервера базы данных (поле Адрес сервера относительно шлюза) может отличаться. Следует также перепроверить порты. Дополнительно потребуется заполнить поля Имя пользователя и Пароль (в блоке Настройки базы данных).

    Внимание: если ранее использовался адаптер Сбербанка, то в настройках базы данных необходимо указать данные уже существующей БД адаптера Сбербанка. Таким образом, все пользователи старого адаптера Сбербанка будут перемещены в новый адаптер. Соответственно повторное подписание оферт в данном случае не потребуется.

    Примечание: если установка является первичной (ранее старая версия адаптера для Сбербанка/Райффайзенбанка не устанавливалась и не использовалась), то понадобится выполнить установку сервера БД PostgreSQL (см. раздел Установка PostgreSQL).

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

  3. На этом этапе осуществляется настройка адаптеров необходимых банков. Необходимо перейти в подраздел Адаптера банка. Для ускорения введения настроек в поле Шаблоны для предзаполнения настроек (заполняются только пустые поля) выберите нужный контур (тестовый или промышленный).
    Настройка адаптеров

    После выбора шаблона автоматически будет заполнена большая часть полей. Необходимо будет дозаполнить поля Идентификатор клиента и Секретный код клиента. Для Адаптера Сбербанка необходимо дополнительно выбрать файл сертификата для TLS подключения по кнопке + Выбрать файл и указать пароль к TLS-сертификату. Для Адаптера Сбербанка и Райффайзенбанка дополнительно доступна опция Выключить проверку серверного сертификата со стороны банка, при необходимости можно включить опцию. Для Адаптера Сбербанка также предусмотрена опция Включить автообновление секретного кода клиента. Для Адаптера Сбербанка также можно дополнительно указать Адрес сервиса больших файлов для ФПСУ, при этом поле не является обязательным к заполнению.

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

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

    На этом этапе настройка по восстановлению корректной работы адаптеров (в новой конфигурации), необходимая при переходе на 21ю версию Терминала Транзита, завершается.

    Примечание: если ранее использовалась старая версия адаптера Райффайзенбанка, то необходимо будет удалить ранее полученные хэши, и выполнить авторизацию заново. Подробнее см. раздел Обновление Хэша для Райффайзенбанка. Для Сбербанка никаких дополнительных манипуляций не потребуется.

Внимание: Начиная с 21 версии Терминала Транзита ссылка для редиректа (redirect_uri) должна указывать на адрес терминала, а не на адрес адаптера, как было ранее. Адрес переадресации должен соответствовать значению {адрес хоста}/adapters/{банковский модуль(sberbank|raiffeisenbankapi)}. Этот же адрес указывается в настройках Терминала Транзита в разделе Адаптеры для конкретного адаптера банка (поле Адрес, на который будет произведена переадресация при успешном получении accessToken). Данное поле автоматически заполняется соответствующей ссылкой при выборе нужного контура в поле Шаблоны для предзаполнения настроек.
Ссылка для редиректа

Ввиду этого изменения не забудьте в личных кабинетах банков указать правильные ссылки для редиректа (переадресации) или согласовать ссылку редиректа с банком:

  • Для Сбербанка - в СББОЛ в услуге SberBusinessAPI в параметре «redirect_uri» необходимо указать адрес терминала ({адрес хоста}/adapters/sberbank);
  • Для Райффайзенбанка - URI редиректа ({адрес хоста}/adapters/raiffeisenbankapi), на который сервис Райффайзенбанка будет отправлять ответы по результатам аутентификации, предварительно требуется согласовать c Райффайзенбанком.

Внимание! Если ранее адаптеры банков (старые версии) не устанавливались, и выполняется первичная настройка и установка (а не повторная, связанная с переходом на 21 версию) необходимо ввести дополнительные настройки в Терминале Транзита:

Обновление Хэша для Райффайзенбанка

В случае если ранее использовался старый адаптер Райффайзенбанка, то при переходе на 21ю версию Терминала Транзита для последующей корректной работы адаптера Райффайзенбанка необходимо выполнить ряд действий, которые обеспечат удаление старого кода авторизации (хэша) и получение нового. Необходимо выполнить следующие шаги:

  1. перейти в панель настроек администратора в раздел Банковские модули, выбрать модуль Райффайзенбанк (API), нажать на кнопку :
    Удаление Хэша из таблицы

    После того как запись из таблицы была удалена, необходимо сохранить изменения, нажав на кнопку Сохранить конфигурацию выбранного модуля:
    Сохранение конфигурации банка после удаления хэша из таблицы

  2. Нажать на кнопку Авторизоваться:
    Авторизация

    Будет выполнен автоматический переход на страницу авторизации сервиса Райффайзенбанка.

  3. На странице авторизации сервиса Райффайзенбанка необходимо ввести логин и пароль, и нажать на кнопку Войти:
    Авторизация на странице сервиса Райффайзенбанка

  4. После авторизации осуществляется переадресация на Терминал (согласно настройкам адаптера, поле Адрес, на который будет произведена переадресация при успешном получении accessToken). Открывается страничка с информацией об успешной авторизации, где необходимо нажать на кнопку Войти:
    Успешная авторизация

  5. На последнем шаге следует проверить появление кода авторизации в таблице в настройках искомого банковского модуля. Для этого необходимо перейти в Настройки:
    Переход в Настройки

    После чего перейти в раздел Банковские модули, выбрать модуль Райффайзенбанк (API) в списке, и убедиться, что в Таблице кодов авторизации появился Хэш:
    Появление Хэша в Таблице кодов авторизации

Перевыбор Хэша в настройках организации не потребуется, поскольку полученный хэш будет соответствовать старому (удаленному).

Примечание: дополнительные настройки Терминала Транзита, которые потребуется ввести при первичной установке адаптера Райффайзенбанка описаны в разделе Настройка Терминала Транзита для адаптера Райффайзенбанка.

Настройка Терминала Транзита для адаптера Райффайзенбанка

Внимание: дополнительные настройки Терминала Транзита, описанные ниже, требуется ввести при первичной установке адаптера Райффайзенбанка. Если ранее использовалась старая версия адаптера Райффайзенбанка, то необходимо выполнить действия, описанные в разделе Обновление Хэша для Райффайзенбанка.

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

  1. Перейти в панель настроек администратора в раздел Банковские модули, выбрать модуль Райффайзенбанк (API), нажать на кнопку Авторизоваться:
    Авторизация

    Будет выполнен автоматический переход на страницу авторизации сервиса Райффайзенбанка.

  2. На странице авторизации сервиса Райффайзенбанка необходимо ввести логин и пароль, и нажать на кнопку Войти:
    Авторизация на странице сервиса Райффайзенбанка

  3. После авторизации осуществляется переадресация на Терминал (согласно настройкам адаптера, поле Адрес, на который будет произведена переадресация при успешном получении accessToken). Открывается страничка с информацией об успешной авторизации, где необходимо нажать на кнопку Войти:
    Успешная авторизация

  4. Проверить появление кода авторизации в таблице в настройках искомого банковского модуля. Для этого необходимо перейти в Настройки:
    Переход в Настройки

    После чего перейти в раздел Банковские модули, выбрать модуль Райффайзенбанк (API) в списке, и убедиться, что в Таблице кодов авторизации появился Хэш:
    Появление Хэша в Таблице кодов авторизации

  5. Необходимо полученный хэш привязать к организации. Для этого нужно перейти в настройки соответствующей организации, и в поле Идентификатор Райффайзенбанка выбрать из выпадающего списка полученный на шаге 3 хэш (код авторизации). При наличии нескольких кодов авторизации в выпадающем списке, можно дополнительно ориентироваться по имени пользователя.
    Настройки организации - выбор хэша

    После того как код был выбран, необходимо нажать на кнопку Сохранить.

  6. Счета, для которых планируется получать выписки, используя адаптер, необходимо привязать к модулю «Райффайзенбанк (API)»:
    Настройки счета Райффайзенбанка

  7. После того как все шаги были пройдены, следует выполнить тестовый запрос выписки по одному из счетов, настроенных на шаге 6.

Настройка Терминала Транзита для адаптера Сбербанка

Начиная с 21го релиза произошли небольшие изменения в интерфейсе настроек модуля Сбербанка. Для удобства введения настроек были добавлены вкладки. Таблица кодов авторизации и соответственно подписание оферты были перенесены на вкладку Настройки пользователей:
Настройки пользователя в модуле Сбербанка

Сам функционал по подписанию оферты остался без изменений. Ниже подробно будет описан процесс подписания оферты.

Внимание: если ранее использовался адаптер Сбербанка, то в настройках базы данных (в настройках подключения к шлюзу) достаточно указать данные уже существующей БД адаптера Сбербанка (см. п.2 раздела Введение настроек в Терминале Транзита). Таким образом, все пользователи старого адаптера Сбербанка будут перемещены в новый адаптер. Соответственно при переходе на 21 версию повторное подписание оферт не потребуется.

Ниже будет приведен порядок действий по подписанию оферты, который потребуется выполнить при первичной установке адаптера Сбербанка или в случае регистрации нового пользователя в ССБОЛ.

Внимание: Пользователь СББОЛ, который будет подписывает оферту в Терминале Транзита, должен иметь признак ЕИО (единоличный исполнительный орган) и/или доступ к вызову /v1/crypto/eio (метод GET_CRYPTO_INFO_EIO). Это значит, что если владельцем сертификата является лицо, действующее на основании доверенности, то он не сможет подписать оферту, это может сделать только генеральный директор. В случае отсутствия доступа к этому методу его необходимо заказать – уточнить наличие доступа и заказать его можно обратившись в тех. поддержку Сбербанка по услуге SberBusinessAPI (адрес и дополнительную информацию см. на первой странице данной инструкции).

Для выполнения подписания оферты рекомендуем воспользоваться браузером Google Chrome или Mozilla Firefox. Необходимо выполнить следующие шаги:

  1. Для подписания оферты на рабочем месте подписанта необходимо войти в СББОЛ соответствующим пользователем/токеном Сбербанка – см. замечание выше.

  2. В дополнительной вкладке браузера в web-интерфейсе Терминала Транзита необходимо зайти пользователем с правами Администратора.

  3. В интерфейсе Терминала Транзита перейти в Настройки в раздел Банковские модули, в списке банков слева выбрать Сбербанк, перейти на вкладку Настройки пользователей к Таблице кодов авторизации, и нажать на кнопку Подписать оферту:
    Подписание оферты

  4. Выбрать способ подписания оферты (Токен или СМС). Для способа СМС дополнительно выбирается адрес для подписи по СМС.
    Выбор способа подписания оферты

    После нажатия на кнопку Подписать осуществляется переадресация на Терминал (согласно настройкам адаптера, поле Адрес, на который будет произведена переадресация при успешном получении accessToken). Открывается страничка с информацией об успешной авторизации, где необходимо нажать на кнопку Войти:
    Успешная авторизация

  5. Проверить появление кода авторизации в таблице в настройках искомого банковского модуля. Для этого необходимо перейти в Настройки:
    Переход в Настройки

    После чего перейти в раздел Банковские модули, выбрать модуль Сбербанк в списке, и убедиться, что в Таблице кодов авторизации появился новый код авторизации:
    Появление Хэша в Таблице кодов авторизации

  6. В интерфейсе Терминала Транзита перейти в Настройки в раздел Организации. Выбрать Организацию, для которой выполнялось подписание оферты, и в карточке данной Организации в поле Идентификатор Сбербанка выбрать соответствующий код авторизации из п.5. При наличии нескольких кодов авторизации в выпадающем списке, можно дополнительно ориентироваться по имени организации или по имени пользователя.
    Указание кода авторизации для организации

    Далее необходимо сохранить изменения по кнопке Сохранить.

  7. После выполнения всех настроек выше следует выполнить тестовый запрос выписки по любому счету этой Организации, но лучше по всем для проверки всех настроенных/выданных полномочий на стороне Банка.

Если на шаге 4 возникнет какая-либо ошибка при попытке подписать оферту, пользователю будет выведено соответствующее сообщение. Например, как на рисунке ниже:
Ошибка при подписании оферты

На рисунке выше приведен лишь один из примеров возможных ошибок.

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

Получение/обновление списка сертификатов и договоров для Сбербанка

Для того чтобы можно было обновить список сертификатов, предусмотрена кнопка :
Получение сертификатов

По кнопке обновляется таблица с сертификатами в соответствии с имеющимися изменениями:
Появление/обновление списка сертификатов

Сам список сертификатов при подписании оферты будет автоматически загружен. Ввиду этого искомая кнопка применяется только при необходимости обновить список сертификатов (при каких либо изменениях).

Примечание: по кнопке также обновляется таблица кодов авторизации. Например, если в таблице имя пользователя не заполнено, то можно при помощи данной кнопки обновить информацию в данном поле (поле заполнится).

Для работы с зарплатными ведомостями необходимо получить список договоров по кнопке :
Получение/обновление списка договоров

Появится таблица со списком договоров:
Появление/обновление списка договоров

Внимание: если список договоров претерпел какие-либо изменения (после действий с организацией/пользователем, повторного подписания оферты и т. д.), то в Терминале Транзита не забудьте обновить список договоров по кнопке .

Сбербанк - получение нового кода авторизации (взамен старого)

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

  1. В настройках организации в поле Идентификатор организации необходимо вместо установленного кода Сбербанка выбрать из списка значение Не выбрано, далее нажать на кнопку Сохранить.
    Удаление идентификатора Сбербанка в настройках организации

  2. В разделе Банковские модули перейти к настройкам модуля Сбербанка, на вкладке Настройки пользователей в блоке Таблица кодов авторизации необходимо удалить код для искомой организации:
    Удаление кода авторизации в настройках модуля

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

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

  3. После выполнения п.2 в дополнительной вкладке браузера требуется войти в СББОЛ под токеном/логином Гендиректора организации, для которой необходимо получить новый код авторизации.

  4. В настройках банковского модуля Сбербанка на вкладке Настройки пользователей в блоке Таблица кодов авторизации необходимо нажать на кнопку Подписать оферту.
    Подписание оферты

    Выбрать способ подписания оферты (Токен или СМС). Для способа СМС дополнительно выбирается адрес для подписи по СМС.
    Выбор способа подписания оферты

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

    Примечание: если при подписании оферты возникла ошибка, необходимо прислать скрин с текстом ошибки, логи Терминала Транзита и Сберадаптера на адрес технической поддержки transit-help@nsd.ru.

  5. Проверить появление кода авторизации в таблице в настройках искомого банковского модуля. Для этого необходимо перейти в Настройки:
    Переход в Настройки

    После чего перейти в раздел Банковские модули, выбрать модуль Сбербанк в списке, и убедиться, что в Таблице кодов авторизации появился новый код авторизации:
    Появление Хэша в Таблице кодов авторизации

  6. После успешного выполнения предыдущих шагов, необходимо перейти в настройки искомой организации, и в поле Идентификатор организации выбрать из списка новый код авторизации для Сбербанка, далее нажать на кнопку Сохранить.
    Установка нового идентификатора Сбербанка в настройках организации

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

Дополнительная информация и документы

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

Логи и перезагрузка

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

Бывают ситуации когда возникшая проблема может быть решена перезагрузкой шлюза и/или адаптеров. Для этого в подразделах предусмотрена кнопка перезагрузки:
Перезагрузка Шлюза/Адаптера

Если с адаптером возникли проблемы, например, в какой-то момент он перестал работать (индикатор стал серый), можно предпринять попытку его перезагрузить по указанной кнопке.

Мониторинг

В разделе Мониторинг административной панели отображаются последние значения метрик. Здесь же отображены индикаторы доступности к компонентам (Терминал, Шлюз и Адаптеры) и к сервисам (доступ к БД, к папкам Файловому шлюзу, скриптам Python):

  • красный индикатор свидетельствует о недоступности/ошибке;
  • зеленый индикатор свидетельствует о доступности/корректной работе;
  • серый индикатор может свидетельствовать о том, что компоненты (шлюз или адаптеры) не были сконфигурированы;

По кнопке Скачать данные мониторинга на компьютер пользователя загружается 7z архив. Архив предназначен для передачи в НРД, таким образом анализ содержимого архива пользователями не предусмотрен.

Подробное описание сервиса Мониторинга можно найти в разделе Мониторинг.

Отправка документов с вложением в Сбербанк

Инструкцию по отправке документов с вложением в Сбербанк можно скачать по ссылке ниже:

Скачать инструкцию по отправке документов с вложением в Сбербанк

Установка PostgreSQL

Инструкцию по установке PostgreSQL можно скачать по ссылке ниже:

Скачать инструкцию по установке PostgreSQL