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