# Open API

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

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

### 1.1. О системе Senim

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

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

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

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

* **Тестовая организация с кошельком** - для приема оплат, предоставляется менеджером по сопровождению, на основе БИН организации и пароля для входа в личный кабинет. &#x20;
* **Тестовый пользователь** *–* для тестирования оплат через приложение Senim.
* **Тестовой личный кабинет** - <https://testcabinet.senim.kz–> содержит информацию об организаций, балансу, торговым точкам, операциям и настройки для интеграций.&#x20;
* **Тестовое мобильное приложение -** на платформе android в формате Android Package(APK).&#x20;

[Тестовая среда](<https://test.senim.kz >)\
[Боевая среда](https://senim.kz/)

## 2. External API Integration

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

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

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

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

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

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

### 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         |
| <p><br>format</p> | 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К кода, для определения статуса заказа(для отображения статуса оплаты в сторонней системе), используется запрос чтения статуса заказа.&#x20;

`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  | <p>Тип возврата</p><p>true – частичный </p><p>false - полный возврат</p> | 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       | <p>Статус заказа </p><p>1 – выставлен </p><p>2 – оплачен </p><p>3 – отклонен клиентом </p><p>4 – отменен продавцом </p><p>7 – оплачен, но в блоке</p> | 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 код. Для того чтобы стать Патрнером и воспользоваться функцией альтернативного безналичного приема оплат, нужно обратиться к менеджеру по сопровождению.&#x20;

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

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

&#x9;Чтобы организации настроить на прием платежей через Кассу, обязательным условием является наличие организации в системе 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-значным кодом для подтверждения привязки организации к кассе.&#x20;

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

`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 запроса:&#x20;

| Название | Описание                                 | Формат | 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         | <p>Статус торговой точки,  оплаты проходят только по активным торговым точкам:</p><p>true – активна</p><p>false - неактивирована</p> | 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         |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://open.senim.kz/master.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.