Памятка разработчику 1С: интеграция с EXZOTRON API для учета выдачи топлива

Документ описывает базовые методы EXZOTRON API, которые нужны для загрузки данных в 1С, получения операций выдачи топлива и управления RFID-картами: добавление, переименование, блокировка, лимиты, привязка к автомобилям и двойная идентификация.

Актуальная документация API:

• Swagger UI: https://5g.exzotron.ru/swagger-ui/
• OpenAPI JSON: https://5g.exzotron.ru/v3/api-docs

Базовый адрес:

Все методы ниже находятся в префиксе /api/v1.

1. Авторизация#

API защищен стандартной авторизацией Spring Security. Для интеграции из 1С обычно используется один из вариантов:

1. HTTP Basic Auth, если он разрешен для учетной записи.
2. Авторизация через форму /login с сохранением cookie JSESSIONID.

CSRF в проекте отключен, поэтому отдельный CSRF-токен для POST/PUT/PATCH не нужен.

Права зависят от роли пользователя. Для управления картами обычно нужны ROLE_ADMIN или ROLE_ADVANCED_USER. Для чтения отчетов часто достаточно ROLE_USER, но часть методов доступна только администратору.

Пример проверки через curl с Basic Auth:

Пример через cookie-сессию:

2. Общий шаблон HTTP-запроса из 1С#

Для POST, PUT, PATCH JSON передается в тело запроса:

3. Справочники, которые желательно загрузить в 1С#

Компании#

GET /api/v1/get_list_company_transformed

Назначение: получить список доступных компаний и их идентификаторы.

Основные поля ответа:

• id - ID компании в EXZOTRON.
• name, nameRu, nameEn - наименование.
• telegram - Telegram ID пользователя/компании, часто нужен в старых API-методах как idUserTelegram.
• utc, workFactUtc - часовой пояс.
• rfidInsertStatus - тип RFID по умолчанию при добавлении.

Пример:

Виды топлива/продукты#

GET /api/v1/get_products

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

Основные поля: id, name, nameRu, price.

Пример:

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

GET /api/v1/report_list_imei_current_user

Назначение: получить список модулей/объектов, доступных текущему пользователю.

Основные поля:

• id - внутренний ID объекта.
• imei - IMEI модуля.
• name - наименование.
• companyId - компания.
• productId, productName - продукт/топливо.
• divisionId, divisionName - подразделение.
• trkTypeId, trkTypeName - тип ТРК.
• status, licenseDate, lastReceivedPackageTime.

Пример:

Типы RFID-карт/объектов#

GET /api/v1/object_rfid_type

Назначение: получить справочник типов RFID-объектов.

Из базы проекта используются типы:

Пример:

Типы лимитов#

GET /api/v1/get_limit_types

Назначение: получить справочник типов лимита. В карточке RFID также есть поле status:

Пример:

4. Загрузка RFID-карт в 1С#

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

GET /api/v1/rfid_list_api

Параметры:

Пример:

Ответ приходит как объект с наборами obj1, obj2, ... В 1С его удобнее разбирать как соответствие и сохранять только нужные поля карты.

Для детальной карточки лучше использовать:

GET /api/v1/get_rfid_object?rfid=123456789&companyId=10&productId=1

Основные поля детальной карточки:

• id - внутренний ID RFID-объекта.
• rfid - номер карты.
• name - имя карты.
• typeId, typeName - тип RFID-объекта.
• status - лимитная/безлимитная/заблокированная.
• dailyLimit - суточный лимит.
• balance - текущий баланс.
• dailyBalance - остаток суточного лимита.
• pinCode - PIN.
• vehicleId, vehicleName - связанный автомобиль.
• employeeId, employeeName - связанный сотрудник.
• divisionId, divisionName - подразделение.
• partnerId, partnerName - контрагент/партнер.
• expireDate - срок действия.

5. Управление RFID-картами из 1С#

Добавить RFID-карту#

POST /api/v1/add_rfid

Тело JSON:

Пример:

