Open API

Инструкция по интеграционному API Senim для разработчиков приложении

1. Общие сведения

Данный документ адресован разработчикам для ознакомления со структурой и принципами работы интеграционного модуля системы Senim и организации взаимодействия между сторонними информационными системами на основе открытой технической спецификации программных интерфейсов. Доступ к документации предоставляется заинтересованным Партнерам.

1.1. О системе Senim

Senim – это смарт кошелек all in one, с помощью которого можно оплачивать товары и услуги, парковку, проезд на общественном транспорте, покупать билеты в кино и заправлять топливо, не выходя из машины. В данном документе рассматривается оплата через QR код, который генерируется в нашей системе и отображается у нашего Партнера.

1.2. Доступ к системе

Для оптимизаций работы Партнеру предоставляется тестовая площадка, к которой можно подключится через VPN. Для скачивания кроссплатформенного клиента OpenVPN с открытым исходным кодом перейдите по ссылке https://client.pritunl.com/ и выберите клиента в соответствии с ОС, для мобильного приложения скачайте в Google Play приложение Openvpn. Профиль для подключения виртуальной частной сети будет предоставлена менеджером по сопровождению после настройки тестовой площадки для Партнера.

Инструменты тестовой площадки для интеграции:

  • Тестовая организация с кошельком - для приема оплат, предоставляется менеджером по сопровождению, на основе БИН организации и пароля для входа в личный кабинет.

  • Тестовый пользователь – для тестирования оплат через приложение Senim.

  • Тестовой личный кабинет - https://testcabinet.senim.kz– содержит информацию об организаций, балансу, торговым точкам, операциям и настройки для интеграций.

  • Тестовое мобильное приложение - на платформе android в формате Android Package(APK).

Тестовая среда Боевая среда

2. External API Integration

2.1. Этапы настройки интеграции онлайн заказа

Настройки для интеграции находятся в личном кабинете Партнера во вкладке “Интеграция”. Для обеспечения информационной безопасности и упрощения аутенфикации в каждом заголовке запросе сторонней системы используются токен X-Senim-API-Token, который сгенерирован в личном кабинете.

Запрос/ответ используют заголовок – сущность Content-Type: application/json.

Ответ от системы Senim возвращается с подписью в целях достоверности данных. Виды шифрования используемые в интеграции: RSA и ЕСС на выбор Партнера, для проверки подписи используются алгоритмы SHA256WithRSA и SHA256withECDSA соответственно, провайдер BC.

CallbackUrl – url адрес Партнера, куда будет стучаться система после успешной оплаты.

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

2.2. Генерация QR кода

Данный запрос используется для получения сгенерированного QR кода в виде ссылки и картинки: POST https://senim.kz//api/integration/v2/qr

Данные POST запроса:

Название

Описание

Формат

Mandatory

branchId

ID торговой точки

int

M

orderId

ID заказа в вашей int системе

int

M

orderAmount

сумма заказа в тенге

int

M

dimension

размер qr кода в пикселях

int

M

duration

время жизни qr кода в секундах

int

M

format

0 – ссылка 1 – картинка + ссылка

int

M

print

Для печати

boolean

O

canChangeAmount

разрешить пользователю менять сумму заказа

boolean

O

callbackUrl

Для отправки статуса после оплаты , по умолчанию отправляется на url указанный в настройках

string

O

Ответ в формате JSON:

Название

Описание

Формат

Mandatory

signature

подпись поля data

string

M

data

Image

строка в base64

string

M

Url

ссылка QR кода

string

M

2.3. Статус заказа

После генераций QК кода, для определения статуса заказа(для отображения статуса оплаты в сторонней системе), используется запрос чтения статуса заказа.

POST https://senim.kz//api/integration/v2/orders/status

Данные POST запроса:

Название

Описание

Формат

Mandatory

orderId

ID заказа в вашей системе

int

M

Ответ в формате JSON:

Название

Описание

Формат

Mandatory

signature

подпись поля data

string

M

data

id

ID заказа в системе Senim

int

M

orderId

ID заказа в сторонней системе

int

M

orderAmount

Сумма заказа в тенге

string

M

cashbackAmount

Сумма кэшбека в тенге

string

M

statusId

Статус заказа 1 – выставлен 2 – оплачен 3 – отклонен клиентом 4 – отменен продавцом 7 – оплачен, но в блоке

int

M

2.4. Возврат заказа

После успешной оплаты клиентом, продавец может сделать полный или частичный возврат при невозможности предоставлении услуги или товара с указанием идентификатора возврата в сторонней системе.

POST https://senim.kz//api/integration/v2/orders/status

Данные POST запроса:

Название

Описание

Формат

Mandatory

orderId

ID заказа в вашей системе

int

M

amount

Новая сумма заказа

double

M

partial

Тип возврата

true – частичный

false - полный возврат

boolean

M

refundId

Id операции возврата в сторонней системе

string

M

Ответ в формате JSON:

Название

Описание

Формат

Mandatory

signature

подпись поля data

string

M

data

id

ID заказа в системе Senim

int

M

orderId

ID заказа в сторонней системе

int

M

orderAmount

Сумма заказа в тенге

string

M

cashbackAmount

Сумма кэшбека в тенге

string

M

statusId

Статус заказа 1 – выставлен 2 – оплачен 3 – отклонен клиентом 4 – отменен продавцом 7 – оплачен, но в блоке

int

M

2.5. Отправка статуса заказа

