Перейти к содержимому
Версия 49.1 от Dmitriy на 2026/04/13 12:45
Скрыть последних авторов
Ярослава Ерина 27.1 1 v 1.0.1
2
Ярослава Ерина 1.1 3 == Настройка перед интеграцией ==
4
Ярослава Ерина 45.1 5 Для начала работы необходимо зарегистрироваться в Личном кабинете Интегратора
Ярослава Ерина 1.1 6
Ярослава Ерина 46.1 7 ~1. Для регистрации пройдите по ссылке: [[https:~~/~~/topazoffice.ru/#/auth/integrator-registration/ef>>https://topazoffice.ru/#/auth/integrator-registration/ef]] 
Ярослава Ерина 1.1 8
Ярослава Ерина 45.1 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 Офис"
Ярослава Ерина 43.1 19 * Базовый url тестового окружения системы внешнего налива
20 * Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
21 * Базовый url боевого окружения системы внешнего налива
22 * Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
Ярослава Ерина 1.1 23
Ярослава Ерина 45.1 24 6. Нажмите на кнопку "Создать", после этого вы получите уникальный API-ключ, он отобразится в соответствующем поле.
Ярослава Ерина 43.1 25
Ярослава Ерина 18.1 26 (% class="box errormessage" %)
27 (((
Ярослава Ерина 28.1 28 (% class="wikigeneratedid" id="H41443043D43D44B43943A43B44E44743D43543E43144543E43443843C43E43144343443544243F43544043543443043243044244C43243E43244143544543743043F44043E44143044543E44243243D43544843D43543944143844144243543C44B4322242243E43F430437-WebOffice2243243743043343E43B43E43243A43528header29externalSystemApikey" %)
29 (((
Ярослава Ерина 34.1 30 === **Данный ключ необходимо будет передавать во всех запросах от внешней системы в "Топаз-Web Office" в заголовке (header) externalSystemApikey** ===
Ярослава Ерина 18.1 31 )))
Ярослава Ерина 28.1 32 )))
Ярослава Ерина 18.1 33
Ярослава Ерина 20.1 34 == ApiKey ==
Ярослава Ерина 19.1 35
36 (% class="wikigeneratedid" %)
37 Интегратору необходимо для каждого своего клиента (сети АЗС) сформировать и хранить в собственной базе данных уникальный Apikey.
38 С помощью этого Apikey происходит идентификация клиента (сети АЗС) при обмене между "Топаз-Web Office" и системой Интегратора.
39
Ярослава Ерина 15.1 40 == Адрес для отправки запросов ==
41
Ярослава Ерина 16.1 42 Базовым адресом **(baseUrl)** для выполнения запросов является [[https:~~/~~/topazoffice.ru/ms/external-fueling/integration>>https://topazoffice.ru/ms/external-fueling/integration]]
Ярослава Ерина 15.1 43
Ярослава Ерина 33.1 44 ----
Ярослава Ерина 24.1 45
46 == **Методы API "Топаз-Web Office":** ==
47
Ярослава Ерина 30.1 48 1. **Получение списка АЗС и их конфигураций**
Ярослава Ерина 24.1 49 1. **Получение прайс-листа**
50 1. **Получение и обработка заказа**
51 1. **Проверка статуса работы станции**
52
Ярослава Ерина 1.1 53 == Получение списка АЗС и их конфигураций ==
54
Ярослава Ерина 19.1 55 Внешняя система опрашивает "Топаз-Web Office" для получения списка АЗС и их конфигураций **через HTTP **запрос на **baseUrl **с префиксом **/station?apikey={apikey **}, запрос типа **GET **, timeout 10 секунд.
Ярослава Ерина 1.1 56
57 В ответ Топаз "Web Офис" дает ответ в формате **JSON**
58
59 **...**
60
Dmitriy 22.1 61 {{code language="javascript" layout="LINENUMBERS"}}
Ярослава Ерина 11.1 62 {
Ярослава Ерина 9.2 63 // идентификатор станции АЗС
Dmitriy 37.1 64 string id
Ярослава Ерина 9.2 65 // статус станции: true – доступна, false – выключена
Dmitriy 37.1 66 bool enable,
Ярослава Ерина 9.2 67 // наименование станции
Dmitriy 37.1 68 string name,
Ярослава Ерина 9.2 69 // адрес станции
Dmitriy 37.1 70 string address,
Ярослава Ерина 9.2 71 // гео точка на карте
Dmitriy 37.1 72 location location
Ярослава Ерина 6.1 73 {
Dmitriy 37.1 74 double lat,
75 double lon },
Ярослава Ерина 9.2 76 // словарь доступных ТРК
Dmitriy 37.1 77 Dictionary columns {
Ярослава Ерина 9.2 78 // номер колонки
79 (int32) Key:
80 {
Ярослава Ерина 6.1 81 // список доступных типов топлива
Dmitriy 37.1 82 "fuels": [ "a92", "a95", "diesel_premium", ... N ]
Ярослава Ерина 6.1 83 }
84 } ... N
Ярослава Ерина 11.1 85 }
86 {{/code}}
Ярослава Ерина 1.1 87
88 **Возможные идентификаторы топлива**
89
Ярослава Ерина 35.1 90 (% border="1" %)
Ярослава Ерина 36.1 91 |(% style="background-color:#e5e4e2; border-color:black" %)ID|(% style="background-color:#e5e4e2; border-color:black" %)Марка
Ярослава Ерина 1.1 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
103 |propane|газ пропан
104 |metan|метан
105
Ярослава Ерина 33.1 106 == ==
107
Ярослава Ерина 1.1 108 == Получение прайс-листа ==
109
Ярослава Ерина 19.1 110 Внешняя система опрашивает "Топаз-Web Office" для получения прайс-листа **HTTP **запросом на **baseUrl **с префиксом **/price?apikey={apikey} **, запрос типа **GET **, timeout 10секунд.
Ярослава Ерина 1.1 111
Ярослава Ерина 11.1 112 В ответ Топаз "Web Офис" дает ответ в формате **JSON**{{{}}}
Ярослава Ерина 1.1 113
Dmitriy 22.1 114 {{code language="javascript" layout="LINENUMBERS"}}
Ярослава Ерина 11.1 115 {
116 {
117 // идентификатор станции внутри Топаз "Web Офис"
Dmitriy 36.3 118 string stationId,
Ярослава Ерина 11.1 119 // идентификатор топлива
Dmitriy 36.3 120 string productId,
Ярослава Ерина 11.1 121 // цена за 1 литр
Dmitriy 36.3 122 double price
123 // Внешний код топлива
124 string fuelExtendedId
Ярослава Ерина 11.1 125 },
126 …. N
127 }
128 {{/code}}
Ярослава Ерина 1.1 129
Ярослава Ерина 12.1 130 **Пример ответа**{{{}}}
Ярослава Ерина 1.1 131
Ярослава Ерина 12.1 132 {{code language="javascript"}}
133 {
Dmitriy 37.1 134 {"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"},
Ярослава Ерина 12.1 137 }
138 {{/code}}
Ярослава Ерина 1.1 139
Ярослава Ерина 33.1 140 == ==
141
Ярослава Ерина 24.1 142 == Получение и обработка заказа ==
Ярослава Ерина 1.1 143
Ярослава Ерина 33.1 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"]]
Ярослава Ерина 1.1 145
Ярослава Ерина 19.1 146 Информирование "Топаз-Web Office" о заказе и их статусах осуществляется **HTTP **запросом на **baseUrl **с префиксом **/order **, запрос типа **POST **, timeout 10 секунд.
Ярослава Ерина 1.1 147
Dmitriy 22.1 148 **Тело запроса содержит JSON вида Order{{{}}}**
Ярослава Ерина 1.1 149
Dmitriy 22.1 150 {{code language="javascript" layout="LINENUMBERS"}}
Ярослава Ерина 13.1 151 {
Dmitriy 20.4 152 // Идентификатор заказа
153 String Id
Dmitriy 39.1 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
Dmitriy 20.4 155 String DateCreate
Ярослава Ерина 13.1 156 // идентификатор станции АЗС
Dmitriy 20.4 157 String StationExtendedId
Ярослава Ерина 40.1 158 // Идентификатор АЗС в системе Интегратора (Необязательное поле)
159 String StationId
Dmitriy 20.4 160 // Тип заказа
161 String OrderType
162 // номер стороны (поста)
Ярослава Ерина 13.1 163 int ColumnId
Dmitriy 20.4 164 // Идентификатор топлива
165 String FuelId
166 // Стоимость 1 литра топлива
Ярослава Ерина 13.1 167 double PriceFuel
Dmitriy 20.4 168 // Сумма заказа
Ярослава Ерина 13.1 169 double Sum
Dmitriy 20.4 170 // Размер заказа в литрах
Ярослава Ерина 13.1 171 double Litre
Dmitriy 20.4 172 // Итого оплачено
Ярослава Ерина 13.1 173 double SumPaid
Dmitriy 20.4 174 // Статус заказа
Ярослава Ерина 13.1 175 OrderStatus Status
Dmitriy 39.1 176 // дата и время завершения заказа 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
Ярослава Ерина 13.1 177 String DateEnd
Dmitriy 20.4 178 // Идентификатор причины отмены заказа
179 String ReasonId
180 // Причина отмены
181 String Reason
182 // Итого заправлено
Ярослава Ерина 13.1 183 double LitreCompleted
Dmitriy 20.4 184 // Итого оплачено по завершению заказа
Ярослава Ерина 13.1 185 double SumPaidCompleted
Dmitriy 20.4 186 // Идентификатор договора
187 String ContractId
188 // Способ оплаты
189 String PayType
Ярослава Ерина 13.1 190 }
191 {{/code}}
Ярослава Ерина 1.1 192
Dmitriy 22.1 193 **Обязательными полями при создании нового заказа являются:**
194
195 {{code layout="LINENUMBERS" language="javascript"}}
196 {
197 "Id": "string",
198 "DateCreate": "string",
199 "OrderType": "Money",
200 "StationExtendedId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
201 "ColumnId": 0,
202 "FuelId": "diesel"
203 "PriceFuel": 0,
204 "Sum": 0,
205 "Litre": 0,
206 "Status": "OrderCreated"
207 "ContractId": "string"
208 }
209 {{/code}}
210
Ярослава Ерина 1.1 211 Параметр **OrderType **– тип заказа может принимать следующие значения:
212
Dmitriy 20.3 213 * **Money **– заправка на фиксированную сумму
214 * **Liters **– заправка на литры
Ярослава Ерина 1.1 215
216 Параметр **Status **– статус заказа может принимать следующие значения
217
218 * **OrderCreated **– заказ создан и полностью оплачен
Dmitriy 20.3 219 * **Accepted **- АЗС готова начать налив
220 * **Expired **– статус от АЗС не поступил в течение 30 минут
Ярослава Ерина 1.1 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
Ярослава Ерина 24.1 234 **FuelId **+ **PriceFuel **– в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ **402.**
Ярослава Ерина 1.1 235
236
Ярослава Ерина 41.1 237 == Отмена заказа ==
238
Ярослава Ерина 42.1 239 Отмена заказа возможна даже после его старта. Для инициации отмены необходимо отправить тот же заказ со статусом (% style="background-color:#dddddd; font-family:Courier New,Courier,monospace" %)**UserCanceled**(%%). Если на момент получения запроса на отмену процесс налива ещё не начался, заказ будет отменён.
Ярослава Ерина 41.1 240
241 В случае, если отмена инициирована после начала налива, система остановит процесс пролива и зафиксирует заказ как отменённый. В этом случае в ответе будет указано количество литров, фактически налитых до момента остановки.
242
243
Ярослава Ерина 24.1 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
Ярослава Ерина 35.1 260 **400 **– станция или ТРК не найдена (неверный идентификатор станции или ТРК)
Ярослава Ерина 24.1 261
Ярослава Ерина 35.1 262 **404 **– ТРК занята / ТРК не готова принять заказ
263
Ярослава Ерина 24.1 264 любой ответ не **200 ОК **– интерпретируется как на станции нет интернета / станция не доступна
265
266 ----
267
268 Для получения статусов Интегратору необходимо со своей стороны реализовать сервис для их получения и обработки.
269
Ярослава Ерина 26.1 270 == **Методы REST API интегратора (внешней системы):** ==
Ярослава Ерина 24.1 271
272 1. **Статус Accepted**
273 1. **Статус Fueling**
274 1. **Статус Canceled**
275 1. **Статус Completed**
Dmitriy 49.1 276 1. **Отправка счетчика налива Volume**
Ярослава Ерина 24.1 277
278 Данные запросы "Топаз-Web Office" отправляет Интегратору.
279
Dmitriy 47.1 280 (% class="box infomessage" %)
281 (((
Dmitriy 49.1 282 ##**Все методы, отправляющие статусы заказа (**##**Accepted, Fueling, Canceled, Completed, Volume),## отправляют данные в теле в формате x-www-form-urlencoded##**
Dmitriy 47.1 283 )))
284
Ярослава Ерина 24.1 285 === **Статус Accepted** ===
286
Ярослава Ерина 19.1 287 Данный статус сообщает внешней системе о том, что заказ принят и обработан в "Топаз-Web Office"
Ярослава Ерина 1.1 288
Ярослава Ерина 19.1 289 Данный статус "Топаз-Web Office" отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг
Ярослава Ерина 1.1 290
Ярослава Ерина 19.1 291 В случае если внешняя система дала ответ, отличный от **200 ОК **, то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ
Ярослава Ерина 1.1 292
Dmitriy 23.1 293 **baseUrl + /api/order/accept**
Ярослава Ерина 1.1 294
Dmitriy 23.1 295 **POST**
296
Ярослава Ерина 1.1 297 **apikey={apikey}&orderId={ordeId}**
298
299 все параметры являются обязательными
300
Ярослава Ерина 33.1 301 === ===
302
Ярослава Ерина 24.1 303 === **Статус Fueling** ===
Ярослава Ерина 1.1 304
Ярослава Ерина 19.1 305 Данный статус сообщает внешней системе о том, что "Топаз-Web Office" готов запустить колонку (начать пролив)
Ярослава Ерина 1.1 306
Ярослава Ерина 19.1 307 Данный статус "Топаз-Web Office" отсылает перед началом пуска колонки
Ярослава Ерина 1.1 308
Ярослава Ерина 19.1 309 В случае если внешняя система дала ответ, отличный от **200 ОК **, то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ
Ярослава Ерина 1.1 310
Dmitriy 23.1 311 **baseUrl + /api/order/fueling**
Ярослава Ерина 1.1 312
Dmitriy 23.1 313 **POST**
314
Ярослава Ерина 1.1 315 **apikey={apikey}&orderId={ordeId}**
316
317 все параметры являются обязательными
318
Ярослава Ерина 33.1 319 === ===
320
Ярослава Ерина 24.1 321 === **Статус Canceled** ===
Ярослава Ерина 1.1 322
323 Данный статус сообщает внешней системе о том, что заказ следует отменить
324
Ярослава Ерина 17.1 325 **baseUrl + /api/order/canceled**
Ярослава Ерина 1.1 326
327 **POST**
328
329 **apikey={apikey}&orderId={ordeId}&reason={reason}**
330
331 все параметры являются обязательными
332
333 **reason – **текстовая причина отмены
334
Ярослава Ерина 33.1 335 === ===
336
Ярослава Ерина 24.1 337 === **Статус Completed** ===
Ярослава Ерина 1.1 338
339 Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито
340
Ярослава Ерина 19.1 341 В случае если внешняя система дала ответ отличный от **200 ОК **, то "Топаз-Web Office" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа **200 ОК**
Ярослава Ерина 1.1 342
Ярослава Ерина 17.1 343 **baseUrl + /api/order/completed POST**
Ярослава Ерина 1.1 344
Dmitriy 23.1 345 **apikey={apikey}&orderId={ordeId}&litre={litre}&extendedOrderId={extendedOrderId}&extendedDate={extendedDate}**
Ярослава Ерина 1.1 346
347 все параметры являются обязательными
348
349 **litre **– кол-во пролитых литров, указывается как **double **с разделителем точка **extendedOrderId **– идентификатор заказа в АСУ сети
350
351 **extendedDate **– дата по которой АСУ строит отчет для сверки, формат **dd.MM.yyyy HH:mm:ss**
352
Ярослава Ерина 33.1 353 === ===
354
Ярослава Ерина 24.1 355 === **Отправка счетчика налива** ===
Ярослава Ерина 1.1 356
Ярослава Ерина 19.1 357 В момент процесса налива "Топаз-Web Office" может сообщать внешней системе статус счетчика налива
Ярослава Ерина 1.1 358
Ярослава Ерина 19.1 359 Для этого с периодичностью от 5 – 10 секунд "Топаз-Web Office" выполняет следующий запрос
Ярослава Ерина 1.1 360
Ярослава Ерина 17.1 361 **baseUrl + /api/order/volume**
Ярослава Ерина 1.1 362
363 **POST**
364
365 **apikey={apikey}&orderId={ordeId}&litre={litre}**
366
367 все параметры являются обязательными
368
369 **litre **– кол-во пролитых на момент отправки запроса литров, указывается как double с разделителем точка