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

1

v 1.0.1

2

3

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

4

5

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

6

7

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

8

9

2. После ввода логина и пароля на почту будет отправлено письмо для подтверждения регистрации

10

11

3. Перейдите по ссылке из письма для подтверждения учетной записи.

12

13

4. Авторизуйтесь в Топаз Web-Office ([[https:~~/~~/topazoffice.ru/#/login>>url:https://topazoffice.ru/#/login]] )

14

15

5. В открывшейся форме заполните поля:

16

17

* Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"

18

* Прикрепите иконку Вашей системы в формате svg с соотношением сторон 1:1. Эти название и иконку будут видеть конечные клиенты в Топаз "Web Офис"

19

* Базовый url тестового окружения системы внешнего налива

20

* Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива

21

* Базовый url боевого окружения системы внешнего налива

22

* Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива

23

24

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

25

26

(% class="box errormessage" %)

27

(((

28

(% class="wikigeneratedid" id="H41443043D43D44B43943A43B44E44743D43543E43144543E43443843C43E43144343443544243F43544043543443043243044244C43243E43244143544543743043F44043E44143044543E44243243D43544843D43543944143844144243543C44B4322242243E43F430437-WebOffice2243243743043343E43B43E43243A43528header29externalSystemApikey" %)

29

(((

30

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

)))

)))

== ApiKey ==

(% class="wikigeneratedid" %)

37

Интегратору необходимо для каждого своего клиента (сети АЗС) сформировать и хранить в собственной базе данных уникальный Apikey.

38

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

39

40

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

41

42

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

----

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

47

48

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

49

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

50

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

51

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

52

53

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

54

55

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

56

57

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

**...**

{

// идентификатор станции АЗС

64

string id

65

// статус станции: true – доступна, false – выключена

66

bool enable,

67

// наименование станции

string name,

// адрес станции

string address,

// гео точка на карте

location location

{

double lat,

double lon },

// словарь доступных ТРК

Dictionary columns {

// номер колонки

(int32) Key:

{

// список доступных типов топлива

82

"fuels": [ "a92", "a95", "diesel_premium", ... N ]

}

} ... N

}

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

89

90

(% border="1" %)

91

|(% style="background-color:#e5e4e2; border-color:black" %)ID|(% style="background-color:#e5e4e2; border-color:black" %)Марка

92

|diesel|дизель

93

|diesel_premium|брендированный дизель

94

|a80|бензин марки А80

95

|a92|бензин марки А92

96

|a92_premium|брендированный бензин марки А92

97

|a95|бензин марки А95

98

|a95_premium|брендированный бензин марки А95

99

|a98|бензин марки А98

100

|a98_premium|брендированный бензин марки А98

101

|a100|бензин марки А100

102

|a100_premium|брендированный бензин марки А100

|propane|газ пропан

|metan|метан

== ==

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

109

110

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

111

112

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

{

{

// идентификатор станции внутри Топаз "Web Офис"

118

string stationId,

119

// идентификатор топлива

string productId,

// цена за 1 литр

double price

// Внешний код топлива

124

string fuelExtendedId

},

…. N

}

**Пример ответа**{{{}}}

{

{"stationId": "0001", "productId": "a92", "price": 38.66, "fuelExtendedId": "92"},

135

{"stationId": "0001", "productId": "a95_premium", "price": 45.21, "fuelExtendedId": "95"},

136

{"stationId": "0002", "productId": "a92", "price": 38.98, , "fuelExtendedId": "92"},

}

== ==

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

143

144

[[image:https://wiki.topazelectro.ru/download/attachments/1179735/image2023-1-19_16-21-33.png?version=1&modificationDate=1716374642000&api=v2||data-xwiki-image-style-border="true"]]

145

146

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

147

148

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

{

// Идентификатор заказа

153

String Id

154

// дата и время создания в 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

155

String DateCreate

156

// идентификатор станции АЗС

157

String StationExtendedId

158

// Идентификатор АЗС в системе Интегратора (Необязательное поле)

String StationId

// Тип заказа

String OrderType

// номер стороны (поста)

163

int ColumnId

164

// Идентификатор топлива

165

String FuelId

166

// Стоимость 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

177

String DateEnd

178

// Идентификатор причины отмены заказа

String ReasonId

// Причина отмены

String Reason

// Итого заправлено

double LitreCompleted

184

// Итого оплачено по завершению заказа

185

double SumPaidCompleted

186

// Идентификатор договора

String ContractId

// Способ оплаты

String PayType

}

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

{

"Id": "string",

"DateCreate": "string",

199

"OrderType": "Money",

200

"StationExtendedId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

"ColumnId": 0,

"FuelId": "diesel"

"PriceFuel": 0,

"Sum": 0,

"Litre": 0,

"Status": "OrderCreated"

207

"ContractId": "string"

}

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

212

213

* **Money **– заправка на фиксированную сумму

214

* **Liters **– заправка на литры

215

216

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

217

218

* **OrderCreated **– заказ создан и полностью оплачен

219

* **Accepted **- АЗС готова начать налив

220

* **Expired **– статус от АЗС не поступил в течение 30 минут

221

* **Completed **– заказа завершен успешно

222

* **StationCanceled **– заказ отменен оператором АЗС или же Топаз "Web Офис"

223

* **UserCanceled **– заказ отменен пользователем

224

225

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

226

227

* **Individual **– договор возмездного оказания услуг (физические лица)

228

* **Corporation **- договор купли продажи топлива (юридические лица)

229

230

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

231

232

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

233

234

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

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

Отмена заказа возможна даже после его старта. Для инициации отмены необходимо отправить тот же заказ со статусом (% style="background-color:#dddddd; font-family:Courier New,Courier,monospace" %)**UserCanceled**(%%). Если на момент получения запроса на отмену процесс налива ещё не начался, заказ будет отменён.

240

241

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

242

243

244

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

245

246

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

247

248

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

249

250

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

251

252

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

253

254

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

255

256

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

257

258

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

259

260

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

261

262

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

263

264

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

----

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

269

270

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

271

272

1. **Статус Accepted**

273

1. **Статус Fueling**

274

1. **Статус Canceled**

275

1. **Статус Completed**

276

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

277

278

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

279

280

=== **Статус Accepted** ===

281

282

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

283

284

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

285

286

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

287

288

**baseUrl + /api/order/accept**

**POST**

**apikey={apikey}&orderId={ordeId}**

293

294

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

=== ===

=== **Статус Fueling** ===

299

300

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

301

302

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

303

304

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

305

306

**baseUrl + /api/order/fueling**

**POST**

**apikey={apikey}&orderId={ordeId}**

311

312

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

=== ===

=== **Статус Canceled** ===

317

318

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

319

320

**baseUrl + /api/order/canceled**

**POST**

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

325

326

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

327

328

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

=== ===

=== **Статус Completed** ===

333

334

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

335

336

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

337

338

**baseUrl + /api/order/completed POST**

339

340

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

341

342

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

343

344

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