Перейти к содержимому

Протокол интеграции систем внешних наливов с Топаз "Web Офис"

Версия 20.3 от Dmitriy на 2024/12/03 12:21
v 1.0.1

Настройка перед интеграцией

Перед началом интеграции, уполномоченный сотрудник компании, предоставляющей услуги внешних наливов (далее Интегратор), передает в ООО "Топаз-сервис" следующую информацию:

  1. Базовый url тестового окружения системы внешнего налива
  2. Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
  3. Базовый url боевого окружения системы внешнего налива
  4. Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
  5. Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"
  6. Иконку системы внешних наливов в формате svg с соотношением сторон 1:1

После получения информации по указанным пунктам, от ООО "Топаз-сервис" будет предоставлен тестовый доступ для настройки интеграции.

Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы внешних наливов в "Топаз-Web Office".

Данный ключ необходимо будет передавать во всех запросах от внешней системы в "Топаз-Web Office" в заголовке (header) externalSystemApikey

ApiKey

Интегратору необходимо для каждого своего клиента (сети АЗС) сформировать и хранить в собственной базе данных уникальный Apikey.
С помощью этого Apikey происходит идентификация клиента (сети АЗС) при обмене между "Топаз-Web Office" и системой Интегратора.

Адрес для отправки запросов

Базовым адресом (baseUrl) для выполнения запросов является  https://topazoffice.ru/ms/external-fueling/integration

Получение списка АЗС и их конфигураций

Внешняя система опрашивает "Топаз-Web Office" для получения списка АЗС и их конфигураций через HTTP запрос на baseUrl с префиксом /station?apikey={apikey }, запрос типа GET , timeout 10 секунд.

В ответ Топаз "Web Офис" дает ответ в формате JSON

...

{
// идентификатор станции АЗС
string Id
// статус станции: true – доступна, false – выключена
bool Enable,
// наименование станции
string Name,
// адрес станции
string Address,
// гео точка на карте
location Location
{
double Lat,
double Lon },
// словарь доступных ТРК
Dictionary Columns {
// номер колонки
(int32) Key:
{
// список доступных типов топлива
"Fuels": [ "a92", "a95", "diesel_premium", ... N ]
}
} ... N
}

Возможные идентификаторы топлива

IDМарка
dieselдизель
diesel_premiumбрендированный дизель
a80бензин марки А80
a92бензин марки А92
a92_premiumбрендированный бензин марки А92
a95бензин марки А95
a95_premiumбрендированный бензин марки А95
a98бензин марки А98
a98_premiumбрендированный бензин марки А98
a100бензин марки А100
a100_premiumбрендированный бензин марки А100
propaneгаз пропан
metanметан

Получение прайс-листа

Внешняя система опрашивает "Топаз-Web Office" для получения прайс-листа HTTP запросом на baseUrl с префиксом /price?apikey={apikey} , запрос типа GET , timeout 10секунд.

В ответ Топаз "Web Офис" дает ответ в формате JSON

{
 {
// идентификатор станции внутри Топаз "Web Офис"
 string StationId,
// идентификатор топлива
 string ProductId,
// цена за 1 литр
 double Price
 },
…. N
}

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

{
{"StationId": "0001", "ProductId": "a92", "Price": 38.66},
{"StationId": "0001", "ProductId": "a95_premium", "Price": 45.21},
{"StationId": "0002", "ProductId": "a92", "Price": 38.98},
}

Обработка заказа

https://wiki.topazelectro.ru/download/attachments/1179735/image2023-1-19_16-21-33.png?version=1&modificationDate=1716374642000&api=v2

Информирование "Топаз-Web Office" о заказе и их статусах осуществляется HTTP запросом на baseUrl с префиксом /order , запрос типа POST , timeout 10 секунд.

Тело запроса содержит JSON вида Order

