# Open API ## 1. Общие сведения Данный документ адресован разработчикам для ознакомления со структурой и принципами работы интеграционного модуля системы Senim и организации взаимодействия между сторонними информационными системами на основе открытой технической спецификации программных интерфейсов. Доступ к документации предоставляется заинтересованным Партнерам. ### 1.1. О системе Senim Senim – это смарт кошелек all in one, с помощью которого можно оплачивать товары и услуги, парковку, проезд на общественном транспорте, покупать билеты в кино и заправлять топливо, не выходя из машины. В данном документе рассматривается оплата через QR код, который генерируется в нашей системе и отображается у нашего Партнера. ### 1.2. Доступ к системе Для оптимизаций работы Партнеру предоставляется тестовая площадка, к которой можно подключится через VPN. Для скачивания кроссплатформенного клиента OpenVPN с открытым исходным кодом перейдите по ссылке и выберите клиента в соответствии с ОС, для мобильного приложения скачайте в Google Play приложение Openvpn. Профиль для подключения виртуальной частной сети будет предоставлена менеджером по сопровождению после настройки тестовой площадки для Партнера. Инструменты тестовой площадки для интеграции: * **Тестовая организация с кошельком** - для приема оплат, предоставляется менеджером по сопровождению, на основе БИН организации и пароля для входа в личный кабинет. * **Тестовый пользователь** *–* для тестирования оплат через приложение Senim. * **Тестовой личный кабинет** - содержит информацию об организаций, балансу, торговым точкам, операциям и настройки для интеграций. * **Тестовое мобильное приложение -** на платформе android в формате Android Package(APK). [Тестовая среда](https://test.senim.kz)\ [Боевая среда](https://senim.kz/) ## 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`](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`](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`](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`](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 |