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

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

Версия 38.1 от Ярослава Ерина на 2025/06/05 07:18

v 1.0.1

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

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

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

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

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

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

ApiKey

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

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

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

Методы API "Топаз-Web Office":

  1. Получение списка АЗС и их конфигураций
  2. Получение прайс-листа
  3. Получение и обработка заказа
  4. Проверка статуса работы станции

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

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

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

...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
// идентификатор станции АЗС
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

1
2
3
4
5
6
7
8
9
10
11
12
13
{
 {
// идентификатор станции внутри Топаз "Web Офис"
 string stationId,
// идентификатор топлива
 string productId,
// цена за 1 литр
 double price
// Внешний код топлива
 string fuelExtendedId
 },
…. N
}

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

{
{"stationId": "0001", "productId": "a92", "price": 38.66, "fuelExtendedId": "92"},
{"stationId": "0001", "productId": "a95_premium", "price": 45.21, "fuelExtendedId": "95"},
{"stationId": "0002", "productId": "a92", "price": 38.98, , "fuelExtendedId": "92"},
}

Получение и обработка заказа

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
// Идентификатор заказа
String Id
// дата и время создания в UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
String DateCreate
// идентификатор станции АЗС
String StationExtendedId
// Тип заказа
String OrderType
// номер стороны (поста)
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
// Способ оплаты
String PayType
}

Обязательными полями при создании нового заказа являются:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
 "Id": "string",
 "DateCreate": "string",
 "OrderType": "Money",
 "StationExtendedId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "ColumnId": 0,
 "FuelId": "diesel"
 "PriceFuel": 0,
 "Sum": 0,
 "Litre": 0,
 "Status": "OrderCreated"
 "ContractId": "string"
}

Параметр 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.

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

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

/ping?apikey={apikey}&stationId={stationId}&columnId={columnId},

stationId – идентификатор станции

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

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

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

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

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

404 – ТРК занята / ТРК не готова принять заказ

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

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

Методы REST API интегратора (внешней системы):

  1. Статус Accepted
  2. Статус Fueling
  3. Статус Canceled
  4. Статус Completed
  5. Отправка счетчика налива

Данные запросы "Топаз-Web Office" отправляет Интегратору.

Статус 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 с разделителем точка