Примечание: в контроллере /add_rfid companyId и productId есть в DTO, но фактически метод опирается на текущего пользователя и его текущий продукт/подразделение. Если нужна жесткая привязка к компании/продукту, стоит согласовать использование /add_rfid_api или текущего контекста пользователя.

Переименовать RFID-карту#

PUT /api/v1/set_name_rfid_tag_api

Параметры:

Пример:

Установить лимитная/безлимитная#

PUT /api/v1/set_rfid_type_limit

Параметры:

В коде обработки bulk-режима используется логика:

• limitType=false - безлимитная карта.
• limitType=true - лимитная карта.

Пример установки лимитной карты:

Установить суточный лимит#

PUT /api/v1/set_day_limit

Параметры:

Пример:

Начислить топливо на баланс RFID-карты#

PATCH /api/v1/move_count_api

Параметры:

Возвращает строку с результатом/ID операции.

Пример:

Пример сторнирования 100 л, ранее ошибочно начисленных на карту:

curl -u "login:password" -X PATCH \
  "https://5g.exzotron.ru/api/v1/move_count_api?idUserTelegram=123456&idCompany=10&idProduct=1&rfid=1234567890&count=-100"

Заблокировать карту#

PATCH /api/v1/rfid_lock

Параметры:

Пример:

Разблокировать карту#

PATCH /api/v1/rfid_delock

Установить PIN#

PUT /api/v1/set_pin

Установить подразделение карты#

PUT /api/v1/rfid/set_division

Установить срок действия карты#

PUT /api/v1/rfid/set_expire_date

Добавить RFID-карту (новый вариант, с явной компанией/продуктом)#

POST /api/v1/add_rfid_new

В отличие от /add_rfid, здесь companyId/productId реально используются (а не берутся из контекста текущего пользователя), и сервер дополнительно проверяет, что вызывающий пользователь действительно принадлежит указанной компании. Позволяет сразу указать привязку к автомобилю, подразделение, тип карты, статус и срок действия — без отдельных вызовов.

Тело JSON:

{
  "name": "Иванов И.И.",
  "companyId": 10,
  "productId": 1,
  "rfid": "1234567890",
  "vehicleId": null,
  "status": 0,
  "typeId": 1,
  "divisionId": null,
  "expireDate": null
}

Пример:

curl -u "login:password" -X POST "https://5g.exzotron.ru/api/v1/add_rfid_new" \
  -H "Content-Type: application/json" \
  -d '{"name":"Иванов И.И.","companyId":10,"productId":1,"rfid":"1234567890","typeId":1,"status":0}'

Добавить сразу несколько карт (пакетно)#

POST /api/v1/add_rfid_bulk

Принимает список карт построчно в одном текстовом поле — удобно для разовой загрузки готового списка без цикла из отдельных запросов /add_rfid. Формат строки (через запятую, поля после rfid — необязательны):

rfid,name,pin,mode,type_rfid,product

Пример — добавить две карты, одну сразу лимитной:

curl -u "login:password" -X POST "https://5g.exzotron.ru/api/v1/add_rfid_bulk" \
  -H "Content-Type: application/json" \
  -d '{"text":"1234567890,Иванов И.И.,0,2,1\n0987654321,Петров П.П."}'

Ответ — список результатов по каждой строке (номер строки, распознанный текст, признак успеха, сообщение).

Привязать существующего сотрудника к RFID-карте#

Отдельного метода вида set_employee_id_to_rfid нет — привязка идёт через общий метод обновления карты:

PUT /api/v1/set_name_rfid_tag

Пример:

curl -u "login:password" -X PUT \
  "https://5g.exzotron.ru/api/v1/set_name_rfid_tag?idUserTelegram=123456&rfid=1234567890&pinCode=0&employeeId=42"

Создать сотрудника и сразу привязать карту#

POST /api/v1/create_employee_from_rfid

Если сотрудника ещё нет в справочнике — создаёт его с ФИО из имени карты и сразу привязывает. Удобно, когда карта уже была заведена (например, синхронизирована), а сотрудника под неё завести отдельно не хочется.

