https://5g.exzotron.ru/swagger-ui/#/

API EXZOTRON

Базовые методы работы с компаниями, модулями ТРК, RFID-объектами, транспортом, лимитами и отчётностью#

1. Назначение API#

API EXZOTRON предназначен для интеграции внешних информационных систем с серверной платформой учёта топлива и управления отпуском продукта. Через API можно получать доступные компании и подключённые модули ТРК, загружать и создавать RFID-объекты, управлять лимитами и балансами, блокировать и разблокировать карты, привязывать транспортные средства к RFID-меткам, а также получать журналы операций за выбранный период.

API может использоваться в интеграции с учётными системами, локальными терминалами управления топливораздаточным оборудованием, мобильными приложениями, сервисными панелями и внешними системами аналитики.

Интерактивная документация API размещена по адресам:

• https://5g.exzotron.ru/swagger
• https://5g.exzotron.ru/swagger-ui/

Базовые методы API имеют префикс:

/api/v1/

2. Основные сущности системы#

Компания#

Компания — организация, которой принадлежат модули ТРК, RFID-объекты, автомобили, лимиты и журналы операций. При работе через API пользователь получает доступ только к тем компаниям, которые доступны его учётной записи.

Модуль ТРК / IMEI#

Модуль ТРК — аппаратный объект, установленный на топливораздаточном оборудовании или связанном устройстве. Основным идентификатором модуля является IMEI. По IMEI можно определить источник отпуска топлива и получить журнал транзакций за период.

RFID-объект#

RFID-объект — идентификационная метка, карта или иной электронный идентификатор, применяемый для разрешения выдачи топлива. RFID-объект может быть связан с автомобилем, сотрудником или другим объектом учёта.

Для RFID-объекта могут задаваться:

• наименование;
• тип объекта;
• признак лимитной или безлимитной карты;
• суточный лимит;
• баланс доступного топлива;
• состояние блокировки;
• связь с транспортным средством.

Автомобиль#

Автомобиль — объект автотранспорта, который может быть создан в системе и привязан к RFID-метке. Такая привязка позволяет определять, какому транспортному средству произведена выдача топлива.

Лимит и баланс#

Лимит определяет допустимые условия выдачи топлива по RFID-объекту. В системе может использоваться лимитная карта, для которой контролируется доступный объём, либо безлимитная карта, позволяющая производить выдачу без ограничения по установленному балансу.

Баланс — доступное количество топлива, начисленное RFID-объекту для последующего использования.

Операция#

Операция — запись о начислении, выдаче или иной транзакции, связанной с RFID-объектом либо модулем ТРК. Операции используются для контроля движения топлива и формирования отчётности.

3. Методы получения справочной информации

3.1. Получение списка доступных компаний#

Метод#

/api/v1/get_list_company_transformed

Назначение#

Метод предназначен для получения перечня компаний, доступных текущему пользователю API. Каждая компания возвращается с идентификатором, который в дальнейшем используется при запросах к модулям ТРК, RFID-объектам, транспорту, лимитам и отчётам.

Когда используется#

Метод вызывается на начальном этапе работы интеграции:

1. пользователь проходит авторизацию;
2. система получает перечень доступных компаний;
3. пользователь или программная логика выбирает нужную компанию;
4. идентификатор выбранной компании используется в последующих запросах.

Результат работы#

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

Практическое применение#

Метод используется:

• для первоначальной настройки интеграции;
• для выбора организации в интерфейсе программы;
• для определения company_id, необходимого при дальнейших операциях;
• для разграничения данных между несколькими организациями одного пользователя.

3.2. Получение списка модулей ТРК текущего пользователя#

Метод#

/api/v1/report_list_imei_current_user

Назначение#

Метод предназначен для загрузки списка доступных текущему пользователю модулей ТРК, идентифицируемых по IMEI.

Модули ТРК представляют собой аппаратные устройства, через которые производится отпуск топлива либо осуществляется сбор данных с оборудования.

Когда используется#

Метод применяется после выбора компании либо в процессе синхронизации локальной системы с сервером.

Результат работы#

Система получает перечень модулей ТРК, доступных пользователю, включая их IMEI и сопутствующие сведения, предусмотренные сервером.

Практическое применение#

Метод необходим для:

• загрузки подключённого оборудования;
• выбора конкретного модуля ТРК в интерфейсе;
• связи операций выдачи топлива с физическим оборудованием;
• получения последующей отчётности по IMEI;
• синхронизации локального терминала с серверной конфигурацией.

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

