Navbar 2
Logo
shell

Основы работы с API

Обзор

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

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

Для реализации первого варианта разработчикам потребуется Transactions API, а также endpoint GET /passes/encrypted/{encryptedId} для получения информации о карте клиента.

Для реализации второго варианта необходимо воспользоваться Templates API и Passes API (кроме вышеуказанного).

Базовым адресом API является https://api.loona.ai/version1

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

Для прохождения авторизации воспользуйтесь следующим примером

curl https://api.loona.ai/oauth/token \
  -X POST \
  -H 'Authorization: Basic Y2xpZW50Og==' \
  -d 'grant_type=client_credentials'

# Пример ответа
{
  "access_token": "eyJhb***********YW1lIjoiZ2xvYmF",
  "token_type": "bearer",
  "expires_in": 299,
  "scope": "any",
  "jti": "0e6da94a-8a35-4b6e-85da-8f54eb1be88b"
}

Все запросы API требуют аутентификации. Нужно установить HTTP-заголовок авторизации, который включает в себя тип Bearer и access token.

Пример заголовка

Authorization: Bearer eyJhb***********YW1lIjoiZ2xvYmF

Для получения токена необходимо отправить POST запрос на /oauth/token с указанием client id(идентификатор) и secret(секретный ключ) в заголовке, которые можно получить в вашем личном кабинете app.loona.ai, в разделе API -> Клиенты. Для работы с API вам потребуется создать клиент типа APP. Скопируйте и сохраните секретный ключ в безопасном месте, так как после закрытия данного окна ключ будет недоступен. Ключ можно будет заменить на новый в любое время, тогда как старый станет недействительным. Что касается client id, то он будет доступен для копирования всегда.

Создание заголовка для получения access token: - Идентификатор клиента и секретный ключ объединяются с использованием двоеточия (:) в качестве разделителя <clientId>:<secret> - Полученная строка кодируется с использованием кодировки Base64. - Закодированная строка добавляется после типа "Basic".

А также нужно указать параметр grant_type: *client_credentials*

Транзакции

Идемпотентность

В контексте API идемпотентность означает, что многократные запросы обрабатываются так же, как однократные. Это значит, что получив повторный запрос с теми же параметрами(в частности, passId), Loona выдаст в ответе результат исходного запроса. Такое поведение помогает избежать нежелательного повторения транзакций. Например, если при проведении транзакции возникли проблемы с сетью, и соединение прервалось, вы сможете безопасно повторить нужный запрос неограниченное количество раз. GET-запросы являются по умолчанию идемпотентными, так как не имеют нежелательных последствий. Для обеспечения идемпотентности POST-запросов используется заголовок Idempotence-Key (или ключ идемпотентности).

Пример заголовка

Idempotence-Key: anyUniqueIdentifier

Значение QR кода на карте

В зависимости от настроек в личном кабинете QR код может иметь следующие значения: - статичный уникальный идентификатор карты - статичный уникальный идентификатор карты в зашифрованном виде - динамичный уникальный идентификатор карты в зашифрованном виде (меняется после каждой транзакции)

Значение QR кода, который по умолчанию представляет собой статичный зашифрованный идентификатор карты, нужно отправить в HTTP-заголовке X-Loona-Encrypted-Key при запросах на проведение транзакции. Если encryptedId недействительный, тогда система выдаст ошибку 400. Возможной причиной такой ошибки может быть отсутствие интернета на устройстве владельца карты, вследствие чего карта не была обновлена после последней транзакции (ее в любое время можно обновлять вручную при подключении к интернету). Если хотите избежать подобного сценария, то всегда можете Отключить динамический QR-code в настройках макета в вашем личном кабинете.

Пример заголовка

X-Loona-Encrypted-Key: 6179518025

Типы транзакций

Пример запроса

curl https://api.loona.ai/version1/transactions/<transaction type> \
  -X POST \
  -H 'Authorization: Bearer <Токен доступа>' \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'X-Loona-Encrypted-Key: <Зашифрованный идентификатор карты, полученный через чтение значения QR кода>' \
  -H 'Content-Type: application/json' \
  -d '{
        "passId": <идентификатор карты в системе Loona, полученный в ответе запроса GET под полем id>,
        "purchaseId": "<идентификатор заказа/покупки/действия на вашей стороне>"
        // другие поля
      }'

На данный момент в рамках системы лояльности Loona поддерживаются следующие типы транзакций:

Информацию о запросах и ответах каждого из вышеперечисленных запросов можете найти в детализированной документации Loona API

Ошибки

The Kittn API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell