# Руководство разработчика

# Начало работы

#### Формат запросов

Все запросы осуществляются только методом **POST**, посредством протокола **https**. Тело POST-запроса должно быть в формате JSON. Ответ так же возвращается в виде JSON. Все текстовые параметры, посланные и принятые, предполагают использование кодировки UTF-8.

<p class="callout info">**Endpoint** - [https://api.novaconnect.kz/api](https://api.novaconnect.kz/api)</p>

В теле запроса также необходимо передавать следующие заголовки:

- **Content-Type**:application/json
- **Authorization**: Bearer &lt;token&gt;

Код языка передается в GET-параметре запроса, параметр **lang.** Доступно два языка - **ru** и **en**. Например, чтобы получить результат на русском языке:

> POST [https://api.novaconnect.kz/api/sim/list?lang=ru](https://api.novaconnect.kz/api/sim/list?lang=ru)
> 
> {.....}

#### Получение токена

Для получения токена авторизуйтесь под учетной записью администратора, перейдите в "Мой профиль".

[![изображение.png](https://kb.novaconnect.kz/uploads/images/gallery/2024-07/scaled-1680-/izobrazenie.png)](https://kb.novaconnect.kz/uploads/images/gallery/2024-07/izobrazenie.png)

На вкладке "***Токены доступа***" создайте новый токен.

[![изображение.png](https://kb.novaconnect.kz/uploads/images/gallery/2024-07/scaled-1680-/lkeizobrazenie.png)](https://kb.novaconnect.kz/uploads/images/gallery/2024-07/lkeizobrazenie.png)

Название токена будет фигурировать в истории операций над сущностями - сим-картами, компанией и т.п.

Чтобы показать содержимое созданного токена, используйте кнопку "***Показать***". Содержимое токена будет отображено в окне.

<p class="callout warning">Токен имеет срок действия **100 лет**.</p>

# Типы данных

# Сим-карта

```javascript
{
    "id": <int>,
    "iccid": <string>,
    "number": <string>,
    "external_number": <string>,
    "name": <string | null>,
    "balance": <float>,
    "currency": <string>,
    "msu_value": <int | null>,
    "profile": <string>,
    "block": <string>,
    "comment": <string | null>,
    "groups": [
        ... массив объектов типа Группа
    ],
    "limit": {
        "type": <string>,
        "value": <int | null>,
        "used": <int | null>,
        "updated": <int | null>,
        "created": <int | null>
    },
    "tariff": {
        "id": <int>,
        "name": <string>,
        "change_lock": <int | null>,
        "package_auto": <bool>
  },
  "queue_status": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Примечание |
|-------|----------|---------|---------|
| **id**     | int     | ID сим-карты    |
| **iccid**     | string     | ICCID сим-карты    |
| **number**     | string     | Основной номер сим-карты    |
| **external_number**     | string     | Дополнительный номер сим-карты    |
| **name**     | string, null     | Название сим-карты    |
| **balance**     | float     | Баланс сим-карты    | Для сим профиля TD всегда нулевой
| **currency**     | string     | Валюта сим-карты    |
| **msu_value**     | int, null     | Количество MSU    | Только для профиля TC
| **profile**     | string     | Профиль    |
| **block**     | string     | Тип блокировки    | значения см. ниже
| **comment**     | string, null     | Комментарий системы    |
| **groups**     | array     | Массив групп сим-карты    | см. [Группа](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/gruppa). Отсутствует в [вэбхук-уведомлениях](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/uvedomleniia)
| **limit**     | object     | Лимит    |
| **limit.type**     | string     | Тип лимита    | значения см. ниже
| **limit.value**     | int     | Установленное значение лимита    |
| **limit.used**     | float     | Использованный лимит    |
| **limit.updated**     | int (UnixTime)     | Дата обновления поля used    |
| **limit.created**     | int (UnixTime)     | Дата установки лимита    |
| **tariff**     | object     | Инфо о тарифе    |
| **tariff.id**     | int     | ID тарифного плана    |
| **tariff.name**     | string     | Название тарифного плана    |
| **tariff.change_lock**     | bool     | Дата снятия блокировки на смену ТП    |
| **tariff.package_auto**     | bool     | Флаг автоматического подключения пакета при истечении    |
| **queue_status**     | string     | Статус обработки    | Возвращается только в вэб-хуках обработки очереди

##### Значения параметра block
| Значение | Описание |
|-------|----------|
| **n**     | Блокировки нет     |
| **u**     | Добровольная (пользовательская)     |
| **m**     | Блокировка по MSU (только для сим профиля TC)     |
| **p**     | Блокировка по истечения пакета     |
| **f**     | Финансовая блокировка     |
| **g**     | Блокировка оператора/NovaConnect     |

##### Значения параметра limit.type
| Значение | Описание |
|-------|----------|
| **off**     | Лимита нет     |
| **month1**     | Календарный месяц (только для сим профиля TC)    |
| **p_lim**     | Пакет, без автопродления (только для сим профиля TD)     |
| **p_unlim**     | Пакет, с автопродлением (только для сим профиля TD)     |

##### Дополнительная информация
- Параметр **"balance"** используется только в сим-картах профиля TC;
- Параметр **"comment"** содержит в себе комментарий от NovaConnect касательно сим-карты (как правило, там рекомендации по работе сим);
- Параметр **"msu_value"** содержит количество MSU, переданных оператором (только для профиля TC);
- Информация о лимитах передается в мегабайтах;
- Все даты - в формате UnixTime;
- Блокировка типа **"m"** невозвратная - значит, что оператор заблокировал сим-карту за превышение лимита MSU.

# Счёт

```javascript
{
    "period": <string>,
    "added": <int>,
    "id": <int>,
    "paided": <int>,
    "cost": <float>,
    "valute_course": <float>,
    "country": <string>,
    "valute_cost": <float>,
    "bid": <string>,
    "currency": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Примечание |
|-------|----------|---------|---------|
| **period**     | string     | Период, за который выставлен счет    |
| **added**     | int (UnixTimeStamp)     | Дата добавления    |
| **id**     | int     | ID счета    |
| **paided**     | int (UnixTimeStamp)    | Дата зачисления оплаты    |
| **cost**     | float     | Сумма счета в EUR    |
| **valute_course**     | float     | Курс валюты на момент выставления счета    |
| **country**     | string     | Код страны для счета    |
| **valute_cost**     | float     | Сумма счета в валюте государства регистрации клиента    |
| **bid**     | string     | Номер счета    |
| **currency**     | string     | Код валюты, в которой выставлен счет   |

##### Дополнительная информация

- Счета выставляются в евро, если государство регистрации компании не Россия или Казахстан. Для российских компаний счета выставляются в рублях, для казахстанских - в тенге.
- Значение **valute_course** отображает курс валюты на день выставления счета. Курс получается из систем Центральных Банков России и Казахстана (для рубля и тенге)

# Компания

```javascript
{
  "id": <int>,
  "name": <string>,
  "unique_id": <string>,
  "contract": <string>,
  "country": <string>,
  "billing_type": <int>,
  "assigned": <int>,
  "balance": <string>,
  "prelimitary_balance": <string>
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **id**     | int     | ID компании    |
| **name**     | string     | Навзание   |
| **unique_id**     | string     | Уникальный ID (как правило - налоговый номер компании)     |
| **contract**     | string     | Номер договора    |
| **country**     | string     | Код государства регистрации компании     |
| **billing_type**     | int     | Тип биллинга: 0 - постоплата, 1 - предоплата     |
| **assigned**     | int     | Не используется    |
| **overdraft**     | string     | Установленный овердрафт    |
| **balance**     | string     | Текущий баланс (с символом валюты)    |
| **prelimitary_balance**     | string     | Предварительный баланс (с символом валюты), для постоплаты    |

# Пользователь

```javascript
{
    "id": <int>,
    "first_name": <string>,
    "last_name": <string>,
    "phone": <string>,
    "email": <string>,
    "active": <bool>,
    "role": <string>
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **id**    | int      | ID пользователя
| **first_name**    | string      | Имя
| **last_name**    | string      | Фамилия
| **phone**    | string      | Номер телефона
| **email**    | string      | Email-адрес
| **active**    | bool      | Активность
| **role**    | string      | Код роли

# Группа

```javascript
{
    "id": <int>,
    "name": <string>,
    "added": <int>
}
```
##### Параметры
| Параметр | Тип | Описание | Примечание |
|-------|----------|---------|---------|
| **id**     | int     | ID группы    |
| **name**     | string     | Название группы    |
| **added**     | int (UnixTimeStamp)     | Дата создания группы    | В объекте [Сим-карта](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/sim-karta) не передается

# Вэб-хуки

# Операции с сим-картами

Если в методах блокировки, разблокировки, перезагрузки, баланса, пинга, изменения групп указан параметр **callbackUrl**, то на этот адрес выполняется **POST**-запрос с информацией о выполнении заданий.

```javascript
POST callbackUrl
Content-type: application/json

{
  "qid": <string>,
  "added": <>,
  "queue": <string>,
  "handler": <string>,
  "items": [
    //массив элементов типа "сим-карта"
  ],
  "user": {
    "id": <int>,
    "first_name": <string>,
    "last_name": <string>,
    "company_id": <int>
  },
  "status": {
    "count": <int>,
    "process": <int>,
    "percentage": <int>
  }
}
```

##### Параметры
| Параметр | Тип | Описание |
|-------|----------|---------|
| **qid**     | string     | ID задания в очереди    |
| **added**     | int(UnixTimeStamp)     | Дата добавления задания в очередь    |
| **queue**     | string     | Код очереди    |
| **handler**     | string     | URL вэб-хука    |
| **items**     | array     | Массив объектов типа [Сим-карта](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/sim-karta)    |
| **user**     | object     | Объект с информацией о пользователе     |
| **user.id**     | int     | ID пользователя   |
| **user.first_name**     | string     | Имя     |
| **user.last_name**     | string     | Фамилия     |
| **user.company_id**     | int     | ID компании пользователя     |
| **status**     | object     | Объект с информацией о статусе выполнения задания     |
| **status.count**     | object     | Общее количество элементов в очереди     |
| **status.process**     | object     | Количество обработанных элементов     |
| **status.percentage**     | object     | Процент обработанных элементов     |

# Уведомления

Если в личном кабинете настроены уведомления типа **Вэбхук**, то на указанный URL приходят POST-запросы вида:
```javascript
POST clientURL

Content-Type: application/json

{
  "type": <string>,
  "files": <array>,
  "items": <array>
}
```
#### Параметры
| Параметр | Тип | Описание | Примечание |
|-------|----------|---------|---------|
| **type**     | string     | Тип уведомления    |
| **files**     | array     | Файлы    |Наличие зависит от типа
| **items**     | array     | Элементы     | Содержание зависит от типа

##### Тип уведомления (параметр type)
| Значение | Описание |
|-------|----------|
| **msu_lock**     | Блокировка сим по MSU     | 
| **package_empty**     | Закончился пакет трафика     | 
| **generate_bill**     | Добавлен новый счет на оплату     | 
| **unpaid_bill_3**     | Отправляется на 3й рабочий день после выставления счета, в случае неоплаты     | 
| **unpaid_bill_5**     | Отправляется на 5й рабочий день после выставления счета, в случае неоплаты     | 
| **unpaid_bill_6**     | Отправляется на 6й рабочий день после выставления счета, в случае неоплаты. Блокировка всех сим-карт и ограничение функциональности ЛК и API     |

##### Параметр files
Параметр **files** заполняется только в случае отправки уведомления по финансовым обязательствам, когда **type** = generate_bill, unpaid_bill_3, unpaid_bill_5, unpaid_bill_6.
Элемент массива представлен следующим объектом:
```javascript

  {
    "type": "base64",
    "format": <string>,
    "name": <string>,
    "body": <string>
  }
```
| Параметр | Тип | Описание | Примечание |
|-------|----------|---------|---------|
| **type**     | string     | Тип содержимого - всегда base64    |
| **format**     | string     | MIME-type файла    |
| **name**     | string     | Имя файла    |
| **body**     | string     | Содержимое файла, закодированное в base64    |

##### Параметр items
Параметр items содержит массив элементов, тип которых зависит от значения параметра **type**:
- Объект типа [Сим-карта](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/sim-karta), для **type** = msu_lock, package_empty
- Объект типа [Счёт](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/scet), для  **type** = generate_bill, unpaid_bill_3, unpaid_bill_5, unpaid_bill_6

# Сим-карты

# Список сим-карт

Для получения списка сим-карт используется метод **sim/list**:

```javascript
POST https://api.novaconnect.kz/api/sim/list

{
  "page": <int>,
  "size": <int>,
  "filter": {
    "profile": <string>,
    "msu_block": <bool>,
    "blocked": <bool>,
    "query": <string>
  },
  "sort": <object>
}
```
#### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **page**     | int     | Страница (нумерация с 0)    |Нет
| **size**     | int     | Размер страницы     |Нет
| **filter**     | object     | Объект фильтра    |Нет
| **sort**     | object    | Объект сортировки    |Нет

##### Фильтр
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **profile**     | string     | Код профиля сим-карты    |Нет
| **msu_block**     | bool     | Блокировка по MSU     |Нет
| **blocked**     | bool     | Блокировка    |Нет
| **query**     | string     | Поисковый запрос    |Нет

- Фильтр **query** принимает на вход поисковый запрос, подробнее см. [Фильтрация информации -> Универсальное поле поиска](https://kb.novaconnect.kz/books/rukovodstvo-polzovatelia/page/filtraciia-informacii#bkmrk-%D0%9F%D0%BE%D0%BB%D1%8F-%D0%B2%D0%B2%D0%BE%D0%B4%D0%B0-iccid-%D0%B8-%D0%BD);
- Фильтр **profile** принимает на вход код профиля: **TD** для сим профиля TD, **TC** для сим профиля TC;
- Фильтр **blocked** работает по следующей логике:
  - при передаче значения **false** будут получены все записи, у которых значение **block = n**, то есть разблокированные;
  - при передаче значения **true** будут получены все записи, у которых значение **block = u, p, m, g, f**, то есть заблокированные по любой причине;

##### Сортировка
В объект сортировки передается код поля, по которому нужно провести сортировку, в качестве ключа. В качестве значение - направление (ASC - по возрастанию, DESC - по убыванию).
```
{
    "id": "DESC" //Сортировка по убыванию идентификаторов сим
}
```


#### Ограничения и доступы
Метод доступен пользователю с любой ролью

#### Успешный ответ
```javascript
{
  "code": 200,
  "message": <string>,
  "count": <int>,
  "all_count": <int>,
  "items": [
        //Объекты типа Сим-карта
  ]
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **count**    | int      | Количество элементов в массиве items
| **all_count**    | int      | Количество элементов в БД
| **items**    | array      | Массив элементов типа [Сим-карта](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/sim-karta)

# Блокировка

Для блокировки сим-карт используется метод **sim/block**:

```javascript
POST https://api.novaconnect.kz/api/sim/block

{
  "items": <array>
  "callbackUrl": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **items**     | array     | Массив идентификаторов сим-карт    |Да
| **callbackUrl**     | int     | Размер страницы     |Нет

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**.

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "queue_id"
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.queue_id**    | string      | Идентификатор задания

После выполнения задания на URL, указанный в параметре **callbackUrl** выполняется POST-запрос с объектом сим-карты. Подробнее - [Операции с сим-картами](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/operacii-s-sim-kartami)

# Разлокировка

Для разблокировки сим-карт используется метод **sim/unblock**:

```javascript
POST https://api.novaconnect.kz/api/sim/unblock

{
  "items": <array>
  "callbackUrl": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **items**     | array     | Массив идентификаторов сим-карт    |Да
| **callbackUrl**     | int     | Размер страницы     |Нет

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**.

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "queue_id"
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.queue_id**    | string      | Идентификатор задания

После выполнения задания на URL, указанный в параметре **callbackUrl** выполняется POST-запрос с объектом сим-карты. Подробнее - [Операции с сим-картами](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/operacii-s-sim-kartami)

# Перезагрузка

> **Внимание!** Метод перенаправляется на [sim/disconnect](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/otkliucenie)

Для "мягкой перезагрузки" (отправка Package of Disconnect для разрыва активной сессии передачи данных) сим-карт используется метод **sim/reconnect**:

```javascript
POST https://api.novaconnect.kz/api/sim/reconnect

{
  "items": <array>
  "callbackUrl": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **items**     | array     | Массив идентификаторов сим-карт    |Да
| **callbackUrl**     | int     | Размер страницы     |Нет

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**.

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "queue_id"
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.queue_id**    | string      | Идентификатор задания

После выполнения задания на URL, указанный в параметре **callbackUrl** выполняется POST-запрос с объектом сим-карты. Подробнее - [Операции с сим-картами](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/operacii-s-sim-kartami)

# Отключение

> **Внимание!** На этот метод перенаправляются запросы [sim/reconnect](https://kb.novaconnect.kz/books/rukovodstvo-polzovatelia/page/perezagruzka). Это сделано из-за некорректной работы методов отправки PoD у операторов.
> 
Для отключения сим-карт от сети (Cancel Location: разрыв подключения к сети) используется метод **sim/disconnect**:

```javascript
POST https://api.novaconnect.kz/api/sim/disconnect

{
  "items": <array>
  "callbackUrl": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **items**     | array     | Массив идентификаторов сим-карт    |Да
| **callbackUrl**     | int     | Размер страницы     |Нет

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**.

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "queue_id"
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.queue_id**    | string      | Идентификатор задания

После выполнения задания на URL, указанный в параметре **callbackUrl** выполняется POST-запрос с объектом сим-карты. Подробнее - Операции с сим-картами

# Пинг

> **Внимание!** Этот метод корректно работает только для сим-карт профиля **TD**

Для пинга сим-карты (отправка СМС с текстом PING на сим-карту) используется метод **sim/ping**:

```javascript
POST https://api.novaconnect.kz/api/sim/ping

{
  "items": <array>
  "callbackUrl": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **items**     | array     | Массив идентификаторов сим-карт    |Да
| **callbackUrl**     | int     | Размер страницы     |Нет

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**.

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "queue_id"
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.queue_id**    | string      | Идентификатор задания

После выполнения задания на URL, указанный в параметре **callbackUrl** выполняется POST-запрос с объектом сим-карты. Подробнее - Операции с сим-картами

# СМС

> **Внимание!** Этот метод работает только для сим-карт профиля **TD**

Для отправки СМС на сим-карты используется метод **sim/sms**:

```javascript
POST https://api.novaconnect.kz/api/sim/sms

{
  "items": <array>
  "callbackUrl": <string>,
  "params": {
    "text": <string>
  }
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **items**     | array     | Массив идентификаторов сим-карт    |Да
| **callbackUrl**     | int     | Размер страницы     |Нет
| **params.text**     | string (70)     | Текст СМС (не больше 70 символов)     |Да

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**.

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "queue_id"
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.queue_id**    | string      | Идентификатор задания

После выполнения задания на URL, указанный в параметре **callbackUrl** выполняется POST-запрос с объектом сим-карты. Подробнее - Операции с сим-картами

# Установка лимита

> **Внимание!** Этот метод работает только для сим-карт профиля **TС**

Для установки лимита на сим-карты используется метод **sim/limit**:

```javascript
POST https://api.novaconnect.kz/api/sim/limit

{
  "items": <array>
  "callbackUrl": <string>,
  "params": {
    "value": <int>,
    "type": <string>
  }
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **items**     | array     | Массив идентификаторов сим-карт    |Да
| **callbackUrl**     | int     | Размер страницы     |Нет
| **params.value**     | int     | Размер лимита в мегабайтах     |Да
| **params.type**     | string     | Тип лимита (off - без лимита, month1 - календарный месяц)     |Да

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**.

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "queue_id"
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.queue_id**    | string      | Идентификатор задания

После выполнения задания на URL, указанный в параметре **callbackUrl** выполняется POST-запрос с объектом сим-карты. Подробнее - Операции с сим-картами

# Изменение тарификации

> **Внимание!** Этот метод работает только для сим-карт профиля **TD**

Для изменения настроек тарифного плана сим-карт используется метод **sim/tariff**:

```javascript
POST https://api.novaconnect.kz/api/sim/tariff

{
  "items": <array>
  "callbackUrl": <string>,
  "params": {
    "value": <int>,
    "auto_package": <bool>,
    "all_world": <bool>
  }
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **items**     | array     | Массив идентификаторов сим-карт    |Да
| **callbackUrl**     | int     | Размер страницы     |Нет
| **params.value**     | int     | Размер пакета в **килобайтах**     |Да
| **params.auto_package**     | bool     | Флаг автоматического переподключения пакета по истечении     |Да
| **params.all_world**     | bool     | Флаг подключения роуминга во всем мире (тариф TD_Mega)     |Нет

##### Размеры пакета
Минимальный пакет - 15360 килобайт (15 мб), максимальный - 102400 килобайт (100 мб). Шаг - 5120 килобайт (5 мб)

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**.

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "queue_id"
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.queue_id**    | string      | Идентификатор задания

После выполнения задания на URL, указанный в параметре **callbackUrl** выполняется POST-запрос с объектом сим-карты. Подробнее - Операции с сим-картами

# Переподключение пакета

> **Внимание!** Этот метод доступен только для сим-карт профиля **TD**

Для переподключения пакета трафика используется метод **sim/repackage**:

```javascript
POST https://api.novaconnect.kz/api/sim/repackage

{
  "items": <array>
  "callbackUrl": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **items**     | array     | Массив идентификаторов сим-карт    |Да
| **callbackUrl**     | int     | Размер страницы     |Нет

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**.

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "queue_id"
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.queue_id**    | string      | Идентификатор задания

После выполнения задания на URL, указанный в параметре **callbackUrl** выполняется POST-запрос с объектом сим-карты. Подробнее - Операции с сим-картами

# Переименование

Для переименования сим-карты используется метод **sim/edit**:

```javascript
POST https://api.novaconnect.kz/api/sim/edit

{
  "id": <int>
  "name": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **id**     | int     | Идентификатор сим-карты    |Да
| **name**     | string     | Название сим-карты     |Да

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**.

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "id": <int>,
        "name": <string>
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.id**    | int      | ID сим-карты
| **result.item.name**    | string      | Имя сим-карты

# Группы

Для изменения групп используется запрос **sim/group**:

```javascript
POST https://api.novaconnect.kz/api/sim/group

{
  "items": <array of int>
  "callbackUrl": <string>,
  "group: <array>,
  "new_group": <array>

}
```

##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **items**     | array     | Массив идентификаторов сим-карт    |Да
| **callbackUrl**     | int     | Размер страницы     |Нет
| **group**     | array     | Массив идентификаторов Групп     |Нет
| **new_group**     | array     | Массив названий Групп     |Нет



#### Дополнительная информация

В параметр **group** передаются идентификаторы групп, которые уже имеются в базе данных. Параметр **new_group** позволяет создать новые группы "на лету" и привязать туда сим-карты из параметра **items**. Если в **new_group** будет передано названия уже существующих групп, то привязка будет осуществлена, в том числе, в них.

#### Ограничения и доступы

Метод доступен пользователю с ролью **Администратор**

#### Успешный ответ
В результате возвращается информация о постановке в очередь.

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        "queue_id"
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.queue_id**    | string      | Идентификатор задания

После выполнения задания на URL, указанный в параметре **callbackUrl** выполняется POST-запрос с объектом сим-карты. Подробнее - [Операции с сим-картами](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/operacii-s-sim-kartami)

# Счета

# Список

Для получения списка счетов используется запрос **bill/list**:

```javascript
POST https://api.novaconnect.kz/api/bill/list

{
  "page": <int>,
  "size": <int>,
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **page**     | int     | Номер страницы, нумерация с 0     |Нет
| **size**    | int      | Размер страницы      |Нет

#### Успешный ответ
```javascript
{
  "code": 200,
  "count": <int>,
  "all_count": <int>,
  "items": [
    {
      ... объект типа счет
    }
  ],
  "message": <string>,
  "allow_operations": <object>
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **count**    | int      | Количество данных в ответе
| **all_count**    | int      | Количество данных в БД
|  **items**    | array      | Массив элементов ["Счет"](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/scet)
| **allow_operations**    | object      | Не используется

# Файлы счёта и расшифровки

##### Счёт

Для получения файла счета, необходимо выполнить GET-запрос формата:

`https://api.novaconnect.kz/api/bill/download/<strong>id_счёта</strong>`

Токен можно передать:

- В заголовке **Authorization: Bearer &lt;token&gt;;**
- Либо в GET-параметре **token,** например *https://api.novaconnect.kz/api/bill/download/id\_счёта?**token=&lt;token&gt;***

<p class="callout info">Файл счёта возвращается в формате PDF</p>

##### Расшифровка счёта

Для получения файла расшифровки счета, необходимо выполнить GET-запрос формата:

`https://api.novaconnect.kz/api/bill/download/<strong>id_счёта?mode=transcript</strong>`

Токен передается в запросе аналогично получению счёта.

<p class="callout info">Файл расшифровки возвращается в формате XLSX</p>

# Отчёты

# По сессиям

Для получения выгрузки по сессиям используется метод **report/sessions**:

```javascript
POST https://api.novaconnect.kz/api/report/sessions

{
  "filter": {
    "start": <string>,
    "end": <string>
  },
  "select": <array>,
  "page": <int>,
  "size": <int>
}
```
#### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **select**     | array     | Массив данных, по которым составляется отчет    |Нет
| **filter.start**     | string     | Дата начала (в формате ДД-ММ-ГГГГ)     |Нет
| **filter.end**     | string     | Дата конца (в формате ДД-ММ-ГГГГ)     |Нет
| **page**     | int     | Номер страницы (нумерация с 0)     |Нет
| **size**     | int     | Размер страницы     |Нет

##### Параметр select
В параметр необходимо передавать массив данных в виде:
- **all** - чтобы получить данные по всем доступным сим-картам;
- **s_*id*** - чтобы получить данные по сим-карте с идентификатором *id*
- **g_*id*** - чтобы получить данные по сим-картам, входящим в группу с идентификатором *id*

#### Ограничения и доступы
Метод доступен пользователю с любой ролью

#### Успешный ответ

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "items": [
        {
            "sid": <int>,
            "start": <int>,
            "end": <int>,
            "country_name": <string>,
            "operator_name": <string>,
            "operator_code": <int>,
            "session_cost": <float>,
            "value": <bigint>,
            "id": <int>,
            "original_number": <string>,
            "iccid": <string>,
            "name": <string | null>
      }
    ]
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.sid**    | int      | Идентификатор сессии
| **result.item.start**    | int (UnixTimeStamp)      | Дата и время начала сессии
| **result.item.end**    | int (UnixTimeStamp)      | Дата и время окончания сессии
| **result.item.country_name**    | string      | Сырое название страны (как хранится у верхнеуровнего оператора)
| **result.item.operator_name**    | string      | Сырое название оператора (как хранится у верхнеуровнего оператора)
| **result.item.operator_code**    | int      | Идентификатор оператора (MCC + MNC)
| **result.item.session_cost**    | float      | Стоимость сессии в евро (только для сим профиля TC)
| **result.item.value**    | bigint (string)      | Количество переданного и принятого трафика в сессии
| **result.item.id**    | int      | Идентификатор сим-карты
| **result.item.original_number**    | string      | Номер сим-карты
| **result.item.iccid**    | string      | ICCID сим-карты
| **result.item.name**    | string/null      | Название сим-карты

#### Дополнительная информация
Синхронизация сессий с базами данных операторов происходит раз в сутки. Например, сессия была 25.06.2024, в отчет она попадет только после синхронизации 26.06.2024

# По дням

Для получения выгрузки сессий по дням используется метод **report/day**:

```javascript
POST https://api.novaconnect.kz/api/report/day

{
  "filter": {
    "start": <string>,
    "end": <string>
  },
  "select": <array>,
  "page": <int>,
  "size": <int>
}
```
#### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **select**     | array     | Массив данных, по которым составляется отчет    |Нет
| **filter.start**     | string     | Дата начала (в формате ДД-ММ-ГГГГ)     |Нет
| **filter.end**     | string     | Дата конца (в формате ДД-ММ-ГГГГ)     |Нет
| **page**     | int     | Номер страницы (нумерация с 0)     |Нет
| **size**     | int     | Размер страницы     |Нет

##### Параметр select
В параметр необходимо передавать массив данных в виде:
- **all** - чтобы получить данные по всем доступным сим-картам;
- **s_*id*** - чтобы получить данные по сим-карте с идентификатором *id*
- **g_*id*** - чтобы получить данные по сим-картам, входящим в группу с идентификатором *id*

#### Ограничения и доступы
Метод доступен пользователю с любой ролью

#### Успешный ответ

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "items": [
        {
            "sid": <int>,
            "day": <int>,
            "session_cost": <float>,
            "value": <bigint>,
            "id": <int>,
            "original_number": <string>,
            "iccid": <string>,
            "name": <string | null>
      }
    ]
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.sid**    | int      | Идентификатор сессии
| **result.item.day**    | int (UnixTimeStamp)      | День
| **result.item.session_cost**    | float      | Стоимость в евро (только для сим профиля TC)
| **result.item.value**    | bigint (string)      | Количество переданного и принятого трафика за день
| **result.item.id**    | int      | Идентификатор сим-карты
| **result.item.original_number**    | string      | Номер сим-карты
| **result.item.iccid**    | string      | ICCID сим-карты
| **result.item.name**    | string/null      | Название сим-карты

#### Дополнительная информация
Синхронизация сессий с базами данных операторов происходит раз в сутки. Например, сессия была 25.06.2024, в отчет она попадет только после синхронизации 26.06.2024

# СМС и звонки

Для получения выгрузки по смс используется метод **report/call_sms**:

```javascript
POST https://api.novaconnect.kz/api/report/call_sms

{
  "filter": {
    "start": <string>,
    "end": <string>
  },
  "select": <array>,
  "page": <int>,
  "size": <int>
}
```
#### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **select**     | array     | Массив данных, по которым составляется отчет    |Нет
| **filter.start**     | string     | Дата начала (в формате ДД-ММ-ГГГГ)     |Нет
| **filter.end**     | string     | Дата конца (в формате ДД-ММ-ГГГГ)     |Нет
| **page**     | int     | Номер страницы (нумерация с 0)     |Нет
| **size**     | int     | Размер страницы     |Нет

##### Параметр select
В параметр необходимо передавать массив данных в виде:
- **all** - чтобы получить данные по всем доступным сим-картам;
- **s_*id*** - чтобы получить данные по сим-карте с идентификатором *id*
- **g_*id*** - чтобы получить данные по сим-картам, входящим в группу с идентификатором *id*

#### Ограничения и доступы
Метод доступен пользователю с любой ролью

#### Успешный ответ

```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "items": [
        {
            "sid": <int>,
            "date": <int>,
            "type": <string>,
            "to_number": <string>,
            "session_cost": <float>,
            "id": <int>,
            "original_number": <string>,
            "iccid": <string>,
            "name": <string | null>
      }
    ]
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item.sid**    | int      | Идентификатор действия
| **result.item.date**    | int (UnixTimeStamp)      | Дата отправки (приема)
| **result.item.type**    | string      | Тип действия (см. ниже)
| **result.item.to_number**    | string      | Номер назначения
| **result.item.session_cost**    | float      | Стоимость в евро
| **result.item.id**    | int      | Идентификатор сим-карты
| **result.item.original_number**    | string      | Номер сим-карты
| **result.item.iccid**    | string      | ICCID сим-карты
| **result.item.name**    | string/null      | Название сим-карты

##### Тип действия
Параметр **type** может принимать следующие значения:
| Значение | Описание |
|-------|----------|
| **call**     | Звонок     |
| **in_sms**     | Входящее смс     |
| **out_sms**     | Исходящее смс     |
| **ussd**     | Ussd-запрос     |

#### Дополнительная информация
Синхронизация информации с базами данных операторов происходит раз в сутки. Например, действие было 25.06.2024, в отчет оно попадет только после синхронизации 26.06.2024

# Профиль

# Данные пользователя

Для получения данных текущего пользователя используется запрос **user/get**:

```javascript
POST https://api.novaconnect.kz/api/user/get

{}
```

#### Успешный ответ
```javascript
{
  "code": 200,
  "count": <int>,
  "all_count": <int>,
  "result": {
      "item": <object> 
  },
  "message": <string>
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **item**    | object      | Объект типа [Пользователь](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/polzovatel)

# Изменение данных

Для изменения текущего пользователя используется запрос **user/edit**:

```javascript
POST https://api.novaconnect.kz/api/user/edit

{
  "first_name": <string>,
  "last_name": <string>,
  "email": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **first_name**     | string     | Имя пользователя    |Нет
| **last_name**     | string     | Фамилия     |Нет
| **email**     | string     | Email-адрес     |Нет


#### Дополнительная информация
Это - вариация метода [user/edit](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/izmenenie), но для текущего пользователя.

#### Ограничения и доступы
Метод доступен пользователю с любой ролью. Изменение пароля для текущего пользователя в этом методе недоступно.

#### Успешный ответ
```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
      // Объект типа Пользователь
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item**    | object      | Объект типа [Пользователь](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/polzovatel)

# Изменения пароля

Для изменения пароля текущего пользователя используется запрос **user/password**:

```javascript
POST https://api.novaconnect.kz/api/user/password

{
  "password": <string>,
  "old_password": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **password**     | string     | Новый пароль    |Да
| **old_password**     | string     | Старый пароль     |Да


#### Дополнительная информация
Этот метод позволяет обойти ограничение на изменение пароля методом [user/edit](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/izmenenie-dannyx) для **текущего пользователя**.

#### Ограничения и доступы
Метод доступен пользователю с любой ролью.

#### Успешный ответ
```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
      // Объект типа Пользователь
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item**    | object      | Объект типа [Пользователь](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/polzovatel)

# Компания

# Данные компании

Для получения информации по текущей компании используется запрос **company/get**:

```javascript
POST https://api.novaconnect.kz/api/company/get

{}
```


#### Успешный ответ
```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": <object>
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item**    | object      | Объект типа [Компания](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/kompaniia)

# Журнал событий

# Пользователи компании

# Список

Для получения списка групп используется запрос **user/list**:

```javascript
POST https://api.novaconnect.kz/api/user/list

{
  "page": <int>,
  "size": <int>,
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **page**     | int     | Номер страницы, нумерация с 0     |Да
| **size**    | int      | Размер страницы      |Да

#### Успешный ответ
```javascript
{
  "code": 200,
  "count": <int>,
  "all_count": <int>,
  "items": [
       //Массив объектов типа Пользователь
  ],
  "message": <string>
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **count**    | int      | Количество данных в ответе
| **all_count**    | int      | Количество данных в БД
|  **items**    | array      | Массив элементов типа [Пользователь](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/polzovatel)

# Создание

Для создания пользователя используется запрос **user/create**:

```javascript
POST https://api.novaconnect.kz/api/user/create

{
  "first_name": <string>,
  "last_name": <string>,
  "email": <string>,
  "phone": <string>,
  "password": <string>,
  "role": <string>,
  "send": <bool>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **first_name**     | string     | Имя пользователя    |Да
| **last_name**     | string     | Фамилия     |Да
| **email**     | string     | Email-адрес     |Да
| **phone**     | string     | Номер телефона     |Да
| **password**     | string     | Пароль     |Нет
| **role**     | string     | Роль (список см. ниже)     |Нет
| **send**     | bool     | Отправить рег. данные     |Нет

#### Дополнительная информация
- Поле пароль **password** не является обязательным. Если его не указывать, то система автоматически сгенерирует пароль.
- Флаг **send** отвечает за отправку регистрационных данных на указанный в **email** адрес.
- Поле **role** также не является обязательным. Если его не передать, то будет создан пользователь с ролью **Пользователь**

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**

#### Успешный ответ
```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        //объект типа Пользователь
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item**    | object      | Объект типа [Пользователь](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/polzovatel)

# Изменение

Для изменения пользователя используется запрос **user/edit**:

```javascript
POST https://api.novaconnect.kz/api/user/edit

{
  "id": <int>
  "first_name": <string>,
  "last_name": <string>,
  "email": <string>,
  "phone": <string>,
  "password": <string>,
  "role": <string>,
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **id**     | int     | ID пользователя    |Да
| **first_name**     | string     | Имя пользователя    |Нет
| **last_name**     | string     | Фамилия     |Нет
| **email**     | string     | Email-адрес     |Нет
| **phone**     | string     | Номер телефона     |Нет
| **password**     | string     | Пароль     |Нет
| **active**     | bool     | Активность     |Нет
| **role**     | string     | Роль (список см. ниже)     |Нет

#### Дополнительная информация
- Значения полей **password**, **active**, **role** возможно поменять только другим пользователям.

#### Ограничения и доступы
Метод доступен пользователю с любой ролью, однако только пользователь с ролью **Администратор** может изменять данные о других пользователях компании

#### Успешный ответ
```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
      // Объект типа Пользователь
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item**    | object      | Объект типа [Пользователь](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/polzovatel)

# Удаление

Для удаления пользователя используется запрос **user/remove**:

```javascript
POST https://api.novaconnect.kz/api/user/remove

{
  "id": <int>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **id**     | int     | ID пользователя    |Да

#### Ограничения и доступы
Метод доступен только пользователю с ролью **Администратор**. С помощью этого метода невозможно удалить самого себя.

#### Успешный ответ
```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
       //Объект типа Пользователь
    }
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item**    | object      | Объект типа [Пользователь](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/polzovatel)

# Группы

# Список

Для получения списка групп используется запрос **group/list**:

```javascript
POST https://api.novaconnect.kz/api/group/list

{
  "page": <int>,
  "size": <int>,
  "filter": {
    "name": <string>
  }
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **page**     | int     | Номер страницы, нумерация с 0     |Да
| **size**    | int      | Размер страницы      |Да
| **filter.name**     | string   | Название группы (часть названия)      |Нет

#### Успешный ответ
```javascript
{
  "code": 200,
  "count": <int>,
  "all_count": <int>,
  "items": [
    {
      //Массив объектов типа Группа
    }
  ],
  "message": <string>
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **count**    | int      | Количество данных в ответе
| **all_count**    | int      | Количество данных в БД
|  **items**    | array      | Массив элементов типа [Группа](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/gruppa)

# Создание

Для создания группы используется запрос **group/create**:

```javascript
POST https://api.novaconnect.kz/api/group/create

{
  "name": <string>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **name**     | string     | Название группы     |Да

#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**

#### Успешный ответ
```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": <object>
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item**    | object      | Объект типа [Группа](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/gruppa)

# Изменение

Для изменения группы используется запрос **group/edit**:

```javascript
POST https://api.novaconnect.kz/api/group/edit

{
  "name": <string>,
  "id": <int>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **name**     | string     | Название группы     |Да
| **id**     | int     | ID группы     |Да


#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**

#### Успешный ответ
```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": <object>
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item**    | object      | Объект типа [Группа](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/gruppa)

# Удаление

Для удаления группы используется запрос **group/remove**:

```javascript
POST https://api.novaconnect.kz/api/group/remove

{
  "id": <int>
}
```
##### Параметры
| Параметр | Тип | Описание | Обязательность |
|-------|----------|---------|---------|
| **id**     | int     | ID группы     |Да


#### Ограничения и доступы
Метод доступен пользователю с ролью **Администратор**

#### Успешный ответ
```javascript
{
  "code": 200,
  "message": <string>,
  "result": {
    "item": <object>
  }
}
```

| Параметр | Тип | Описание |
|-------|----------|---------|
| **code**     | int     | Код ответа, для успеха - 200
| **message**    | string      | Сообщение ответа
| **result.item**    | object      | Объект типа [Группа](https://kb.novaconnect.kz/books/rukovodstvo-razrabotcika/page/gruppa)