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

====== **v 1.0.1** ======

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

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

7

8

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

9

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

10

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

11

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

12

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

13

1. Иконку системы внешних наливов в формате svg с соотношением сторон 1:1

14

15

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

16

17

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

18

19

(% class="box errormessage" %)

20

(((

21

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

22

)))

23

24

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

25

26

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

27

28

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

29

30

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

31

32

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

**...**

{

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

39

string Id

40

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

41

bool Enable,

42

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

string Name,

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

string Address,

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

location Location

{

double Lat,

double Lon },

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

Dictionary Columns {

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

(int32) Key:

{

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

57

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

}

} ... N

}

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

|ID|Марка

|diesel|дизель

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

68

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

69

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

70

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

71

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

72

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

73

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

74

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

75

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

76

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

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

|metan|метан

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

81

82

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

83

84

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

{

{

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

90

string StationId,

91

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

string ProductId,

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

double Price

},

…. N

}

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

{

{“StationId”: “0001”, “ProductId”: “a92”, “Price”: 38.66},

107

{“StationId”: “0001”, “ProductId”: “a95_premium”, “Price”: 45.21},

108

{“StationId”: “0002”, “ProductId”: “a92”, “Price”: 38.98},

}

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

113

114

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

115

116

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

117

118

119

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

{

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

124

string Id

125

// дата и время создания в UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss

String DateCreate

// значение заказа

double OrderVolume

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

130

string StationExtendedId

131

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

132

int ColumnId

133

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

134

string FuelId

135

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

146

String DateEnd

147

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

string ReasonId

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

string Reason

// итого сумма литров залито

152

double LitreCompleted

153

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

154

double SumPaidCompleted

155

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

string ContractId

}

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

161

162

* **Money **– заправка на фиксированную сумму, **OrderVolume **– сумма рублей

163

* **Liters **– заправка на литры, **OrderVolume **– кол-вол литров

164

165

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

166

167

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

168

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

169

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

170

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

171

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

172

173

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

174

175

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

176

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

177

178

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

179

180

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

181

182

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

183

184

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

185

186

=== Статус Accept ===

187

188

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

189

190

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

191

192

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

193

194

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

195

196

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

197

198

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

199

200

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

201

202

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

203

204

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

205

206

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

207

208

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

209

210

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

211

212

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

213

214

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

215

216

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

217

218

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

**POST**

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

223

224

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

225

226

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

227

228

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

229

230

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

231

232

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

233

234

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

235

236

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

237

238

**extendedDate={extendedDate}**

239

240

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

241

242

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

243

244

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

245

246

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

247

248

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

249

250

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

251

252

**baseUrl + /api/order/volume**

**POST**

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

257

258

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

259

260

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

261

262

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

263

264

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

265

266

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

267

268

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

269

270

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

271

272

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