{
// идентификатор заказа
string Id
// дата и время создания в UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
String DateCreate
// значение заказа
double OrderVolume
// идентификатор станции АЗС
string StationExtendedId
// номер колонки
int ColumnId
// идентификатор топлива
string FuelId
// стоимость 1 литра топлива
double PriceFuel
// сумма заказа
double Sum
// кол-во литров
double Litre
// итого оплачено
double SumPaid
// статус заказа
OrderStatus Status
// дата и время завершения заказа UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
String DateEnd
// идентификатор причины отмены заказа
string ReasonId
// причина отмены
string Reason
// итого сумма литров залито
double LitreCompleted
// итого оплачено по завершению заказа
double SumPaidCompleted
// идентификатор договора
string ContractId
}

Параметр OrderType – тип заказа может принимать следующие значения:

  • Money – заправка на фиксированную сумму
  • Liters – заправка на литры

Параметр Status – статус заказа может принимать следующие значения

  • OrderCreated – заказ создан и полностью оплачен
  • Accepted - АЗС готова начать налив
  • Expired – статус от АЗС не поступил в течение 30 минут
  • Completed – заказа завершен успешно
  • StationCanceled – заказ отменен оператором АЗС или же Топаз "Web Офис"
  • UserCanceled – заказ отменен пользователем

Параметр ContractId – стандартными типами договора, по которому обрабатывается заказ

  • Individual – договор возмездного оказания услуг (физические лица)
  • Corporation - договор купли продажи топлива (юридические лица)

Так же можно указать любые другие типы договора по договоренности между сетью АЗС и внешней системой.

При получении заказа в статусе OrderCreated Топаз "Web Офис" проверяет ряд параметров StationExtendedId – в случае если идентификатор станции не найден в Топаз "Web Офис", то Топаз "Web Офис" дает ответ 400

FuelId + PriceFuel – в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ 402

Передача статусов о заказе

Статус Accepted

Данный статус сообщает внешней системе о том, что заказ принят и обработан в "Топаз-Web Office"

Данный статус "Топаз-Web Office" отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг

В случае если внешняя система дала ответ, отличный от 200 ОК , то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ

baseUrl + /api/order/accept POST

apikey={apikey}&orderId={ordeId}

все параметры являются обязательными

Статус Fueling

Данный статус сообщает внешней системе о том, что "Топаз-Web Office" готов запустить колонку (начать пролив)

Данный статус "Топаз-Web Office" отсылает перед началом пуска колонки

В случае если внешняя система дала ответ, отличный от 200 ОК , то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ

baseUrl + /api/order/fueling POST

apikey={apikey}&orderId={ordeId}

все параметры являются обязательными

Статус Canceled

Данный статус сообщает внешней системе о том, что заказ следует отменить

baseUrl + /api/order/canceled

POST

apikey={apikey}&orderId={ordeId}&reason={reason}

все параметры являются обязательными

reason – текстовая причина отмены

Статус Completed

Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито

В случае если внешняя система дала ответ отличный от 200 ОК , то "Топаз-Web Office" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа 200 ОК

baseUrl + /api/order/completed POST

apikey={apikey}&orderId={ordeId}&litre={litre}&extendedOrderId={extendedOrderId}&

extendedDate={extendedDate}

все параметры являются обязательными

litre – кол-во пролитых литров, указывается как double с разделителем точка extendedOrderId – идентификатор заказа в АСУ сети

extendedDate – дата по которой АСУ строит отчет для сверки, формат dd.MM.yyyy HH:mm:ss

Отправка счетчика налива

В момент процесса налива "Топаз-Web Office" может сообщать внешней системе статус счетчика налива

Для этого с периодичностью от 5 – 10 секунд "Топаз-Web Office" выполняет следующий запрос

baseUrl + /api/order/volume

POST

apikey={apikey}&orderId={ordeId}&litre={litre}

все параметры являются обязательными

litre – кол-во пролитых на момент отправки запроса литров, указывается как double с разделителем точка

Проверка статуса работы станции

Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ baseUrl с префиксом

/ping?apikey={apikey}&stationId={stationId}&columnId={columnId}, stationId – идентификатор станции

columnId – идентификатор ТРК

запрос типа GET , timeout 10 секунд.

Статусы ответов

200 ОК – станция и ТРК готова принять и обработать заказ

400 – станция или ТРК не найдена (не верный идентификатор станции или ТРК) 404 – ТРК занята / ТРК не готова принять заказ

любой ответ не 200 ОК – интерпретируется как на станции нет интернета / станция не доступна