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
Для печати
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
Was this helpful?