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

• Начало работы
• Типы данных
• Сим-карта
• Счёт
• Компания
• Пользователь
• Группа
• Вэб-хуки
• Операции с сим-картами
• Уведомления
• Сим-карты
• Список сим-карт
• Блокировка
• Разлокировка
• Перезагрузка
• Отключение
• Пинг
• СМС
• Установка лимита
• Изменение тарификации
• Переподключение пакета
• Переименование
• Группы
• Счета
• Список
• Файлы счёта и расшифровки
• Отчёты
• По сессиям
• По дням
• СМС и звонки
• Профиль
• Данные пользователя
• Изменение данных
• Изменения пароля
• Компания
• Данные компании
• Пользователи компании
• Список
• Создание
• Изменение
• Удаление
• Группы
• Список
• Создание
• Изменение
• Удаление

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

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

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

Endpoint - https://api.novaconnect.kz/api

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

• Content-Type:application/json
• Authorization: Bearer <token>

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

POST https://api.novaconnect.kz/api/sim/list?lang=ru

{.....}

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

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

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

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

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

Токен имеет срок действия 100 лет.

Типы данных

Сим-карта

{
    "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	Массив групп сим-карты	см. Группа. Отсутствует в вэбхук-уведомлениях
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.

Счёт

{
    "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 отображает курс валюты на день выставления счета. Курс получается из систем Центральных Банков России и Казахстана (для рубля и тенге)

Компания

{
  "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	Предварительный баланс (с символом валюты), для постоплаты

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

{
    "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	Код роли

Группа

{
    "id": <int>,
    "name": <string>,
    "added": <int>
}

Параметры

Параметр	Тип	Описание	Примечание
id	int	ID группы
name	string	Название группы
added	int (UnixTimeStamp)	Дата создания группы	В объекте Сим-карта не передается

Вэб-хуки

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

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

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	Массив объектов типа Сим-карта
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-запросы вида:

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. Элемент массива представлен следующим объектом:

  {
    "type": "base64",
    "format": <string>,
    "name": <string>,
    "body": <string>
  }

Параметр	Тип	Описание	Примечание
type	string	Тип содержимого - всегда base64
format	string	MIME-type файла
name	string	Имя файла
body	string	Содержимое файла, закодированное в base64

Параметр items

Параметр items содержит массив элементов, тип которых зависит от значения параметра type:

• Объект типа Сим-карта, для type = msu_lock, package_empty
• Объект типа Счёт, для type = generate_bill, unpaid_bill_3, unpaid_bill_5, unpaid_bill_6

Сим-карты

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

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

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 принимает на вход поисковый запрос, подробнее см. Фильтрация информации -> Универсальное поле поиска;
• Фильтр profile принимает на вход код профиля: TD для сим профиля TD, TC для сим профиля TC;
• Фильтр blocked работает по следующей логике:
  • при передаче значения false будут получены все записи, у которых значение block = n, то есть разблокированные;
  • при передаче значения true будут получены все записи, у которых значение block = u, p, m, g, f, то есть заблокированные по любой причине;

Сортировка

В объект сортировки передается код поля, по которому нужно провести сортировку, в качестве ключа. В качестве значение - направление (ASC - по возрастанию, DESC - по убыванию).

{
    "id": "DESC" //Сортировка по убыванию идентификаторов сим
}

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

Метод доступен пользователю с любой ролью

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

{
  "code": 200,
  "message": <string>,
  "count": <int>,
  "all_count": <int>,
  "items": [
        //Объекты типа Сим-карта
  ]
}

Параметр	Тип	Описание
code	int	Код ответа, для успеха - 200
message	string	Сообщение ответа
count	int	Количество элементов в массиве items
all_count	int	Количество элементов в БД
items	array	Массив элементов типа Сим-карта

Блокировка

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

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

{
  "items": <array>
  "callbackUrl": <string>
}

Параметры

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

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

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

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

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

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

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

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

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

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

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

{
  "items": <array>
  "callbackUrl": <string>
}

Параметры

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

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

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

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

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

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

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

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

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

Внимание! Метод перенаправляется на sim/disconnect

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

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

{
  "items": <array>
  "callbackUrl": <string>
}

Параметры

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

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

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

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

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

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

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

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

Отключение

Внимание! На этот метод перенаправляются запросы sim/reconnect. Это сделано из-за некорректной работы методов отправки PoD у операторов.

Для отключения сим-карт от сети (Cancel Location: разрыв подключения к сети) используется метод sim/disconnect:

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

{
  "items": <array>
  "callbackUrl": <string>
}

Параметры

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

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

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

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

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

{
  "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:

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

{
  "items": <array>
  "callbackUrl": <string>
}

Параметры

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

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

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

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

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

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

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

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

СМС

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

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

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

{
  "items": <array>
  "callbackUrl": <string>,
  "params": {
    "text": <string>
  }
}

Параметры

Параметр	Тип	Описание	Обязательность
items	array	Массив идентификаторов сим-карт	Да
callbackUrl	int	Размер страницы	Нет
params.text	string (70)	Текст СМС (не больше 70 символов)	Да

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

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

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

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

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

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

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

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

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

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

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 - календарный месяц)	Да

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

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

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

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

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

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

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

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

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

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

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 мб)

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

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

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

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

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

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

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

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

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

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

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

{
  "items": <array>
  "callbackUrl": <string>
}

Параметры

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

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

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

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

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

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

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

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

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

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

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

{
  "id": <int>
  "name": <string>
}

Параметры

Параметр	Тип	Описание	Обязательность
id	int	Идентификатор сим-карты	Да
name	string	Название сим-карты	Да

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

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

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

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

{
  "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:

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 будет передано названия уже существующих групп, то привязка будет осуществлена, в том числе, в них.

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

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

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

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

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

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

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

Счета

Список

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

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

{
  "page": <int>,
  "size": <int>,
}

Параметры

Параметр	Тип	Описание	Обязательность
page	int	Номер страницы, нумерация с 0	Нет
size	int	Размер страницы	Нет

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

{
  "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	Массив элементов "Счет"
allow_operations	object	Не используется

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

Счёт

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

https://api.novaconnect.kz/api/bill/download/id_счёта

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

• В заголовке Authorization: Bearer <token>;
• Либо в GET-параметре token, например https://api.novaconnect.kz/api/bill/download/id_счёта?token=<token>

Файл счёта возвращается в формате PDF

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

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

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

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

Файл расшифровки возвращается в формате XLSX

Отчёты

По сессиям

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

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

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

Метод доступен пользователю с любой ролью

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

{
  "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:

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

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

Метод доступен пользователю с любой ролью

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

{
  "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:

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

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

Метод доступен пользователю с любой ролью

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

{
  "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:

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

{}

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

{
  "code": 200,
  "count": <int>,
  "all_count": <int>,
  "result": {
      "item": <object> 
  },
  "message": <string>
}

Параметр	Тип	Описание
code	int	Код ответа, для успеха - 200
message	string	Сообщение ответа
item	object	Объект типа Пользователь

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

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

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, но для текущего пользователя.

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

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

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

{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
      // Объект типа Пользователь
    }
  }
}

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

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

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

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

{
  "password": <string>,
  "old_password": <string>
}

Параметры

Параметр	Тип	Описание	Обязательность
password	string	Новый пароль	Да
old_password	string	Старый пароль	Да

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

Этот метод позволяет обойти ограничение на изменение пароля методом user/edit для текущего пользователя.

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

Метод доступен пользователю с любой ролью.

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

{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
      // Объект типа Пользователь
    }
  }
}

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

Компания

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

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

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

{}

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

{
  "code": 200,
  "message": <string>,
  "result": {
    "item": <object>
  }
}

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

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

Список

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

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

{
  "page": <int>,
  "size": <int>,
}

Параметры

Параметр	Тип	Описание	Обязательность
page	int	Номер страницы, нумерация с 0	Да
size	int	Размер страницы	Да

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

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

Параметр	Тип	Описание
code	int	Код ответа, для успеха - 200
message	string	Сообщение ответа
count	int	Количество данных в ответе
all_count	int	Количество данных в БД
items	array	Массив элементов типа Пользователь

Создание

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

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 также не является обязательным. Если его не передать, то будет создан пользователь с ролью Пользователь

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

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

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

{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
        //объект типа Пользователь
    }
  }
}

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

Изменение

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

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 возможно поменять только другим пользователям.

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

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

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

{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
      // Объект типа Пользователь
    }
  }
}

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

