С помощью этого API вы можете рассчитывать скидку, запрашивать бонусный баланс, подтверждать покупку, совершать оплату бонусными баллами, совершать возвраты и тд.
В качестве основного протокола используется HTTP, а значит, подходит для разработки на любом языке программирования, который умеет работать с HTTP-библиотеками. API процессинга является RPC и использует POST-запросы с телом в JSON формате. API всегда возвращает ответ в формате JSON.
Более подробное описание методов API доступно по ссылке:
https://app.swaggerhub.com/apis-docs/Samarasoft/Samarasoftloyalty/v1#
Аутентификация
Для аутентификации запросов используется Http Bearer Auth — реализация аутентификации по токену (HTTP Bearer token). Для аутентификации с помощью токена нужно передать его в http заголовке Authorization. Например:
Authorization: Bearer FFFF70it7tzNsHddEiq0BZ0i-OU8S3xVТокен доступа настраивается в файле конфигурации или через переменные окружения сервиса процессинга в параметре API_AUTH_TOKEN.
Ошибки
Если в процессе обработки запроса произойдет ошибка, API вернет объект ошибки и стандартный HTTP-код.
HTTP-коды, используемые в API
200 — Успешный запрос.
400 — Неправильный запрос. Чаще всего этот статус выдается из-за нарушения правил взаимодействия с API.
401 — Неверный токен доступа или отсутствует заголовок Authorization.
500 — На стороне процессинга что-то пошло не так. Результат обработки запроса неизвестен. Обратитесь к системному администратору.
Коды ошибок бизнес логики
shop_not_found — не найдена точка продаж
client_not_found — не найден клиент
card_blocked — карта заблокирована
card_already_activated — карта уже активирована
product_not_found — товар не найден
purchase_already_confirmed — покупка уже подтверждена
not_enough_bonus — не хватает бонусных баллов для оплаты
purchase_not_found — покупка не найдена
refund_already_exists — возврат покупки с таким же номером уже существует
Методы
| Метод | Назначение | Изменяет финансовые данные |
|---|---|---|
POST /purchase/calculate | Предварительный расчёт покупки | Нет |
POST /purchase/confirm | Сразу зафиксировать завершённую покупку | Да |
POST /purchase/create | Создать незавершённую покупку | Да |
POST /purchase/update | Изменить незавершённую покупку | Да |
POST /purchase/complete | Завершить созданную покупку | Да |
POST /purchase/refund | Полный или частичный возврат | Да |
POST /catalog/calculate | Рассчитать скидки каталога | Нет |
POST /bonus/chargebonus | Ручное начисление | Да |
POST /bonus/expensebonus | Ручное списание | Да |
Последовательности
Продажа одним вызовом: calculate -> confirm.
Заказ с отложенной оплатой: calculate -> create -> update (0..N) -> complete.
Возврат: успешный confirm или complete -> refund.
Расчёт не резервирует бонусы. Доступность списания окончательно проверяется финансовой командой. Если ответ потерян, повторяйте финансовую команду только с тем же внешним идентификатором после проверки результата.