Перейти к содержимому
Версия 29.1 от Ярослава Ерина на 2024/12/11 12:29
Последние авторы
1 {{toc/}}
2
3 v 1.0.1
4
5 == Настройка перед интеграцией ==
6
7
8 Перед началом интеграции, уполномоченный сотрудник компании, предоставляющей услуги внешних наливов (далее Интегратор), передает в ООО "Топаз-сервис" следующую информацию:
9
10 1. Базовый url тестового окружения системы внешнего налива
11 1. Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
12 1. Базовый url боевого окружения системы внешнего налива
13 1. Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
14 1. Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"
15 1. Иконку системы внешних наливов в формате svg с соотношением сторон 1:1
16
17 После получения информации по указанным пунктам, от ООО "Топаз-сервис" будет предоставлен тестовый доступ для настройки интеграции.
18
19 Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы внешних наливов в "Топаз-Web Office".
20
21 (% class="box errormessage" %)
22 (((
23 (% class="wikigeneratedid" id="H41443043D43D44B43943A43B44E44743D43543E43144543E43443843C43E43144343443544243F43544043543443043243044244C43243E43244143544543743043F44043E44143044543E44243243D43544843D43543944143844144243543C44B4322242243E43F430437-WebOffice2243243743043343E43B43E43243A43528header29externalSystemApikey" %)
24 (((
25 **Данный ключ необходимо будет передавать во всех запросах от внешней системы в "Топаз-Web Office" в заголовке (header) externalSystemApikey**
26 )))
27 )))
28
29 == ApiKey ==
30
31 (% class="wikigeneratedid" %)
32 Интегратору необходимо для каждого своего клиента (сети АЗС) сформировать и хранить в собственной базе данных уникальный Apikey.
33 С помощью этого Apikey происходит идентификация клиента (сети АЗС) при обмене между "Топаз-Web Office" и системой Интегратора.
34
35 == Адрес для отправки запросов ==
36
37 Базовым адресом **(baseUrl)** для выполнения запросов является [[https:~~/~~/topazoffice.ru/ms/external-fueling/integration>>https://topazoffice.ru/ms/external-fueling/integration]]
38
39
40 == **Методы API "Топаз-Web Office":** ==
41
42 1. [[**Получение списка АЗС и их конфигураций**>>Получение списка АЗС и их конфигураций]]
43 1. **Получение прайс-листа**
44 1. **Получение и обработка заказа**
45 1. **Проверка статуса работы станции**
46
47 == Получение списка АЗС и их конфигураций ==
48
49 Внешняя система опрашивает "Топаз-Web Office" для получения списка АЗС и их конфигураций **через HTTP **запрос на **baseUrl **с префиксом **/station?apikey={apikey **}, запрос типа **GET **, timeout 10 секунд.
50
51 В ответ Топаз "Web Офис" дает ответ в формате **JSON**
52
53 **...**
54
55 {{code language="javascript" layout="LINENUMBERS"}}
56 {
57 // идентификатор станции АЗС
58 string Id
59 // статус станции: true – доступна, false – выключена
60 bool Enable,
61 // наименование станции
62 string Name,
63 // адрес станции
64 string Address,
65 // гео точка на карте
66 location Location
67 {
68 double Lat,
69 double Lon },
70 // словарь доступных ТРК
71 Dictionary Columns {
72 // номер колонки
73 (int32) Key:
74 {
75 // список доступных типов топлива
76 "Fuels": [ "a92", "a95", "diesel_premium", ... N ]
77 }
78 } ... N
79 }
80 {{/code}}
81
82 **Возможные идентификаторы топлива**
83
84 |ID|Марка
85 |diesel|дизель
86 |diesel_premium|брендированный дизель
87 |a80|бензин марки А80
88 |a92|бензин марки А92
89 |a92_premium|брендированный бензин марки А92
90 |a95|бензин марки А95
91 |a95_premium|брендированный бензин марки А95
92 |a98|бензин марки А98
93 |a98_premium|брендированный бензин марки А98
94 |a100|бензин марки А100
95 |a100_premium|брендированный бензин марки А100
96 |propane|газ пропан
97 |metan|метан
98
99 == Получение прайс-листа ==
100
101 Внешняя система опрашивает "Топаз-Web Office" для получения прайс-листа **HTTP **запросом на **baseUrl **с префиксом **/price?apikey={apikey} **, запрос типа **GET **, timeout 10секунд.
102
103 В ответ Топаз "Web Офис" дает ответ в формате **JSON**{{{}}}
104
105 {{code language="javascript" layout="LINENUMBERS"}}
106 {
107 {
108 // идентификатор станции внутри Топаз "Web Офис"
109 string StationId,
110 // идентификатор топлива
111 string ProductId,
112 // цена за 1 литр
113 double Price
114 },
115 …. N
116 }
117 {{/code}}
118
119
120 **Пример ответа**{{{}}}
121
122 {{code language="javascript"}}
123 {
124 {"StationId": "0001", "ProductId": "a92", "Price": 38.66},
125 {"StationId": "0001", "ProductId": "a95_premium", "Price": 45.21},
126 {"StationId": "0002", "ProductId": "a92", "Price": 38.98},
127 }
128 {{/code}}
129
130 == Получение и обработка заказа ==
131
132 [[image:https://wiki.topazelectro.ru/download/attachments/1179735/image2023-1-19_16-21-33.png?version=1&modificationDate=1716374642000&api=v2]]
133
134 Информирование "Топаз-Web Office" о заказе и их статусах осуществляется **HTTP **запросом на **baseUrl **с префиксом **/order **, запрос типа **POST **, timeout 10 секунд.
135
136
137 **Тело запроса содержит JSON вида Order{{{}}}**
138
139 {{code language="javascript" layout="LINENUMBERS"}}
140 {
141 // Идентификатор заказа
142 String Id
143 // дата и время создания в UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
144 String DateCreate
145 // идентификатор станции АЗС
146 String StationExtendedId
147 // Тип заказа
148 String OrderType
149 // номер стороны (поста)
150 int ColumnId
151 // Идентификатор топлива
152 String FuelId
153 // Стоимость 1 литра топлива
154 double PriceFuel
155 // Сумма заказа
156 double Sum
157 // Размер заказа в литрах
158 double Litre
159 // Итого оплачено
160 double SumPaid
161 // Статус заказа
162 OrderStatus Status
163 // дата и время завершения заказа UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
164 String DateEnd
165 // Идентификатор причины отмены заказа
166 String ReasonId
167 // Причина отмены
168 String Reason
169 // Итого заправлено
170 double LitreCompleted
171 // Итого оплачено по завершению заказа
172 double SumPaidCompleted
173 // Идентификатор договора
174 String ContractId
175 // Способ оплаты
176 String PayType
177 }
178 {{/code}}
179
180 **Обязательными полями при создании нового заказа являются:**
181
182 {{code layout="LINENUMBERS" language="javascript"}}
183 {
184 "Id": "string",
185 "DateCreate": "string",
186 "OrderType": "Money",
187 "StationExtendedId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
188 "ColumnId": 0,
189 "FuelId": "diesel"
190 "PriceFuel": 0,
191 "Sum": 0,
192 "Litre": 0,
193 "Status": "OrderCreated"
194 "ContractId": "string"
195 }
196 {{/code}}
197
198 Параметр **OrderType **– тип заказа может принимать следующие значения:
199
200 * **Money **– заправка на фиксированную сумму
201 * **Liters **– заправка на литры
202
203 Параметр **Status **– статус заказа может принимать следующие значения
204
205 * **OrderCreated **– заказ создан и полностью оплачен
206 * **Accepted **- АЗС готова начать налив
207 * **Expired **– статус от АЗС не поступил в течение 30 минут
208 * **Completed **– заказа завершен успешно
209 * **StationCanceled **– заказ отменен оператором АЗС или же Топаз "Web Офис"
210 * **UserCanceled **– заказ отменен пользователем
211
212 Параметр **ContractId **– стандартными типами договора, по которому обрабатывается заказ
213
214 * **Individual **– договор возмездного оказания услуг (физические лица)
215 * **Corporation **- договор купли продажи топлива (юридические лица)
216
217 Так же можно указать любые другие типы договора по договоренности между сетью АЗС и внешней системой.
218
219 При получении заказа в статусе **OrderCreated **Топаз "Web Офис" проверяет ряд параметров **StationExtendedId **– в случае если идентификатор станции не найден в Топаз "Web Офис", то Топаз "Web Офис" дает ответ **400**
220
221 **FuelId **+ **PriceFuel **– в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ **402.**
222
223
224 == Проверка статуса работы станции ==
225
226 Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ **baseUrl **с префиксом
227
228 **/ping?apikey={apikey}&stationId={stationId}&columnId={columnId},**
229
230 **stationId **– идентификатор станции
231
232 **columnId **– идентификатор стороны ТРК
233
234 запрос типа **GET **, timeout 10 секунд.
235
236 ==== **Статусы ответов** ====
237
238 **200 ОК **– станция и ТРК готова принять и обработать заказ
239
240 **400 **– станция или ТРК не найдена (не верный идентификатор станции или ТРК) **404 **– ТРК занята / ТРК не готова принять заказ
241
242 любой ответ не **200 ОК **– интерпретируется как на станции нет интернета / станция не доступна
243
244 ----
245
246 Для получения статусов Интегратору необходимо со своей стороны реализовать сервис для их получения и обработки.
247
248 == **Методы REST API интегратора (внешней системы):** ==
249
250 1. **Статус Accepted**
251 1. **Статус Fueling**
252 1. **Статус Canceled**
253 1. **Статус Completed**
254 1. **Отправка счетчика налива**
255
256 Данные запросы "Топаз-Web Office" отправляет Интегратору.
257
258 === **Статус Accepted** ===
259
260 Данный статус сообщает внешней системе о том, что заказ принят и обработан в "Топаз-Web Office"
261
262 Данный статус "Топаз-Web Office" отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг
263
264 В случае если внешняя система дала ответ, отличный от **200 ОК **, то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ
265
266 **baseUrl + /api/order/accept**
267
268 **POST**
269
270 **apikey={apikey}&orderId={ordeId}**
271
272 все параметры являются обязательными
273
274 === **Статус Fueling** ===
275
276 Данный статус сообщает внешней системе о том, что "Топаз-Web Office" готов запустить колонку (начать пролив)
277
278 Данный статус "Топаз-Web Office" отсылает перед началом пуска колонки
279
280 В случае если внешняя система дала ответ, отличный от **200 ОК **, то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ
281
282 **baseUrl + /api/order/fueling**
283
284 **POST**
285
286 **apikey={apikey}&orderId={ordeId}**
287
288 все параметры являются обязательными
289
290 === **Статус Canceled** ===
291
292 Данный статус сообщает внешней системе о том, что заказ следует отменить
293
294 **baseUrl + /api/order/canceled**
295
296 **POST**
297
298 **apikey={apikey}&orderId={ordeId}&reason={reason}**
299
300 все параметры являются обязательными
301
302 **reason – **текстовая причина отмены
303
304 === **Статус Completed** ===
305
306 Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито
307
308 В случае если внешняя система дала ответ отличный от **200 ОК **, то "Топаз-Web Office" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа **200 ОК**
309
310 **baseUrl + /api/order/completed POST**
311
312 **apikey={apikey}&orderId={ordeId}&litre={litre}&extendedOrderId={extendedOrderId}&extendedDate={extendedDate}**
313
314 все параметры являются обязательными
315
316 **litre **– кол-во пролитых литров, указывается как **double **с разделителем точка **extendedOrderId **– идентификатор заказа в АСУ сети
317
318 **extendedDate **– дата по которой АСУ строит отчет для сверки, формат **dd.MM.yyyy HH:mm:ss**
319
320 === **Отправка счетчика налива** ===
321
322 В момент процесса налива "Топаз-Web Office" может сообщать внешней системе статус счетчика налива
323
324 Для этого с периодичностью от 5 – 10 секунд "Топаз-Web Office" выполняет следующий запрос
325
326 **baseUrl + /api/order/volume**
327
328 **POST**
329
330 **apikey={apikey}&orderId={ordeId}&litre={litre}**
331
332 все параметры являются обязательными
333
334 **litre **– кол-во пролитых на момент отправки запроса литров, указывается как double с разделителем точка