Удаление

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

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

{
  "id": <int>
}

Параметры

Параметр	Тип	Описание	Обязательность
id	int	ID пользователя	Да

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

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

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

{
  "code": 200,
  "message": <string>,
  "result": {
    "item": {
       //Объект типа Пользователь
    }
  }
}

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

Группы

Список

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

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

{
  "page": <int>,
  "size": <int>,
  "filter": {
    "name": <string>
  }
}

Параметры

Параметр	Тип	Описание	Обязательность
page	int	Номер страницы, нумерация с 0	Да
size	int	Размер страницы	Да
filter.name	string	Название группы (часть названия)	Нет

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

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

Параметр	Тип	Описание
code	int	Код ответа, для успеха - 200
message	string	Сообщение ответа
count	int	Количество данных в ответе
all_count	int	Количество данных в БД
items	array	Массив элементов типа Группа

Создание

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

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

{
  "name": <string>
}

Параметры

Параметр	Тип	Описание	Обязательность
name	string	Название группы	Да

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

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

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

{
  "code": 200,
  "message": <string>,
  "result": {
    "item": <object>
  }
}

Параметр	Тип	Описание
code	int	Код ответа, для успеха - 200
message	string	Сообщение ответа
result.item	object	Объект типа Группа

Изменение

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

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

{
  "name": <string>,
  "id": <int>
}

Параметры

Параметр	Тип	Описание	Обязательность
name	string	Название группы	Да
id	int	ID группы	Да

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

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

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

{
  "code": 200,
  "message": <string>,
  "result": {
    "item": <object>
  }
}

Параметр	Тип	Описание
code	int	Код ответа, для успеха - 200
message	string	Сообщение ответа
result.item	object	Объект типа Группа

Удаление

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

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

{
  "id": <int>
}

Параметры

Параметр	Тип	Описание	Обязательность
id	int	ID группы	Да

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

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

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

{
  "code": 200,
  "message": <string>,
  "result": {
    "item": <object>
  }
}

Параметр	Тип	Описание
code	int	Код ответа, для успеха - 200
message	string	Сообщение ответа
result.item	object	Объект типа Группа