Введение в 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_version | string | Версия сборки службы. | Нет |
| code | string | Код ошибки. | Нет |
| endpoint_url | string | URL-адрес конечной точки, которая завершилась с ошибкой. | Нет |
| long_message | string | Подробное описание возникшей ошибки. | Да |
| member_identification | string | Идентификатор Участника. Пример: bankName. | Нет |
| service_name | string | Название службы. | Нет |
| short_message | string | Краткое описание сообщения об ошибке. | Да |
| timestamp | number (int64) | Временная метка события. Пример: 1651224866578. | Да |
| troubleshooting_id | string | Идентификатор, указывающий на источник возникновения ошибки. | Нет |
Аутентификация
Для аутентификации запросов необходимо использовать 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, иначе Токен автоматически аннулируется.