Метод#

/api/v1/rfid_list_api

Назначение#

Метод предназначен для загрузки списка RFID-объектов, доступных пользователю или выбранной компании. RFID-объекты используются для идентификации автомобилей, сотрудников или иных получателей топлива.

Получаемые сведения#

В зависимости от серверной схемы по RFID-объекту могут быть доступны:

• идентификатор объекта;
• код RFID-метки;
• наименование объекта;
• тип RFID-объекта;
• связанный автомобиль;
• признак лимитной или безлимитной карты;
• установленный лимит;
• текущий баланс;
• состояние блокировки;
• сведения о доступном продукте.

Когда используется#

Метод вызывается:

• при первоначальной загрузке справочника меток;
• при синхронизации локальной базы RFID-карт;
• при проверке существования метки перед добавлением новой;
• при отображении списка карт в административном интерфейсе;
• при подготовке операций начисления или блокировки.

Результат работы#

Возвращается актуальный перечень RFID-объектов с их серверными идентификаторами и параметрами доступа.

3.4. Получение списка автомобилей#

Метод#

/api/v1/vehicle

Назначение#

Метод используется для загрузки списка автотранспортных средств, зарегистрированных в системе EXZOTRON.

Когда используется#

Загрузка списка автомобилей необходима:

• при создании или редактировании RFID-объекта;
• при привязке карты к автомобилю;
• при построении отчётности по транспорту;
• при отображении транспортных средств в учётной системе.

Результат работы#

Система получает перечень зарегистрированных автомобилей с идентификаторами, которые могут применяться при последующей привязке к RFID-объекту.

4. Методы управления RFID-объектами

4.1. Добавление нового RFID-объекта#

Метод#

/api/v1/add_rfid

Назначение#

Метод предназначен для создания нового RFID-объекта с типом «автомобиль». Созданный объект впоследствии может быть настроен как лимитный или безлимитный, связан с автомобилем, переименован, заблокирован либо использован для операций начисления топлива.

Типовой сценарий использования#

1. Пользователь вводит код новой RFID-метки.
2. Программа проверяет, отсутствует ли такой объект в загруженном перечне.
3. Выполняется запрос на создание нового RFID-объекта.
4. Сервер возвращает результат создания и идентификатор нового объекта.
5. После создания выполняются дополнительные настройки: название, тип лимита, баланс, суточный лимит и привязка к автомобилю.

Практическое применение#

Метод используется при:

• регистрации новой топливной карты;
• создании RFID-карты автомобиля;
• массовой загрузке меток из внешней системы;
• переносе справочника RFID-объектов из учётной программы на сервер.

Важное замечание#

Перед созданием нового объекта необходимо контролировать уникальность RFID-кода с учётом правил, действующих на сервере.

4.2. Переименование RFID-метки#

Метод#

/api/v1/set_name_rfid_tag_api

Назначение#

Метод предназначен для изменения отображаемого наименования RFID-объекта.

Название позволяет пользователю быстро определять, кому или чему принадлежит карта: автомобилю, водителю, подразделению, оборудованию или иному объекту учёта.

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

• КАМАЗ А123ВС
• Экскаватор CAT 320
• Водитель Иванов И.И.
• Служебный автомобиль №5

Когда используется#

Метод применяется:

• сразу после создания RFID-объекта;
• при смене автомобиля или владельца карты;
• при исправлении ошибочного названия;
• при синхронизации изменений из внешней учётной системы.

Результат работы#

Наименование выбранной RFID-метки изменяется на сервере и должно быть обновлено в локальном справочнике интегрированной системы.

4.3. Установка типа лимита RFID-карты#

Метод#

/api/v1/set_rfid_type_limit

Назначение#

Метод предназначен для определения режима использования RFID-карты: лимитная или безлимитная.

Лимитная карта#

Для лимитной карты выдача топлива допускается только в пределах установленного доступного объёма либо других ограничений, предусмотренных системой. При совершении операций доступный остаток контролируется и уменьшается.

Безлимитная карта#

Для безлимитной карты выдача топлива разрешается без контроля фиксированного остатка, если объект не заблокирован и имеет доступ к соответствующему продукту или оборудованию.

Когда используется#

Метод вызывается:

