Skip to main content

Введение в API TKEY7

TKEY7 позволяет сети географически распределённых финансовых учреждений обмениваться ценностями по всему миру за считаные секунды, используя цифровые расчётные инструменты на основе блокчейна и платёжные сообщения стандарта ISO 20022 для Клиринга и расчётов по международным платежам в режиме реального времени.

API TKEY7 построены на широко известных REST-принципах и обладают предсказуемым поведением. API поддерживает DELETE, POST и GET запросы. API всегда возвращает ответ в формате JSON, независимо от типа запроса.

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

ПараметрОписание
headerПараметры, которые передаются в HTTP-заголовке запроса.
bodyПараметры, которые передаются в теле запроса.
pathПараметры, которые передаются как часть пути в URL. Выделяются фигурными скобками — {}.
queryПараметры, которые передаются, как параметры URL-запроса. Указываются после знака ?.

TKEY7 немедленно обрабатывает полученный запрос и возвращает результат обработки. Ответ содержит код ответа HTTP, стандартные заголовки и при необходимости тело ответа.

Основная сущность API TKEY7 — это объект. Каждый запрос связан с выполнением определённого действия над объектом, например, создание или удаление объекта, получение информации о нём.

При успешной обработке запроса TKEY7 возвращает в теле ответа созданный, изменённый или запрошенный объект, или список объектов. Параметры тела ответа зависят от запроса.

Если с запросом что-то не так, то для кодов ответа HTTP: 400, 401, 403, 404, 406, 409 и 500 — вернётся тело ответа в формате JSON с описанием ошибки.

НаименованиеТипОписаниеОбязательный
build_versionstringВерсия сборки службы.
Нет
codestringКод ошибки.
Нет
endpoint_urlstringURL-адрес конечной точки, которая завершилась с ошибкой.
Нет
long_messagestringПодробное описание возникшей ошибки.
Да
member_identificationstringИдентификатор Участника. Пример: bankName.
Нет
service_namestringНазвание службы.
Нет
short_messagestringКраткое описание сообщения об ошибке.
Да
timestampnumber (int64)Временная метка события. Пример: 1651224866578.
Да
troubleshooting_idstringИдентификатор, указывающий на источник возникновения ошибки.
Нет

Аутентификация

Для аутентификации запросов необходимо использовать OAuth-токен и передавать его с каждым запросом.

curl https://ru.bankname.payments.tkey7.com/client/v1/api/digital-accounts \
-H "Authorization: Bearer <OAuth-токен>"

Пользователю, чтобы использовать возможности TKEY7, требуется запросить разрешение на получение OAuth-токена у Пользователя-Участника с Правами доступа Администратор.

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

Получение токена доступа

Шаг 1. Авторизоваться в Веб-офисе

Пользователю-Участнику с Правами доступа Администратор требуется выполнить авторизацию на клиентском портале.

Шаг 2. Создать Пользователя с Правами доступа Наблюдатель или Менеджер

Пользователю-Участнику с Правами доступа Администратор требуется перейти в раздел «Управление пользователями» и создать нового Пользователя с Правами доступа Наблюдатель или Менеджер.

Шаг 3. Создать JWT OAuth-токен

Пользователю-Участнику с Правами доступа Администратор необходимо перейти в раздел «Управление токенами доступа» и создать новый OAuth-токен для Пользователя с Правами доступа Наблюдатель или Менеджер.

Для создания JWT требуется указать:

  • Идентификатор Участника в TKEY7, если у организации несколько развёрнутых узлов Участников.
  • Идентификаторы Цифровых счетов, для которых будет разрешён доступ.
  • Разрешённые IP-адреса, с которых Пользователь может выполнять запросы.
  • Разрешённые конечные точки, к которым Пользователь получит доступ.

Сеанс токена доступа — 24 часа, затем Пользователю-Участнику с Правами доступа Администратор требуется создать новый Токен доступа.

Пользователь-Участник с Правами доступа Наблюдатель или Менеджер должен обновлять Токен доступа каждые 15 минут или раньше с помощью вызова через конечную точку /oauth-token/refresh, иначе Токен автоматически аннулируется.

Page last updated: 26 November 2022