Перейти к содержимому
Редактировал(а) Dmitriy 2026/08/28 10:53
От версии 53.1
отредактировано Dmitriy
на 2026/08/28 10:53
Изменить комментарий: К данной версии нет комментариев
К версии 16.1
отредактировано Ярослава Ерина
на 2024/09/18 06:43
Изменить комментарий: К данной версии нет комментариев

Сводка

Подробности

Свойства страницы
Родительский документ
... ... @@ -1,1 +1,1 @@
1 -vneshnie_api.vneshnie_nalivy2.WebHome
1 +Main.WebHome
Автор документа
... ... @@ -1,1 +1,1 @@
1 -XWiki.erin_ds
1 +XWiki.erina_jv
Содержимое
... ... @@ -1,85 +1,55 @@
1 -v 1.0.1
1 +====== **v 1.0.1** ======
2 2  
3 3  == Настройка перед интеграцией ==
4 4  
5 -Для начала работы необходимо зарегистрироваться в Личном кабинете Интегратора
6 6  
7 -~1. Для регистрации пройдите по ссылке: [[https:~~/~~/topazoffice.ru/#/auth/integrator-registration/ef>>https://topazoffice.ru/#/auth/integrator-registration/ef]] 
6 +Перед началом интеграции, уполномоченный сотрудник компании, предоставляющей услуги внешних наливов, передает в ООО "Топаз-сервис" следующую информацию:
8 8  
9 -2. После ввода логина и пароля на почту будет отправлено письмо для подтверждения регистрации
8 +1. Базовый url тестового окружения системы внешнего налива
9 +1. Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
10 +1. Базовый url боевого окружения системы внешнего налива
11 +1. Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
12 +1. Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"
13 +1. Иконку системы внешних наливов в формате svg с соотношением сторон 1:1
10 10  
11 -3. Перейдите по ссылке из письма для подтверждения учетной записи.
15 +После получения информации по указанным пунктам, от ООО "Топаз-сервис" будет предоставлен тестовый доступ для настройки интеграции.
12 12  
13 -4. Авторизуйтесь в Топаз Web-Office ([[https:~~/~~/topazoffice.ru/#/login>>url:https://topazoffice.ru/#/login]] )
17 +Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы внешних наливов в Топаз "Web Офис". Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке externalSystemApikey
14 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** ===
31 -)))
32 -)))
33 -
34 -== ApiKey ==
35 -
36 -(% class="wikigeneratedid" %)
37 -Интегратору необходимо для каждого своего клиента (сети АЗС) сформировать и хранить в собственной базе данных уникальный Apikey.
38 -С помощью этого Apikey происходит идентификация клиента (сети АЗС) при обмене между "Топаз-Web Office" и системой Интегратора.
39 -
40 40  == Адрес для отправки запросов ==
41 41  
42 42  Базовым адресом **(baseUrl)** для выполнения запросов является [[https:~~/~~/topazoffice.ru/ms/external-fueling/integration>>https://topazoffice.ru/ms/external-fueling/integration]]
43 43  
44 -----
45 -
46 -== **Методы API "Топаз-Web Офис":** ==
47 -
48 -1. **Получение списка АЗС и их конфигураций**
49 -1. **Получение прайс-листа**
50 -1. **Получение и обработка заказа**
51 -1. **Проверка статуса работы станции**
52 -
53 53  == Получение списка АЗС и их конфигураций ==
54 54  
55 -Внешняя система опрашивает "Топаз-Web Office" для получения списка АЗС и их конфигураций **через HTTP **запрос на **baseUrl **с префиксом **/station?apikey={apikey **}, запрос типа **GET **, timeout 10 секунд.
25 +Внешняя система опрашивает Топаз "Web Офис" для получения списка АЗС и их конфигураций **через HTTP **запрос на **url **с префиксом **/integration/station?apikey={apikey **}, запрос типа **GET **, timeout 10 секунд.
56 56  
57 57  В ответ Топаз "Web Офис" дает ответ в формате **JSON**
58 58  
59 59  **...**
60 60  
61 -{{code language="javascript" layout="LINENUMBERS"}}
31 +{{code language="javascript"}}
62 62  {
63 63  // идентификатор станции АЗС
64 -string id
34 +string Id
65 65  // статус станции: true – доступна, false – выключена
66 -bool enable,
36 +bool Enable,
67 67  // наименование станции
68 -string name,
38 +string Name,
69 69  // адрес станции
70 -string address,
40 +string Address,
71 71  // гео точка на карте
72 -location location
42 +location Location
73 73  {
74 -double lat,
75 -double lon },
44 +double Lat,
45 +double Lon },
76 76  // словарь доступных ТРК
77 -Dictionary columns {
47 +Dictionary Columns {
78 78  // номер колонки
79 79  (int32) Key:
80 80  {
81 81  // список доступных типов топлива
82 -"fuels": [ "a92", "a95", "diesel_premium", ... N ]
52 +"Fuels": [ "a92", "a95", "diesel_premium", ... N ]
83 83  }
84 84  } ... N
85 85  }
... ... @@ -87,8 +87,7 @@
87 87  
88 88  **Возможные идентификаторы топлива**
89 89  
90 -(% border="1" %)
91 -|(% style="background-color:#e5e4e2; border-color:black" %)ID|(% style="background-color:#e5e4e2; border-color:black" %)Марка
60 +|ID|Марка
92 92  |diesel|дизель
93 93  |diesel_premium|брендированный дизель
94 94  |a80|бензин марки А80
... ... @@ -103,121 +103,95 @@
103 103  |propane|газ пропан
104 104  |metan|метан
105 105  
106 -== ==
107 -
108 108  == Получение прайс-листа ==
109 109  
110 -Внешняя система опрашивает "Топаз-Web Office" для получения прайс-листа **HTTP **запросом на **baseUrl **с префиксом **/price?apikey={apikey} **, запрос типа **GET **, timeout 10секунд.
77 +Внешняя система опрашивает Топаз "Web Офис" для получения прайс-листа **HTTP **запросом на **url **с префиксом **/integration/price?apikey={apikey} **, запрос типа **GET **, timeout 10секунд.
111 111  
112 112  В ответ Топаз "Web Офис" дает ответ в формате **JSON**{{{}}}
113 113  
114 -{{code language="javascript" layout="LINENUMBERS"}}
81 +{{code language="javascript"}}
115 115  {
116 116   {
117 117   // идентификатор станции внутри Топаз "Web Офис"
118 - string stationId,
85 + string StationId,
119 119   // идентификатор топлива
120 - string productId,
87 + string ProductId,
121 121   // цена за 1 литр
122 - double price
123 - // Внешний код топлива
124 - string fuelExtendedId
89 + double Price
125 125   },
126 126  …. N
127 127  }
128 128  {{/code}}
129 129  
95 +
96 +
130 130  **Пример ответа**{{{}}}
131 131  
132 132  {{code language="javascript"}}
133 133  {
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"},
101 +{“StationId”: “0001”, “ProductId”: “a92”, “Price”: 38.66},
102 +{“StationId”: “0001”, “ProductId”: “a95_premium”, “Price”: 45.21},
103 +{“StationId”: “0002”, “ProductId”: “a92”, “Price”: 38.98},
137 137  }
138 138  {{/code}}
139 139  
140 -== ==
107 +== Обработка заказа ==
141 141  
142 -== Получение и обработка заказа ==
109 +[[image:https://wiki.topazelectro.ru/download/attachments/1179735/image2023-1-19_16-21-33.png?version=1&modificationDate=1716374642000&api=v2]]
143 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"]]
111 +Информирование Топаз "Web Офис" о заказе и их статусах осуществляется **HTTP **запросом на **url **с префиксом **/integration/order **, запрос типа **POST **, timeout 10 секунд.
145 145  
146 -Информирование "Топаз-Web Office" о заказе и их статусах осуществляется **HTTP **запросом на **baseUrl **с префиксом **/order **, запрос типа **POST **, timeout 10 секунд.
147 147  
148 -**Тело запроса содержит JSON вида Order{{{}}}**
114 +**Тело запроса содержит JSON вида Order**{{{}}}
149 149  
150 -{{code language="javascript" layout="LINENUMBERS"}}
116 +{{code language="none"}}
151 151  {
152 -// Идентификатор заказа
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
118 +// идентификатор заказа
119 +string Id
120 +// дата и время создания в UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
121 +String DateCreate
122 +// значение заказа
123 +double OrderVolume
156 156  // идентификатор станции АЗС
157 -String StationExtendedId
158 -// Идентификатор АЗС в системе Интегратора (Необязательное поле)
159 -String StationId
160 -// Тип заказа
161 -String OrderType
162 -// номер стороны (поста)
125 +string StationExtendedId
126 +// номер колонки
163 163  int ColumnId
164 -// Идентификатор топлива
165 -String FuelId
166 -// Стоимость 1 литра топлива
128 +// идентификатор топлива
129 +string FuelId
130 +// стоимость 1 литра топлива
167 167  double PriceFuel
168 -// Сумма заказа
132 +// сумма заказа
169 169  double Sum
170 -// Размер заказа в литрах
134 +// кол-во литров
171 171  double Litre
172 -// Итого оплачено
136 +// итого оплачено
173 173  double SumPaid
174 -// Статус заказа
138 +// статус заказа
175 175  OrderStatus Status
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
140 +// дата и время завершения заказа UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
177 177  String DateEnd
178 -// Идентификатор причины отмены заказа
179 -String ReasonId
180 -// Причина отмены
181 -String Reason
182 -// Итого заправлено
142 +// идентификатор причины отмены заказа
143 +string ReasonId
144 +// причина отмены
145 +string Reason
146 +// итого сумма литров залито
183 183  double LitreCompleted
184 -// Итого оплачено по завершению заказа
148 +// итого оплачено по завершению заказа
185 185  double SumPaidCompleted
186 -// Идентификатор договора
187 -String ContractId
188 -// Способ оплаты
189 -String PayType
150 +// идентификатор договора
151 +string ContractId
190 190  }
191 191  {{/code}}
192 192  
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 -
211 211  Параметр **OrderType **– тип заказа может принимать следующие значения:
212 212  
213 -* **Money **– заправка на фиксированную сумму
214 -* **Liters **– заправка на литры
157 +* **Money **– заправка на фиксированную сумму, **OrderVolume **– сумма рублей
158 +* **Liters **– заправка на литры, **OrderVolume **– кол-вол литров
215 215  
216 216  Параметр **Status **– статус заказа может принимать следующие значения
217 217  
218 218  * **OrderCreated **– заказ создан и полностью оплачен
219 -* **Accepted **- АЗС готова начать налив
220 -* **Expired **– статус от АЗС не поступил в течение 30 минут
163 +* **Expire **– статус от АЗС не поступил в течение 30 минут
221 221  * **Completed **– заказа завершен успешно
222 222  * **StationCanceled **– заказ отменен оператором АЗС или же Топаз "Web Офис"
223 223  * **UserCanceled **– заказ отменен пользователем
... ... @@ -231,103 +231,43 @@
231 231  
232 232  При получении заказа в статусе **OrderCreated **Топаз "Web Офис" проверяет ряд параметров **StationExtendedId **– в случае если идентификатор станции не найден в Топаз "Web Офис", то Топаз "Web Офис" дает ответ **400**
233 233  
234 -**FuelId **+ **PriceFuel **– в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ **402.**
177 +**FuelId **+ **PriceFuel **– в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ **402**
235 235  
179 +== Передача статусов о заказе ==
236 236  
237 -== Отмена заказа ==
181 +=== Статус Accept ===
238 238  
239 -Отмена заказа возможна даже после его старта. Для инициации отмены необходимо отправить тот же заказ со статусом (% style="background-color:#dddddd; font-family:Courier New,Courier,monospace" %)**UserCanceled**(%%). Если на момент получения запроса на отмену процесс налива ещё не начался, заказ будет отменён.
183 +Данный статус сообщает внешней системе о том, что заказ принят и обработан в Топаз "Web Офис"
240 240  
185 +Данный статус Топаз "Web Офис"отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг
241 241  
187 +В случае если внешняя система дала ответ, отличный от **200 ОК **, то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ
242 242  
243 -== Проверка статуса работы станции ==
189 +**базовый url + /api/order/accept POST**
244 244  
245 -Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ **baseUrl **с префиксом
246 -
247 -**/ping?apikey={apikey}&stationId={stationId}&columnId={columnId},**
248 -
249 -**stationId **– идентификатор станции
250 -
251 -**columnId **– идентификатор стороны ТРК
252 -
253 -запрос типа **GET **, timeout 10 секунд.
254 -
255 -==== **Статусы ответов** ====
256 -
257 -**200 ОК **– станция и ТРК готова принять и обработать заказ
258 -
259 -**400 **– станция или ТРК не найдена (неверный идентификатор станции или ТРК)
260 -
261 -**404 **– ТРК занята / ТРК не готова принять заказ
262 -
263 -любой ответ не **200 ОК **– интерпретируется как на станции нет интернета / станция не доступна
264 -
265 -----
266 -
267 -Для получения статусов Интегратору необходимо со своей стороны реализовать сервис для их получения и обработки.
268 -
269 -== **Методы REST API интегратора (внешней системы):** ==
270 -
271 -
272 -
273 -=== Получение статусов от Топаз Web-офис ===
274 -
275 -
276 -
277 -1. **Статус Accepted**
278 -1. **Статус Fueling**
279 -1. **Статус Canceled**
280 -1. **Статус Completed**
281 -1. **Отправка счетчика налива Volume**
282 -
283 -Данные запросы "Топаз-Web Office" отправляет Интегратору.
284 -
285 -(% class="box infomessage" %)
286 -(((
287 -##**Все методы, отправляющие статусы заказа (**##**Accepted, Fueling, Canceled, Completed, Volume),## отправляют данные в теле в формате x-www-form-urlencoded##**
288 -)))
289 -
290 -=== **Статус Accepted** ===
291 -
292 -Данный статус сообщает внешней системе о том, что заказ принят и обработан в "Топаз-Web Office"
293 -
294 -Данный статус "Топаз-Web Office" отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг
295 -
296 -В случае если внешняя система дала ответ, отличный от **200 ОК **, то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ
297 -
298 -**baseUrl + /api/order/accept**
299 -
300 -**POST**
301 -
302 302  **apikey={apikey}&orderId={ordeId}**
303 303  
304 304  все параметры являются обязательными
305 305  
306 -=== ===
195 +=== Статус Fueling ===
307 307  
308 -=== **Статус Fueling** ===
197 +Данный статус сообщает внешней системе о том, что Топаз "Web Офис" готов запустить колонку (начать пролив)
309 309  
310 -Данный статус сообщает внешней системе о том, что "Топаз-Web Office" готов запустить колонку (начать пролив)
199 +Данный статус Топаз "Web Офис" отсылает перед началом пуска колонки
311 311  
312 -Данный статус "Топаз-Web Office" отсылает перед началом пуска колонки
201 +В случае если внешняя система дала ответ, отличный от **200 ОК **, то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ
313 313  
314 -В случае если внешняя система дала ответ, отличный от **200 ОК **, то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ
203 +**базовый url + /api/order/fueling POST**
315 315  
316 -**baseUrl + /api/order/fueling**
317 -
318 -**POST**
319 -
320 320  **apikey={apikey}&orderId={ordeId}**
321 321  
322 322  все параметры являются обязательными
323 323  
324 -=== ===
209 +=== Статус Canceled ===
325 325  
326 -=== **Статус Canceled** ===
327 -
328 328  Данный статус сообщает внешней системе о том, что заказ следует отменить
329 329  
330 -**baseUrl + /api/order/canceled**
213 +**базовый url + /api/order/canceled**
331 331  
332 332  **POST**
333 333  
... ... @@ -337,38 +337,32 @@
337 337  
338 338  **reason – **текстовая причина отмены
339 339  
340 -=== ===
223 +=== Статус Completed ===
341 341  
342 -=== **Статус Completed** ===
343 -
344 344  Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито
345 345  
346 -В случае если внешняя система дала ответ отличный от **200 ОК **, то "Топаз-Web Office" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа **200 ОК**
227 +В случае если внешняя система дала ответ отличный от **200 ОК **, то Топаз "Web Офис" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа **200 ОК**
347 347  
348 -**baseUrl + /api/order/completed POST**
229 +**базовый url + /api/order/completed POST**
349 349  
350 -**apikey={apikey}&orderId={ordeId}&litre={litre}&summ={summ}&extendedOrderId={extendedOrderId}&extendedDate={extendedDate}**
231 +**apikey={apikey}&orderId={ordeId}&litre={litre}&extendedOrderId={extendedOrderId}&**
351 351  
233 +**extendedDate={extendedDate}**
234 +
352 352  все параметры являются обязательными
353 353  
354 -**litre **– кол-во пролитых литров, указывается как **double **с разделителем точка,
237 +**litre **– кол-во пролитых литров, указывается как **double **с разделителем точка **extendedOrderId **– идентификатор заказа в АСУ сети
355 355  
356 -**summ **- итоговая сумма заказа,
357 -
358 -**extendedOrderId **– идентификатор заказа в АСУ сети
359 -
360 360  **extendedDate **– дата по которой АСУ строит отчет для сверки, формат **dd.MM.yyyy HH:mm:ss**
361 361  
362 -=== ===
241 +=== Отправка счетчика налива ===
363 363  
364 -=== **Отправка счетчика налива** ===
243 +В момент процесса налива Топаз "Web Офис" может сообщать внешней системе статус счетчика налива
365 365  
366 -В момент процесса налива "Топаз-Web Office" может сообщать внешней системе статус счетчика налива
245 +Для этого с периодичностью от 5 – 10 секунд Топаз "Web Офис" выполняет следующий запрос
367 367  
368 -Для этого с периодичностью от 5 – 10 секунд "Топаз-Web Office" выполняет следующий запрос
247 +**базовый url + /api/order/volume**
369 369  
370 -**baseUrl + /api/order/volume**
371 -
372 372  **POST**
373 373  
374 374  **apikey={apikey}&orderId={ordeId}&litre={litre}**
... ... @@ -377,9 +377,20 @@
377 377  
378 378  **litre **– кол-во пролитых на момент отправки запроса литров, указывается как double с разделителем точка
379 379  
257 +== Проверка статуса работы станции ==
380 380  
381 -=== Отправка статусов в Топаз Web Офис ===
259 +Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ url с префиксом
382 382  
383 -Для согласованности заказов после каждого полученного статуса от Топаз Web Офис необходимо отправить статус в системе Интегратора.
384 -Для этого необходимо повторить запрос **/order, **с измененными полями **OrderStatus, **в соответствии с состоянием заказа в системе Интегратора.
385 -При отправке статуса **Completed **допускается присылать размер реально налитых литров и оплаченных средств **LitreCompleted, SumPaidCompleted**
261 +**/integration/ping?apikey={apikey}&stationId={stationId}&columnId={columnId}, stationId **– идентификатор станции
262 +
263 +**columnId **– идентификатор ТРК
264 +
265 +запрос типа **GET **, timeout 10 секунд.
266 +
267 +== Статусы ответов ==
268 +
269 +**200 ОК **– станция и ТРК готова принять и обработать заказ
270 +
271 +**400 **– станция или ТРК не найдена (не верный идентификатор станции или ТРК) **404 **– ТРК занята / ТРК не готова принять заказ
272 +
273 +любой ответ не **200 ОК **– интерпретируется как на станции нет интернета / станция не доступна