Использование

Требования

Доступ к API GoPoints осуществляется по протоколу HTTPS, каждому методу (эндпоинту) соответствует метод HTTP и URL-путь. При передаче данных в теле запросов и ответов используется JSON с установкой заголовка Content-Type: application/json.

API GoPoints предоставляется для зарегистрированных клиентских приложений. Каждый запрос к API должен содержать следующее:

  • протокол и имя хоста для запросов HTTP. Для API среды sandbox это https://snbx-api.gopoints.net.

  • company_code это первый компонент пути URL для всех запросов, например:

    https://snbx-api.gopoints.net/000000/v1/auth/login

    Здесь 000000 это company_code, значение будет одинаковым для всех запросов, отправляемых клиентским приложением.

  • api_key это API-ключ, присваиваемый каждому клиентскому приложению (см. ниже).

API-ключи

Каждому зарегистрированному клиентскому приложению присваивается API-ключ. Все запросы, отправляемые клиентским приложением, должны включать заголовок X-Api-Key, содержащий его API-ключ. Если этот заголовок отсутствует, возвращается ошибка auth.apikey.missing. Если переданный API-ключ неверен, возвращается ошибка auth.apikey.invalid. Подробнее см. Коды ошибок .

Аутентификация для критических изменений

Когда клиентское приложение использует вызов API, совершающий критическое изменение от лица пользователя с авторизованной сессией, у таких запросов есть необязательные параметры password и otp для подтверждения аутентификации пользователя.

На API-ключе клиентского приложения может быть включено или выключено требование аутентификации для критических изменений. При включенной аутентификации для критических изменений для пользователей с установленным паролем запросы должны передавать верный пароль. Для пользователей без пароля высылается SMS с одноразовым кодом подтверждения (OTP), который должен быть передан в запросе. Когда запрос не содержит данных аутентификации для критических изменений, возвращается код ошибки critical.auth.required, а поле ответа critical_auth_method (метод аутентификации) содержит password или otp.

Когда клиентское приложение получает код ошибки critical.auth.required, ему следует запросить у пользователя пароль или OTP и затем использовать тот же вызов API, передавая соответственно параметр запроса password или otp.

Когда передан неверный пароль или OTP из SMS, возвращается соответственно код ошибки auth.password.invalid или auth.otp.invalid. Перед возвращением кода ошибки auth.otp.invalid пользователю высылается новый код (OTP). Клиентскому приложению следует запросить у пользователя повторный ввод пароля или OTP из SMS и повторно запросить тот же вызов API, передавая новое значение в параметре запроса password или otp.

Если API-ключ не требует аутентификации для критических изменений, для таких вызвов поля запроса password и otp могут быть опущены или содержать пустые строки.

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

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

Методы (вызовы) специализированного API требуют, чтобы все запросы были подписаны и содержали заголовок Authorization со значением Signature <signature>. Клиентское приложение должно использовать свой секретный ключ для создания подписей запросов. Поскольку секретные ключи могут содержать любые случайные байты, они отображаются с использованием URL-безопасной кодировки Base64 (RFC 3548, раздел 4). При создании подписи секретный ключ должен быть использован в своей изначальной форме (декодированным из URL-безопасного представления Base64).

Следующие данные запросов используются для подписи:

  1. Текущее время в виде целочисленной временной метки POSIX (TIMESTAMP).
  2. HTTP-метод запроса (METHOD).
  3. URL-путь используемого вызова (URL, не включая схему, имя хоста и параметры HTTP-запроса).
  4. Если в запросе есть параметры запроса, пары param_name=value, отсортированные по названию параметра. Значения не должны быть URL-кодированными.
  5. Если в запросе есть тело (обычно JSON для запросов POST или PUT), текст тела точно как он отправляется.

Все эти значения объединяются в многострочную строку в кодировке UTF-8 со строками, разделенными символом перевода строки (\n). Затем с использованием секретного ключа генерируется HMAC-SHA-256 этой строки в виде шестнадцатеричного дайджеста (HMAC_RESULT). Временная метка и результат HMAC формируют подпись для заголовка HTTP:

Authorization: Signature TIMESTAMP;HMAC_RESULT

Пример

Клиентскому приложению был назначен секретный ключ: SECRET_KEY_01234. При выпуске этот ключ был отображен в URL-безопасной кодировке Base64: U0VDUkVUX0tFWV8wMTIzNA==.

Это клиентское приложение совершает запрос POST с URL-адресом /000000/test/search?size=10&from=50 (включая параметры запроса) и JSON-телом {"text": "Quick brown fox", "simple": true}. Текущая временная метка: 1451638800.

Приложение формирует следующую многостроковую строку в кодировке UTF-8 (строки разделены символом \n, в конце перевода строки нет):

1451638800
POST
/000000/test/search
from=50
size=10
{"text": "Quick brown fox", "simple": true}

Шестнадцатеричный дайджест HMAC-SHA-256 этой строки с использованием ключа SECRET_KEY_01234:

f3aadb1d57b7c7b01d26e1f60ab14b09a5da5541e5fef624ac6661ed5198dd7c

В результате получается HTTP-заголовок подписи запроса (все в одну строку):

Authorization: Signature 1451638800;f3aadb1d57b7c7b01d26e1f60ab14b09a5da5541e5fef624ac6661ed5198dd7c

Разрешения доступа пользователей

Авторизация

Большинство методов (вызовов) API общего уровня требуют действительную пользовательскую сессию. При успешной авторизации API возвращает сессионный токен (session_token). Все дальнейшие запросы должны включать заголовок Authorization со значением Bearer <сессионный_токен>.

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

Профили и роли

У каждого профиля есть именованная роль, например, CLIENT, USER, PARTNER, EMPLOYEE, COMPANY. Некоторые вызовы API разрешены только пользователям с определенными ролями.

Помимо названий, роли профилей образуют иерархию. У каждого профиля есть доступ только к самому себе и другим профилям с подчиненными ролями («под ним» в иерархии). Например, профиль PARTNER, представляющий банк-партнер, имеет доступ к клиентским профилям (CLIENT) этого банка, но не к профилям другого партнера или его клиентов.

Многие объекты, такие как продукты или экземпляры продуктов, ассоциированы с какими-либо профилями. Разрешения доступа к таким объектам определяются доступом к профилям, к которым они принадлежат.

Проверяющие разрешения доступа вызовы API возвращают код ошибки auth.restricted, если доступ к объекту не авторизован.