• при первичной настройке новой карты;
• при изменении политики выдачи топлива;
• при переводе автомобиля с безлимитного режима на лимитный;
• при временном снятии ограничений с карты;
• при массовом обновлении параметров RFID-объектов.

Результат работы#

Сервер сохраняет установленный тип лимита для выбранного RFID-объекта. Все дальнейшие операции выдачи топлива должны учитывать новый режим.

4.4. Установка суточного лимита#

Метод#

/api/v1/set_day_limit

Назначение#

Метод предназначен для задания суточного лимита расхода топлива по выбранному RFID-объекту.

Суточный лимит позволяет ограничить максимальный объём топлива, который может быть выдан по карте в течение календарных суток либо иного расчётного периода, установленного серверной логикой.

Когда используется#

Метод необходим:

• для ограничения расхода топлива автомобилем;
• для контроля выдачи по сменам или суткам;
• при настройке лимитных топливных карт;
• при изменении нормативов расхода;
• при интеграции с внешней системой управления лимитами.

Пример бизнес-логики#

Автомобилю может быть начислен общий баланс топлива, но одновременно установлено ограничение, запрещающее получить больше определённого объёма в течение суток.

Результат работы#

Для RFID-объекта сохраняется установленное суточное ограничение. При последующей выдаче топлива сервер учитывает наличие и размер лимита.

4.5. Начисление топлива на баланс RFID-объекта#

Метод#

/api/v1/move_count_api

Назначение#

Метод предназначен для начисления топлива на баланс выбранного RFID-объекта. При успешном выполнении создаётся операция начисления, идентификатор которой может использоваться для последующей сверки, журналирования и отчётности.

Когда используется#

Метод применяется:

• при назначении лимита автомобилю;
• при пополнении баланса топливной карты;
• при проведении документа начисления из учётной системы;
• при корректировке доступного остатка топлива;
• при синхронизации лимитов между внешней системой и сервером EXZOTRON.

Типовой сценарий#

1. Выбирается компания.
2. Выбирается RFID-объект.
3. Указывается объём начисляемого топлива.
4. Отправляется запрос на сервер.
5. Сервер фиксирует операцию начисления.
6. В ответе возвращается результат выполнения и идентификатор созданной операции.
7. Внешняя система сохраняет этот идентификатор для контроля обмена.

Результат работы#

Баланс RFID-объекта увеличивается на переданный объём топлива, а на сервере создаётся запись об операции начисления.

4.6. Блокировка RFID-объекта#

Метод#

/api/v1/rfid_lock

Назначение#

Метод предназначен для блокировки RFID-объекта. Заблокированная карта не должна использоваться для разрешения выдачи топлива до момента снятия блокировки.

Причины блокировки#

Блокировка может применяться в случаях:

• утери топливной карты;
• увольнения сотрудника;
• вывода автомобиля из эксплуатации;
• выявления подозрительных операций;
• временного запрета на получение топлива;
• замены идентификатора новым.

Когда используется#

Метод вызывается из административного интерфейса, учётной системы либо автоматизированного процесса контроля безопасности.

Результат работы#

RFID-объект получает статус заблокированного. При попытке использования такой карты выдача топлива должна быть запрещена.

4.7. Разблокировка RFID-объекта#

Метод#

/api/v1/rfid_delock

Назначение#

Метод предназначен для снятия ранее установленной блокировки с RFID-объекта.

Когда используется#

Разблокировка выполняется:

• после возврата временно заблокированной карты;
• после устранения причины блокировки;
• после подтверждения возможности дальнейшей эксплуатации автомобиля;
• при ошибочной блокировке объекта.

Результат работы#

RFID-объект вновь становится доступным для применения в операциях выдачи топлива при соблюдении остальных условий: наличия лимита, баланса, разрешённого продукта и доступа к оборудованию.

5. Методы управления транспортом

5.1. Добавление автомобиля#

Метод#

/api/v1/vehicle

Назначение#

Метод применяется не только для получения списка транспорта, но и для добавления нового автомобиля в справочник. Конкретное действие определяется типом операции и параметрами запроса, предусмотренными Swagger-документацией.

Когда используется#

Автомобиль создаётся в системе перед его привязкой к RFID-объекту, если соответствующее транспортное средство ещё отсутствует в справочнике.

Основные сведения об автомобиле#

В зависимости от схемы сервера для автомобиля могут использоваться:

• государственный регистрационный номер;
• отображаемое наименование;
• внутренний идентификатор;
• дополнительные сведения об объекте транспорта.

