Протокол интеграции систем внешних наливов с Топаз "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 Office".

18

19

(% class="box errormessage" %)

20

(((

21

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

)))

== ApiKey ==

(% class="wikigeneratedid" %)

27

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

28

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

29

30

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

31

32

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

33

34

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

35

36

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

37

38

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

**...**

{

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

45

string Id

46

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

47

bool Enable,

48

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

string Name,

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

string Address,

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

location Location

{

double Lat,

double Lon },

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

Dictionary Columns {

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

(int32) Key:

{

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

63

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

}

} ... N

}

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

|ID|Марка

|diesel|дизель

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

74

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

75

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

76

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

77

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

78

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

79

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

80

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

81

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

82

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

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

|metan|метан

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

87

88

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

89

90

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

{

{

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

96

string StationId,

97

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

string ProductId,

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

double Price

},

…. N

}

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

{

{"StationId": "0001", "ProductId": "a92", "Price": 38.66},

113

{"StationId": "0001", "ProductId": "a95_premium", "Price": 45.21},

114

{"StationId": "0002", "ProductId": "a92", "Price": 38.98},

}

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

119

120

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

121

122

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

123

124

125

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

{

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

130

string Id

131

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

String DateCreate

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

double OrderVolume

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

136

string StationExtendedId

137

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

138

int ColumnId

139

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

140

string FuelId

141

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

152

String DateEnd

153

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

string ReasonId

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

string Reason

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

158

double LitreCompleted

159

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

160

double SumPaidCompleted

161

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

string ContractId

}

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

167

168

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

169

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

170

171

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

172

173

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

174

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

175

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

176

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

177

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

178

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

179

180

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

181

182

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

183

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

184

185

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

186

187

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

188

189

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

190

191

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

192

193

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

194

195

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

196

197

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

198

199

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

200

201

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

202

203

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

204

205

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

206

207

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

208

209

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

210

211

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

212

213

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

214

215

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

216

217

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

218

219

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

220

221

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

222

223

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

224

225

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

**POST**

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

230

231

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

232

233

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

234

235

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

236

237

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

238

239

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

240

241

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

242

243

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

244

245

**extendedDate={extendedDate}**

246

247

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

248

249

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

250

251

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

252

253

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

254

255

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

256

257

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

258

259

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

**POST**

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

264

265

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

266

267

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

268

269

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

270

271

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

272

273

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

274

275

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

276

277

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

278

279

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