curl -u "login:password" -X POST \
  "https://5g.exzotron.ru/api/v1/create_employee_from_rfid?companyId=10&productId=1&rfid=1234567890"

Ответ: {"employeeId": 42}.

Удалить RFID-карту#

DELETE /api/v1/delete_rfid

Пример:

curl -u "login:password" -X DELETE \
  "https://5g.exzotron.ru/api/v1/delete_rfid?rfid=1234567890"

6. Автомобили и двойная идентификация#

Двойная идентификация в EXZOTRON означает, что при выдаче топлива могут участвовать две RFID-метки:

• rfid_tag1 / rfidUser - карта пользователя/водителя/сотрудника.
• rfid_tag2 / rfidVehicle - карта автомобиля.
• Дополнительно может быть rfid_tag3 / rfidRandomObject - произвольный объект.

В 1С для корректной загрузки двойной идентификации рекомендуется хранить:

• справочник RFIDКарты: номер RFID, тип, статус, лимит, баланс;
• справочник Автомобили: ID EXZOTRON, госномер, наименование, IMEI, RFID автомобиля;
• связь RFIDКартаАвтомобиль: rfid, vehicleId, productId, companyId;
• в документах выдачи топлива: rfidUser, rfidVehicle, vehicleId, vehicleName, imei.

Загрузить список автомобилей#

GET /api/v1/vehicle

Параметры:

Пример:

Основные поля автомобиля:

• id - ID автомобиля.
• name, nameRu, nameEn - наименование.
• licensePlate - госномер.
• garageNumber - гаражный номер.
• rfid - RFID автомобиля для двойной идентификации.
• imei - IMEI объекта мониторинга.
• divisionId, divisionName - подразделение.
• companyId - компания.

Добавить автомобиль#

POST /api/v1/vehicle

Тело JSON:

Метод возвращает id созданного автомобиля.

Пример:

Изменить автомобиль#

PUT /api/v1/vehicle

Передается объект Vehicle с заполненным id.

Привязать автомобиль к RFID-карте#

PATCH /api/v1/set_vehicle_id_to_rfid

Параметры:

Пример:

Создать автомобиль и сразу привязать карту (короткий путь)#

POST /api/v1/create_vehicle_from_rfid

Заменяет шаги 1–3 сценария ниже одним вызовом, если карта уже создана с типом «Автомобиль»: берёт имя и RFID из самой карты, создаёт автомобиль и сразу привязывает.

curl -u "login:password" -X POST \
  "https://5g.exzotron.ru/api/v1/create_vehicle_from_rfid?companyId=10&productId=1&rfid=987654321"

Ответ: {"vehicleId": 25}.

Практический сценарий для 1С:

1. Создать/обновить автомобиль через /api/v1/vehicle.
2. Создать RFID-карту типа Vehicles, то есть typeRfid = "2".
3. Привязать карту к автомобилю через /api/v1/set_vehicle_id_to_rfid.
4. При загрузке операций сохранять и карту водителя, и карту автомобиля.

7. Отчеты и загрузка операций выдачи топлива#

Журнал операций по RFID-картам#

GET /api/v1/report_by_rfid

Параметры:

Пример:

Основные поля операции:

• accountOperationId - ID операции.
• operationLogId - ID записи журнала.
• dateTime, operationDateTime - дата операции.
• account - счет/RFID.
• quantity - количество топлива.
• debit, credit - движение по счету.
• count, finalBalance - количество/остаток.
• productId, product - продукт.
• imei, objectName - ТРК/модуль.
• rfidUser - RFID водителя/сотрудника.
• rfidVehicle - RFID автомобиля.
• rfidRandomObject - RFID произвольного объекта.
• rfidName - имя RFID.
• vehicleId, vehicleName, vehicleImei - автомобиль.
• tankStart, tankEnd, tank - топливо в баке.
• totalCounterIn, totalCounterOut, fuelCounter, totalAccount - счетчики.