Типовой сценарий#

1. Выполняется загрузка существующего списка автомобилей.
2. Если нужный автомобиль отсутствует, он создаётся через API.
3. После получения его серверного идентификатора выполняется привязка к RFID-объекту.

Результат работы#

В системе появляется новый автомобиль, который можно использовать в справочниках, отчётах и связях с RFID-картами.

5.2. Привязка автомобиля к RFID-объекту#

Метод#

/api/v1/set_vehicle_id_to_rfid

Назначение#

Метод предназначен для установки связи между зарегистрированным автомобилем и RFID-объектом.

После выполнения привязки операции, совершённые по данной RFID-карте, могут интерпретироваться как операции конкретного транспортного средства.

Когда используется#

Метод вызывается:

• после создания нового RFID-объекта;
• после добавления нового автомобиля;
• при замене карты на автомобиле;
• при передаче RFID-карты другому транспортному средству;
• при восстановлении связей после импорта справочников.

Типовой сценарий#

1. Создаётся либо выбирается существующий автомобиль.
2. Создаётся либо выбирается существующий RFID-объект.
3. Передаются идентификаторы автомобиля и RFID-объекта.
4. Сервер сохраняет связь.
5. При последующей выдаче топлива операция может быть связана с автомобилем.

Результат работы#

RFID-объект становится связанным с выбранным автомобилем, что позволяет вести учёт топлива не только по карте, но и по транспортному средству.

6. Методы получения отчётности

6.1. Получение журнала операций по RFID-объекту за период#

Метод#

/api/v1/report_by_rfid

Назначение#

Метод предназначен для получения журнала операций, относящихся к конкретному RFID-объекту, за заданный период времени.

Когда используется#

Метод необходим:

• для просмотра истории использования топливной карты;
• для контроля начислений и списаний;
• для формирования отчёта по автомобилю или сотруднику;
• для сверки операций между сервером и внешней учётной системой;
• для анализа расхода топлива по конкретному объекту.

Отчёт может содержать#

В зависимости от серверной реализации в журнале могут отображаться:

• дата и время операции;
• RFID-объект;
• связанный автомобиль;
• тип операции;
• количество топлива;
• остаток или изменение баланса;
• связанный модуль ТРК;
• идентификатор операции;
• дополнительные служебные сведения.

Типовой сценарий#

1. Пользователь выбирает RFID-объект.
2. Указывает начало и окончание отчётного периода.
3. Выполняется запрос отчёта.
4. Полученные операции отображаются в журнале либо сохраняются в локальной базе.

Результат работы#

Формируется журнал всех доступных операций по выбранной RFID-метке за указанный период.

6.2. Получение журнала транзакций по IMEI за период#

Метод#

/api/v1/report_by_objects_income

Назначение#

Метод предназначен для получения журнала транзакций за выбранный период по модулю ТРК, определяемому через IMEI.

В отличие от отчёта по RFID-объекту, данный метод ориентирован на оборудование: он позволяет определить, какие операции выполнялись через конкретный модуль ТРК.

Когда используется#

Метод применяется:

• для контроля отпуска топлива через конкретную точку выдачи;
• для получения истории операций АЗС или топливного модуля;
• для сверки показаний оборудования и серверных данных;
• для анализа загрузки отдельных модулей ТРК;
• для формирования отчётности по объектам хранения и выдачи топлива.

Отчёт может содержать#

В зависимости от реализации серверного ответа:

• IMEI модуля ТРК;
• дату и время транзакции;
• количество выданного либо принятого топлива;
• связанный RFID-объект;
• транспортное средство;
• идентификатор операции;
• тип операции;
• дополнительные данные оборудования.

Типовой сценарий#

1. Загружается перечень доступных модулей ТРК через метод /api/v1/report_list_imei_current_user.
2. Выбирается требуемый IMEI.
3. Указывается отчётный период.
4. Выполняется запрос /api/v1/report_by_objects_income.
5. Полученные данные используются для анализа либо выгрузки в учётную систему.

Результат работы#

Формируется журнал транзакций, выполненных через выбранный модуль ТРК за заданный период.

7. Рекомендуемая последовательность работы с API

7.1. Первичная загрузка справочников#

При первом подключении внешней системы рекомендуется выполнить следующую последовательность:

1. Получить перечень доступных компаний:
   • /api/v1/get_list_company_transformed
