Billing API Exzotron

Billing API Exzotron#

Billing API Exzotron предоставляет программный интерфейс для работы с системой биллинга, обеспечивая доступ к управлению пользователями, объектами, а также аутентификацию и авторизацию. Все методы API возвращают стандартные коды состояния HTTP для информирования о результате выполнения запроса.

Общие характеристики#

• При успешном выполнении всех методов возвращается StatusCode = 200.
• При ошибках возвращается StatusCode = 500 или другой код ошибки, в теле ответа присутствует поле error_text с описанием ошибки.
• Все значения даты и времени передаются в формате UnixTime UTC.
• Доступ к серверу после авторизации ограничен: пользователь видит только те компании и объекты, которые доступны его учетной записи.

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

POST /api/billing/login

Входные параметры:

• string login
• string password

Параметры можно передавать как JSON, application/x-www-form-urlencoded или query/form параметры.

Пример JSON-запроса:#

{
  "login": "user_login",
  "password": "user_password"
}

Ответ при успехе:#

{
  "error_text": "",
  "token": "string"
}

Ответ при ошибке:#

{
  "error_text": "Invalid login or password",
  "token": null
}

Если пользователь заблокирован (проверка по полю ex_users.users_ban), токен не выдается.

2. Вход от имени другого пользователя#

POST /api/billing/v1/login_as

Входные параметры:

• string token — токен администратора
• string login — логин целевого пользователя

Пример запроса:#

{
  "token": "admin_token",
  "login": "target_user_login"
}

Ответ при успешном выполнении:#

{
  "error_text": "",
  "token": "string"
}

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

3. Получение списка пользователей#

POST /api/billing/v1/users

Входные параметры:

• string token

Пример запроса:#

{
  "token": "string"
}

Ответ при успехе:#

{
  "error_text": "",
  "rows": [
    {
      "user_id": 1,
      "login": "user_login"
    }
  ]
}

Администратор получает список пользователей компаний, доступных его учетной записи. Обычный пользователь получает только данные собственной учетной записи.

4. Получение списка объектов#

GET /api/billing/v1/vehicles

Входные параметры:

• string token

Пример запроса:#

GET /api/billing/v1/vehicles?token=string

Ответ при успехе:#

{
  "error_text": "",
  "rows": [
    {
      "vehicle_id": 123,
      "mnf": "869556062485751",
      "vehicle_name": "A001AA",
      "phone": "+79990000000",
      "create_date": 1780300800,
      "last_msg_date": 1780387200,
      "latitude": 55.751244,
      "longitude": 37.618423,
      "altitude": 0,
      "speed": 12.5,
      "direction": 180,
      "sat_count": 12
    }
  ]
}

Описание полей:#

Поле	Тип	Описание
vehicle_id	int64	Уникальный идентификатор объекта в системе
mnf	string	Заводской номер терминала (IMEI или серийный номер)
vehicle_name	string	Наименование объекта
phone	string	Номер SIM-карты
create_date	int64	Дата создания объекта (UnixTime UTC)
last_msg_date	int64	Дата последнего сообщения от терминала (UnixTime UTC)
latitude	double	Последнее зафиксированное местоположение, широта
longitude	double	Последнее зафиксированное местоположение, долгота
altitude	integer	Последняя высота, м
speed	double	Последняя скорость, км/ч
direction	integer	Последнее направление движения, градусы (0-359)
sat_count	integer	Количество спутников на момент последнего сообщения

Источники данных:#

• ex_objects: поля object_id, imei, object_name, phone_number, create_date
• ex_d_<imei>: последняя телеметрия (date_time/s_time, lat, lon, speed, angle, sat, alt/altitude)

Если таблицы ex_d_<imei> или отдельные колонки отсутствуют, соответствующие поля возвращаются как null.

5. Блокировка / разблокировка пользователя#

POST /api/billing/v1/enable_account

Входные параметры:

• string token
• integer user_id
• bool enable

Пример запроса:#

{
  "token": "admin_token",
  "user_id": 123,
  "enable": false
}

Ответ при успехе:#

{
  "error_text": ""
}

Метод доступен только администраторам. Пользователь должен принадлежать одной из компаний, доступных администратору.

Логика блокировки:#

• enable = true — разблокировать пользователя (ex_users.users_ban = 0)
• enable = false — заблокировать пользователя (ex_users.users_ban = 1)

Блокировка влияет на получение токена через /api/billing/login и предотвращает получение нового токена. Однако блокировка не мешает выполнению метода /api/billing/v1/login_as.

6. Выход из системы#

POST /api/billing/logout

Входные параметры:

• string token

Пример запроса:#

{
  "token": "string"
}

Ответ при успехе:#

{
  "error_text": ""
}

Метод инвалидирует текущий токен биллинга. После выполнения logout токен больше нельзя использовать в Billing API.

Ошибки#

Типовой ответ при ошибке:

{
  "error_text": "Invalid token"
}

Для методов, возвращающих токен:

{
  "error_text": "Invalid login or password",
  "token": null
}

Для методов, возвращающих массив:

{
  "error_text": "Access denied",
  "rows": []
}

Основные ошибки и их смысл:#

• Invalid login or password — Неверный логин или пароль
• User blocked — Пользователь заблокирован
• Invalid token — Токен отсутствует, истек или недействителен
• Access denied — Нет доступа к пользователю или компании
• User not found — Пользователь не найден
• Internal error — Внутренняя ошибка сервера

Источники#

• exzotron.ru
• exzotron.com