Журнал транзакций по IMEI за период#

GET /api/v1/report_by_objects_income

Параметры:

Пример:

Для 1С это основной метод для загрузки фактических транзакций по ТРК/IMEI за период. Для двойной идентификации обязательно сохраняйте поля rfidUser, rfidVehicle, vehicleId, vehicleName.

8. Рекомендуемая последовательность обмена с 1С#

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

1. GET /api/v1/get_products - загрузить продукты/виды топлива.
2. GET /api/v1/get_list_company_transformed - загрузить компании и определить companyId.
3. GET /api/v1/object_rfid_type - загрузить типы RFID.
4. GET /api/v1/get_limit_types - загрузить типы лимитов.
5. GET /api/v1/report_list_imei_current_user - загрузить ТРК/IMEI.
6. GET /api/v1/vehicle - загрузить автомобили.
7. GET /api/v1/rfid_list_api или GET /api/v1/get_rfid_object - загрузить RFID-карты.

Регулярная загрузка операций выдачи топлива#

1. Взять период обмена из регистра 1С, например последние 1-3 дня с перекрытием.
2. Получить операции по IMEI: /api/v1/report_by_objects_income.
3. Сопоставить операции по ключу operationLogId или accountOperationId.
4. Обновить/создать документы выдачи топлива.
5. Сохранить rfidUser, rfidVehicle, vehicleId, imei, quantity, dateTime, productId.

Управление картами из 1С#

1. Добавить карту: /api/v1/add_rfid.
2. Если это автомобильная карта: создать/найти автомобиль и привязать /api/v1/set_vehicle_id_to_rfid.
3. Установить тип лимита: /api/v1/set_rfid_type_limit.
4. Установить суточный лимит: /api/v1/set_day_limit.
5. При необходимости установить PIN, подразделение, срок действия.
6. При увольнении/выводе из эксплуатации блокировать карту через /api/v1/rfid_lock, а не удалять.

9. Минимальная модель данных в 1С#

Справочник ЭкзотронКомпании#

• ИдентификаторEXZOTRON
• Наименование
• Telegram
• UTC

Справочник ЭкзотронПродукты#

• ИдентификаторEXZOTRON
• Наименование
• Цена

Справочник ЭкзотронRFIDКарты#

• RFID
• Наименование
• Компания
• Продукт
• ТипКарты
• Статус
• СуточныйЛимит
• Баланс
• PIN
• СрокДействия
• Автомобиль
• Сотрудник
• Подразделение

Справочник ЭкзотронАвтомобили#

• ИдентификаторEXZOTRON
• Наименование
• ГосНомер
• ГаражныйНомер
• RFIDАвтомобиля
• IMEI
• Подразделение

Документ/регистр ЭкзотронВыдачаТоплива#

• ИдентификаторОперации
• ИдентификаторЖурнала
• ДатаОперации
• IMEI
• ОбъектТРК
• Продукт
• Количество
• RFIDПользователя
• RFIDАвтомобиля
• Автомобиль
• ОстатокДо
• ОстатокПосле
• Счетчики

10. Важные замечания для 1С-разработчика#

• Даты передавайте URL-encoded, например 2026-06-01%2000:00:00.
• Числа RFID храните строкой. Большие RFID-номера безопаснее не превращать в число 1С.
• Для повторной загрузки операций используйте идемпотентность по operationLogId/accountOperationId.
• Для двойной идентификации не ограничивайтесь полем account: в отчетах отдельно есть rfidUser и rfidVehicle.
• Для автомобильных карт используйте тип RFID 2 и связь через /api/v1/set_vehicle_id_to_rfid.
• Блокировка карты меняет доступ, но сохраняет историю операций. Это предпочтительнее удаления.
• idUserTelegram берите из карточки компании/пользователя, если метод его требует.
• Методы /api/v1/rfid_list_api, /api/v1/set_rfid_type_limit, /api/v1/set_day_limit, /api/v1/move_count_api дополнительно проверяют доступ к компании.

11. Короткая таблица методов#