2. Выбрать рабочую компанию и сохранить её идентификатор.
3. Загрузить доступные модули ТРК:
   • /api/v1/report_list_imei_current_user
4. Загрузить перечень RFID-объектов:
   • /api/v1/rfid_list_api
5. Загрузить перечень автомобилей:
   • /api/v1/vehicle

После выполнения этих действий внешняя система получает основные справочники для дальнейшей работы.

7.2. Создание и настройка новой RFID-карты автомобиля#

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

1. Проверить отсутствие RFID-объекта в текущем списке.
2. При необходимости создать автомобиль:
   • /api/v1/vehicle
3. Создать RFID-объект с типом «автомобиль»:
   • /api/v1/add_rfid
4. Задать понятное наименование RFID-метки:
   • /api/v1/set_name_rfid_tag_api
5. Установить тип карты:
   • /api/v1/set_rfid_type_limit
6. При лимитной карте установить суточный лимит:
   • /api/v1/set_day_limit
7. Привязать автомобиль к RFID-объекту:
   • /api/v1/set_vehicle_id_to_rfid
8. При необходимости начислить стартовый баланс:
   • /api/v1/move_count_api

7.3. Начисление топлива на карту#

Для начисления доступного объёма топлива на RFID-объект применяется следующий сценарий:

1. Выбрать RFID-объект.
2. Проверить его состояние: карта должна быть активной и не заблокированной.
3. Проверить установленный тип лимита.
4. Выполнить начисление топлива:
   • /api/v1/move_count_api
5. Сохранить возвращённый идентификатор операции.
6. При необходимости проверить результат через отчёт:
   • /api/v1/report_by_rfid

7.4. Блокировка и восстановление карты#

При необходимости временно запретить работу карты применяется метод:

• /api/v1/rfid_lock

После устранения причины блокировки доступ восстанавливается методом:

• /api/v1/rfid_delock

После изменения статуса RFID-объекта рекомендуется выполнить повторную загрузку его данных либо обновить соответствующую запись в локальной базе.

7.5. Получение отчётности#

Для анализа операций используются два основных направления отчётности:

По RFID-объекту#

Метод:

• /api/v1/report_by_rfid

Используется, когда требуется выяснить, какие операции выполнялись по определённой карте, автомобилю или получателю топлива.

По модулю ТРК / IMEI#

Метод:

• /api/v1/report_by_objects_income

Используется, когда требуется проанализировать все операции, прошедшие через конкретный модуль выдачи топлива.

8. Таблица базовых методов API

9. Требования к интеграции внешней системы

При разработке программного модуля, использующего API EXZOTRON, необходимо предусмотреть:

• хранение идентификаторов компаний, модулей ТРК, RFID-объектов, автомобилей и операций;
• регулярную синхронизацию справочников RFID и транспорта;
• обработку ошибок сервера и недоступности соединения;
• защиту от повторного создания одинаковых объектов;
• сохранение идентификаторов операций начисления;
• контроль статуса блокировки карты до начала выдачи топлива;
• проверку лимитов и балансов перед разрешением операции;
• журналирование запросов и ответов API;
• возможность повторной отправки операций при временном отсутствии связи;
• разграничение данных по компании и пользователю.

Для автономных терминалов или локальных приложений рекомендуется дополнительно использовать локальную базу данных, в которой сохраняются актуальные справочники RFID-карт, модулей ТРК, автомобилей, лимитов и очередь операций, ожидающих синхронизации с сервером.

10. Итоговое назначение API

API EXZOTRON обеспечивает полный базовый цикл работы с системой учёта топлива:

• выбор доступной компании;
• загрузка подключённых модулей ТРК;
• получение и управление RFID-метками;
• регистрация автомобилей и привязка их к картам;
• назначение лимитов и начисление топлива;
• блокировка и разблокировка средств идентификации;
• получение журналов операций по картам и оборудованию.

Использование API позволяет связать сервер EXZOTRON с внешними учётными системами и локальными терминалами, обеспечить контроль выдачи топлива по RFID-картам, отслеживать операции по модулям ТРК и формировать достоверную отчётность по движению продукта.
:::

В данном варианте сознательно не указаны HTTP-методы (GET/POST), обязательные поля JSON, заголовки авторизации и точные структуры ответов: они должны быть выгружены непосредственно из активной OpenAPI-схемы Swagger, чтобы не зафиксировать недостоверные параметры.