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

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

Версия 43.1 от Ярослава Ерина на 2026/02/09 10:34

v 1.0.1

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

1. Для регистрации пройдите по ссылке: https://topazoffice.ru/#/auth/integrator-registration/ef

2. Перейдите по ссылке из письма для подтверждения учетной записи.
3. Авторизуйтесь в Топаз Web-Office (ссылка на авторизаию)
4. В открывшейся форме заполните поля:

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

5. Нажмите на кнопку "Создать", после этого вы получите уникальный API-ключ в соответствующем поле.

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

Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы внешних наливов в "Топаз-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
39
40
{
// Идентификатор заказа
String Id
// дата и время создания в UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z', yyyy-MM-dd'T'HH:mm:ss.SSS'Z', либо yyyy-MM-dd HH:mm:ss
String DateCreate
// идентификатор станции АЗС
String StationExtendedId
// Идентификатор АЗС в системе Интегратора (Необязательное поле)
String StationId
// Тип заказа
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'T'HH:mm:ss.SSS'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.

Отмена заказа

Отмена заказа возможна даже после его старта. Для инициации отмены необходимо отправить тот же заказ со статусом UserCanceled. Если на момент получения запроса на отмену процесс налива ещё не начался, заказ будет отменён.

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

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

Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ 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 с разделителем точка