Доброго времени суток!
В этой статье хочу поделиться описание интерфейса взаимодействия сервиса Лукойл ЛИКАРД, с информационно системой 1С:Предприятие, а также показать пример, как можно программно получить данные из описанных веб-сервисов. Данная статья будет наиболее полезна, специалистам, занимающихся интеграцией автотранспортных конфигураций с топливными сервисами.
Описание будет приведено по шаблону:
Имя параметра, тип, обязательный (да, нет), описание
Входящие параметры - то, что будем передавать, исходящие -то, что получаем в ответ.
1. Сервисы по работе с клиентами
1.1. getClientDrivers
Сервис выполняет запрос списка зарегистрированных водителей для клиента.
Входящие параметры:
clientId INTEGER Содержит Идентификатор клиента в сервисе ЛИКАРД
Исходящие параметры:
driverId INTEGER Идентификатор водителя.
shortName STRING Короткое имя водителя.
driverSurname STRING Фамилия водителя.
driverName STRING Имя водителя.
driverMiddleName STRING Отчество водителя.
vehicleId INTEGER Идентификатор транспортного средства.
vehicleNumber STRING Номер транспортного средства.
2. Cервисы по работе с договорами
2.1 getContractInfo
Сервис выполняет запрос информации по договору.
Входящие параметры:
contractId INTEGER Да Идентификатор договора.
Исходящие параметры:
clientId INTEGER Идентификатор клиента.
clientShortName STRING Короткое имя клиента.
contractNumber STRING Номер договора.
openDate DATE Дата вступления контракта в силу.
Выдается в формате «YYYY-MM-DD»
closeDate DATE Дата окончания договора.
Выдается в формате «YYYY-MM-DD»
amountAvailable DECIMAL Текущий баланс договора.
totalBalance DECIMAL Суммарный баланс по картам договора.
volumePrev DECIMAL Расход литров за предыдущий месяц.
volume DECIMAL Расход литров за текущий месяц.
creditLimit DECIMAL Кредитный лимит.
statusId INTEGER Код статуса договора.
status STRING Статус договора.
discountStatusCode STRING Код статуса договора по потреблению.
discountStatus STRING Значение для отображения статуса договора по потреблению.
addInfo01Code STRING Код схемы оплаты.
addInfo01 STRING Значение для отображения схемы оплаты.
addInfo02Code STRING Код региона заключения договора.
addInfo02 STRING Регион заключения договора.
addInfo03 STRING Имя схемы определения статуса по объему потребления.
addInfo03Code STRING Схема определения статуса по объему потребления.
addInfo04Code STRING Дополнительная информация. Возвращаемые данные зависят от типа договора. Возвращаемое значение не подвергается дополнительной обработке.
addInfo04 STRING Дополнительная информация. Возвращаемые данные зависят от типа договора. Возвращаемое значение не подвергается дополнительной обработке.
2.2. getContractCards
Сервис выполняет запрос списка карт по договору. В текущей реализации поддержаны двухуровневая и трехуровневая иерархии контрактов.
При задании в качестве parentId идентификатора «таксопарка» – в ответ будет получена информация по всем его картам и картам всех его «держателей карт».
При задании в качестве parentId идентификатора «держателя карт» – в ответ будет получена информация по всем его картам.
Входящие параметры:
parentId INTEGER Да Идентификатор договора.
dateOpenIn DATE Нет Дата выдачи карты.
Задается в формате «YYYY-MM-DDTHH:MM:SS».
Выгружаются карты, дата выдачи которых больше, чем указанная. Если поле не заполнено, выводятся все карты, дата выдачи которых больше, либо равна “01-01-1990 00:00:00”.
Исходящие параметры:
cardId INTEGER Идентификатор карты.
cardNumber STRING Номер карты.
expirationDate STRING Дата окончания срока действия карты в формате «YYMM».
driverId INTEGER Идентификатор водителя.
status STRING Статус карты.
contractStatusId INTEGER Идентификатор статуса карты.
externalStatusCode STRING Фиксированный код статуса для дополнительных проверок.
Возможные значения кода:
• CC001 – Карта активна
• CC411 - Карта аннулирована/возвращена в ЛИКАРД
• CC412 - Карта аннулирована/утеряна
• CC051 - Карта заблокирована
• CC052 - Карта заблокирована не сотрудником Ликард
CC141 - Карта не активна
activityDate DATE Дата последнего использования.
Выдается в формате «YYYY-MM-DD».
trackingStatus STRING Код расширенного статуса карты.
trackingStatusName STRING Имя расширенного статуса карты.
pinAttemptsCounter INTEGER Количество попыток ввода PIN-кода.
dateOpen DATE Дата выдачи карты.
Выдается в формате «YYYY-MM-DDTHH:MM:SS».
activationDate DATE Дата активации карты.
Выдается в формате «YYYY-MM-DDTHH:MM:SS».
mileage STRING Текущий пробег.
2.3 getContractBalance
Сервис выполняет запрос значений балансов договора/карты.
По умолчанию поддержан следующий перечень балансов:
• VOLUME – потребление топлива за текущий месяц,
• VOLUME_PREV – потребление топлива за предыдущий месяц,
• AVAILABLE – сумма доступных средств.
Входящие параметры:
contractId INTEGER Да Идентификатор договора/карты
Исходящие параметры:
balanceTypeCode STRING Код типа баланса.
Возможные значения:
VOLUME,
VOLUME_PREV,
AVAILABLE.
balanceValue DECIMAL Значение баланса.
balanceCurr STRING Валюта баланса.
2.4 getContractTransactions
Сервис выполняет запрос транзакционного отчета по договору/карте.
Транзакции в ответе выводятся в порядке убывания transDate. Если transDate совпадает, то сортировка ведется по transId в порядке убывания.
Входящие параметры:
contractId INTEGER Да Идентификатор договора/карты.
dateFrom DATE Да Дата, начиная с которой отбираются записи.
Задается в формате
«YYYY-MM-DDTHH:MM:SS».
dateTo DATE Да Дата, заканчивая которой отбираются записи.
Задается в формате
«YYYY-MM-DDTHH:MM:SS».
reportMode STRING Нет Возможные значения - Y/N.
Фильтр регламентирует режим отображения вторичных документов в транзакционном отчете. При установленном значении ‘Y’ отмены/корректировки/репосты отображаются одной записью вместе с оригинальным документом.
cardNumberIn STRING Нет Номер карты для фильтрации ответа.
Допускается перечисление номеров карт через запятую.
Допускается поиск по частичному совпадению, например «%54334» - отфильтруются все карты, с номером, заканчивающимся на 54334.
vehicleNumberIn STRING Нет Номер ТС/ФИО водителя для фильтрации ответа.
Допускается использование % для поиска по части ФИО/номера. Не чувствительно к регистру.
cityIn STRING Нет Название города для фильтрации ответа.
Допускается использование % для поиска по части названия. Не чувствительно к регистру.
transMatterIn STRING Нет Код схемы поставки для фильтрации ответа.
Возможные значения:
A – агентирование,
S – поставка,
E - ошибка.
countryCodeIn STRING Нет Трехзначный код страны. Поле code из ответа сервиса getCountries.
regionIdIn INTEGER Нет Название региона. Поле code из ответа сервиса getRegions.
operationTypeId INTEGER Нет Идентификатор типа операции. Значение transTypeId из ответа сервиса getTransactionsTypes
goodsGroupCodeIn STRING Нет Код товарной группы. Значение code из ответа сервиса getGoodsHandbook
minQuantity INTEGER Нет Минимальный объем (quantity) операции
maxQuantity INTEGER Нет Максимальный объем (quantity) операции
maxRowsThreshold INTEGER Нет Максимальное количество возвращаемых записей. Вернутся первые maxRowsThreshold записей. Дефолтное значение 1000.
Исходящие параметры:
transId INTEGER Идентификатор транзакции.
cardNumberOut STRING Номер карты.
vehicleNumberOut STRING Номер ТС/ФИО водителя.
cityOut STRING Название города.
transMatterOut STRING Код схемы поставки.
Возможные значения:
A - агентирование,
S - поставка,
E - ошибка.
transMatterName STRING Схема поставки (семантическое значение).
Возможные значения:
Агентирование,
Поставка,
Ошибка.
goodsGroupCodeOut STRING Код группы товаров.
goodsName STRING Наименование товара.
transDate DATE Дата и время транзакции на терминале. Выдается в формате
«YYYY-MM-DDTHH:MM:SS».
targetContractMainNum STRING Номер контракта держателя карты.
targetContractMainMainNum STRING Иерархия контрактов держателя карты.
discountAmount DECIMAL Общая скидка для клиента.
requestCategory STRING Вид операции.
Возможные значения:
'Q' – Request (Прямая)
‘P’ – Advice (Прямая)
‘R’– Reversal (Отмена)
'J' – Adjustment (Частичная отмена)
Для сервисных транзакций и возмещения стоимости карт не является значимым
Значение будет выгружаться и для сервисных транзакций, но анализировать его не нужно
requestCategoryName STRING Вид операции (семантическое значение).
Название типа операции RequestCategory. Соответствует значению в RequestCategory:
Q – ‘Запрос’
P – ‘Прямая’
R – ‘Отмена’
J – ‘Возврат’
transType STRING Тип операции
Возможные значения:
Если requestCategory=’Q’ или ‘P’, то trans_type.name с ‘.’ на конце (trans_type.name || '.' ||)
Если requestCategory=’R’, то trans_type.name и ‘Отмена.’ с ‘. ’ между ними (trans_type.name || '. Отмена.' ||)
Если requestCategory=’J’, то trans_type.name и ‘Возврат.’ с ‘. ’ между ними (trans_type.name || '. Возврат.' ||)
quantity INTEGER Количество.
sourceAmount DECIMAL Стоимость товара для ЛИКАРД.
stelaPrice DECIMAL Цена стелы.
fxRate DECIMAL Курс конвертации.
clientCurr STRING Валюта клиента.
clientCurrName STRING Валюта клиента (семантическое значение).
targetPrice DECIMAL Отпускная цена товара в валюте клиента.
targetAmount DECIMAL Отпускная сумма товара клиенту в валюте клиента.
countryCodeOut STRING Код страны АЗС.
transCurr STRING Валюта партнера.
transCurrName STRING Валюта партнера (семантическое значение).
sourceProfit DECIMAL Выгода Ликард в валюте партнера.
partnerName STRING Партнер (поставщик).
region STRING Регион АЗС.
country STRING Страна АЗС.
streetAddress STRING Улица.
measureUnit STRING Единица измерения.
vat DOUBLE НДС в процентах.
stelaAmount DECIMAL Сумма покупки по цене стелы.
isOnline STRING Онлайн признак операции.
outletName STRING Название торговой точки.
discountPcnt DOUBLE Скидка в процентах.
mileage STRING Пробег.
regionIdOut INTEGER Идентификатор региона.
transTypeId INTEGER Идентификатор типа операции.
fxFee DECIMAL Комиссия за конвертацию в валюте клиента.
clientMainName STRING Наименование клиента контракта (держателя карт).
clientMainMainName STRING Наименование клиента головного контракта иерархии.
gasStationId INTEGER Идентификатор АЗС.
dateFrom DATE Дата, начиная с которой отбираются записи.
Выводится в формате.
«YYYY-MM-DDTHH:MM:SS».
dateTo DATE Дата transDate самого позднего документа в ответе.
Выводится в формате
«YYYY-MM-DDTHH:MM:SS».
В случае превышения максимально допустимого порога записей – дата может быть меньше даты dateTo в запросе.
maxRowsThresholdReached true/Boolean
false/Boolean Флаг превышения числа отобранных записей максимально допустимого порога.
3. Сервисы по работе с картами
3.1 getContractIdByNumber
Сервис выполняет запрос идентификатора карты/контракта по номеру.
Входящие параметры:
contractNumber STRING Да Номер карты/контракта.
Исходящие параметры:
contractId INTEGER Идентификатор карты/контракта.
3.2 getCardInfo
Сервис выполняет запрос информации по карте.
В блоках lastTransactions и lastPayments по умолчанию содержатся по 5 последних платежей и транзакций за последний год. Транзакции выводятся в порядке убывания transDate. Если transDate совпадает, то сортировка ведется по transId в порядке убывания. Платежи выводятся в порядке убывания transactionDate. Если transactionDate совпадают, то сортировка ведется по paymentIdt в порядке убывания.
Входящие параметры:
contractId INTEGER Да Идентификатор карты
Исходящие параметры:
cardNumber STRING Номер карты.
expirationDate STRING Окончание срока действия в формате «YYMM».
driverId INTEGER Идентификатор водителя.
driverSurname STRING Фамилия водителя.
driverName STRING Имя водителя.
contractBalance DECIMAL Текущий баланс карты.
volumePrev DECIMAL Расход литров за предыдущий месяц.
volume DECIMAL Расход литров за текущий месяц.
statusId INTEGER Идентификатор статуса карты.
status STRING Имя статуса карты.
externalStatusCode STRING Код дополнительного статуса карты.
activityDate DATE Дата последнего использования.
trackingStatus STRING Код расширенного статуса карты.
trackingStatusName STRING Имя расширенного статуса карты.
pinAttemptsCounter INTEGER Количество попыток ввода PIN-кода.
issueDate DATE Дата выпуска карты.
В качестве значения используется последняя дата, когда у карты менялся статус на «Карта выпущена». Выводится в формате «YYYY-MM-DD».
activationDate DATE В качестве значения используется последняя дата, когда у карты менялся статус на «Карта активна». Выводится в формате «YYYY-MM-DD».
mileage STRING Пробег.
blockDate DATE В качестве значения используется последняя дата, когда у карты менялся статус на «Карта заблокирована» или «Карта заблокирована (не сотрудником ЛИКАРД)». Выводится в формате «YYYY-MM-DD».
lastTransactions Блок - Последние 5 транзакций за год.
lastPayments Блок - Последние 5 платежей за год.
3.3 getCardPayments
Сервис выполняет запрос списка платежей по карте.
Если в запросе не заданы dateFrom и dateTo, то выдается информация по платежам за последние 4 месяца.
Платежи выводятся в порядке убывания transactionDate. Если transactionDate совпадают, то сортировка ведется по paymentIdt в порядке убывания.
Входящие параметры:
contractId INTEGER Да Идентификатор карты.
dateFrom DATE Нет Начальная дата. Задается в формате «YYYY-MM-DD».
dateTo DATE Нет Конечная дата.
Задается в формате «YYYY-MM-DD».
maxRowsThreshold INTEGER Нет Максимальное количество возвращаемых записей. Вернутся первые maxRowsThreshold записей. Дефолтное значение 1000.
contractId INTEGER Идентификатор карты.
paymentId INTEGER Идентификатор платежа.
sourceRegNumber STRING Номер счета.
transactionDate DATE Дата платежа. Выводится в формате
«YYYY-MM-DDTHH:MM:SS».
transactionAmount DECIMAL Сумма.
transactionCurrency STRING Валюта.
transactionDetails STRING Описание.
paymentName STRING Название платежа.
requestCategory STRING Тип платежа.
paymentIdt STRING Номер платежа для отображения.
На примере сервиса getContractTransactions, который формирует отчет по транзакциям, рассмотрим как можно получить эти данные:
&НаСервере
Функция ПолучитьМассивСРезультатомЗапросаНаСайт()
ЗаписьJSON = Новый ЗаписьJSON;
ДатаНачала = НачалоДня(Объект.НачалоПериода);
ДатаКонец = КонецДня(Объект.КонецПериода);
ИдентификаторДоговора = Справочники.ПБ_СлужебныеПеременныеЛукойлWialon.ИдентификаторДоговораЛукойл.Значение; // заранее определил хранение идентификатора договора в справочнике служебныеПеременныеЛукойлWialon
ПутьКФайлуSSLСертификата = Справочники.ПБ_СлужебныеПеременныеЛукойлWialon.ПутьКФайлуSSLСертификата.Значение; // заранее определил хранение пути к SSL сертификату в справочнике служебныеПеременныеЛукойлWialon, файл предоставляется ЛУКОЙЛ
ПарольSSLСертификата = Справочники.ПБ_СлужебныеПеременныеЛукойлWialon.ПарольSSLСертификата.Значение; // заранее определил хранение пароля от SSL сертификата в справочнике служебныеПеременныеЛукойлWialon
// формируем структуру входящих параметров, обязательно должны быть все параметры, если они не нужны оставляем пустыми
СтруктураПараметров = Новый Структура;
СтруктураПараметров.Вставить("contractId", ИдентификаторДоговора);
СтруктураПараметров.Вставить("dateFrom", ДатаНачала);
СтруктураПараметров.Вставить("dateTo", ДатаКонец);
СтруктураПараметров.Вставить("reportMode", "");
СтруктураПараметров.Вставить("cardNumberIn", "");
СтруктураПараметров.Вставить("vehicleNumberIn", "");
СтруктураПараметров.Вставить("cityIn", "");
СтруктураПараметров.Вставить("transMatterIn", "");
СтруктураПараметров.Вставить("countryCodeIn", "");
СтруктураПараметров.Вставить("regionIdIn", "");
СтруктураПараметров.Вставить("operationTypeId", 35271);
СтруктураПараметров.Вставить("goodsGroupCodeIn", "");
СтруктураПараметров.Вставить("minQuantity", "");
СтруктураПараметров.Вставить("maxQuantity", "");
СтруктураПараметров.Вставить("maxRowsThreshold", "");
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, СтруктураПараметров);
ТекстПараметровJSON = ЗаписьJSON.Закрыть();
Сервер = "11.111.11.11"; // сервер
ssl = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаФайл(ПутьКФайлуSSLСертификата, ПарольSSLСертификата));
Попытка
HTTPСоединение = Новый HTTPСоединение(Сервер, 443 ,,,,30, ssl);
Исключение
ЗаписатьСобытиеВЖурналСинхронизации("Ошибка", "Не удалось установить HTTPCоединение.");
КонецПопытки;
Заголовки = Новый Соответствие;
Заголовки.Вставить("Content-Type", "application/json;charset=utf-8");
// здесь используем имя веб сервиса, можно сделать универсальнее, и сделать переменной
HTTPЗапрос = Новый HTTPЗапрос("/solar-bridge-ext/ext/json-services/getContractTransactions", Заголовки);
HTTPЗапрос.УстановитьТелоИзСтроки(ТекстПараметровJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
HTTPОтвет = HTTPСоединение.ОтправитьДляОбработки(HTTPЗапрос);
МассивРезультатЗапроса = Новый Массив;
Попытка
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(HTTPОтвет.ПолучитьТелоКакСтроку());
СтруктураJSON = ПрочитатьJSON(ЧтениеJSON);
ЧтениеJSON.Закрыть();
МассивРезультатЗапроса = СтруктураJSON.getContractTransactionsRs.getContractTransactionsPayload.contractTransactions;
Исключение
флгРезультатЧтенияФайла = Ложь;
ЗаписатьСобытиеВЖурналСинхронизации("Ошибка", "Не удалось прочитать файл-ответ.");
КонецПопытки;
// получили массив с данными, полученными из сервиса
Возврат МассивРезультатЗапроса;
КонецФункции
Всем спасибо, в следующей статье покажу, как на основе полученных данных, сделать автоматическое сопоставление и загрузку документов заправок и сливов на примере конфигурации "Управление автотранспортом".
