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

Версия 24.1 от Ярослава Ерина на 2024/12/11 11:26

v 1.0.1

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

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

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

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

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

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

ApiKey

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

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

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

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

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

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

Внешняя система опрашивает "Топаз-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

{
{
// идентификатор станции внутри Топаз "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},
}

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

Информирование "Топаз-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 интегратора:

Статус Accepted
Статус Fueling
Статус Canceled
Статус Completed
Отправка счетчика налива

Данные запросы "Топаз-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" отсылает перед началом пуска колонки

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