Система Senim оповещает интегрированную стороннюю систему после каждой успешной оплаты клиента, методом POST по указанному URL в сгенерированном QR коде либо используется URL по умолчанию, указанный в настройках интеграции партнера. Система через расписание будет стучаться по указанному URL до получения статуса 200 OK (тело ответа неважно).

Запрос оповещения сторонней системы

POST URL + request body в формате json:

Название

Описание

Формат

signature

подпись поля data

string

data

id

ID заказа в системе Senim

int

orderId

ID заказа в сторонней системе

int

orderAmount

Сумма заказа в тенге

string

cashbackAmount

Сумма кэшбека в тенге

string

statusId

Статус заказа

1 – выставлен

2 – оплачен

3 – отклонен клиентом

4 – отменен продавцом

7 – оплачен, но в блоке

int

2.6 Деактивация сгенерированного QR

Если по каким-либо причинам сторонняя система после генерации QR кода не может принять оплату через систему Senim, вызывается функция деактивации сгенерированного QR кода. Тем самым QR код становится недействительным.

POST https://senim.kz//api/integration/v2/qr/urls/deactivate (idempotent)

Данные POST запроса:

Название

Описание

Формат

Mandatory

url

сгенерированная QR ссылка

string

M

Ответ в формате JSON:

Название

Описание

Формат

Mandatory

signature

подпись поля data

string

M

data

url

сгенерированная qr ссылка

string

M

active

Статус QR кода

boolean

M

3. Оплата через эквайринг Senim

Система Senim предоставляет функционал альтернативного варианта безналичного приема оплат неавторизованными пользователями для партнеров, присоединившихся к сервису “Касса”. Покупатели, которые не являются пользователями смарт кошелька Senim, могут оплачивать покупки через переход на страницу оплат поддоменом kassa.senim.kz. Генерация ссылки перехода вшит в специальный динамический QR код. Для того чтобы стать Патрнером и воспользоваться функцией альтернативного безналичного приема оплат, нужно обратиться к менеджеру по сопровождению.

3.1 Настройка интеграций Кассы

Касса – это абстракный интерфейс для отображения сгенерированного динамического кода(терминал оплат, монитор для отображения QR кода). Для того чтобы выставить счет по кассе, нужно привязать кассу к главной организации(в дальнейшем Организатор), курирующей генерацию QR кодов для других организации, выполняющий техническую часть интеграции между системами. Организатор в приеме оплат не участвует, успешные оплаты начисляются на счет организации от имени кого был сгенерирован QR код.

Чтобы организации настроить на прием платежей через Кассу, обязательным условием является наличие организации в системе Senim с достоверными данными счетов для вывода средств и скачивание приложение Senim для дальнейшей работы.

3.2 Привязка организаций к кассе

Организатор привязывает организации к сервису Кассы, через push-уведомление на мобильное устройство. Центр уведомлении находится в вкладке Профиль приложения Senim. Организатор использует следующий запрос для привязки организации к системе.

POST https://senim.kz/api/integration/v2/push-notification/code

Данные POST запроса:

Название

Описание

Формат

Mandatory

bin

БИН организации, которую нужно привязать к кассе для генерации QR кода

string

M

Ответ в формате JSON:

Название

Описание

Формат

Mandatory

signature

подпись поля data

string

M

data

Строка подтверждение: Пуш уведомление отправлено

string

M

После успешной обработки запроса, высылается push-уведомление на мобильное устройство организации с 6-значным кодом для подтверждения привязки организации к кассе.

Следующий запрос для подтверждение привязки:

POST https://senim.kz/api/integration/v2/verify/code

Данные POST запроса:

Название

Описание

Формат

Mandatory

bin

БИН организации, которую нужно привязать к кассе для генерации QR кода

string

M

code

6-значный код из push-уведомления

string

M

Ответ в формате JSON:

Название

Описание

Формат

Mandatory

signature

подпись поля data

string

M

data

organizationId

ID организации в системе Senim, далее будет использован для поиска торговых точек для данной организации

int

M

statusMessage

Строка подтверждение: Успешное подтверждение кода

string

M

3.3 Список торговых точек

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

GET https://senim.kz/api/integration/v2/organizations/{id}/branches

Данные GET запроса:

Название

Описание

Формат

Mandatory

id

ID организации ранее привязанной к кассе

int

M

Ответ в формате JSON:

Название

Описание

Формат

Mandatory

signature

подпись поля data

string

M

data

organizationId

ID организации в системе Senim, далее будет использован для поиска торговых точек для данной организации

int

M

branches

Массив торговых точек

id

ID торговой точки в системе Senim

int

M

name

Название торговой точки

string

M

address

Адрес торговой точки

string

M

active

Статус торговой точки, оплаты проходят только по активным торговым точкам:

true – активна

false - неактивирована

boolean

M

Используется пагинация, для след страницы, отправить page = 2... в параметрах запроса.

3.4. Получение ссылки на фискальный чек

Партнерам, имеющие кассовые аппараты с фискализацией чеков, после успешной оплаты клиента в системе Senim, нужно выслать нам ссылку на чек для отображения этого чека в мобильном устройстве Senim.

POST https://senim.kz/api/integration/v2/kassa/check-link

Данные POST запроса:

Название

Описание

Формат

Mandatory

invoiceId

ID заказа в системе Senim

int

M

link

Ссылка на фискальный чек, валидный URL

string

M

orderId

ID заказа в сторонней системе

int

M

Ответ в формате JSON:

Название

Описание

Формат

Mandatory

signature

подпись поля data

string

M

data

orderId

ID заказа в сторонней системе

int

M

statusMessage

Строка подтверждение: Успешно отправлено

string

M

Last updated