Перейти к содержимому
Версия 14.1 от Ярослава Ерина на 2024/07/30 06:44
Скрыть последних авторов
Ярослава Ерина 1.1 1 ====== **v 1.0.1** ======
2
3 == Настройка перед интеграцией ==
4
5
6 Перед началом интеграции, уполномоченный сотрудник компании, предоставляющей услуги внешних наливов, передает в ООО "Топаз-сервис" следующую информацию:
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 Офис". Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке externalSystemApikey
18
19 == Получение списка АЗС и их конфигураций ==
20
21 Внешняя система опрашивает Топаз "Web Офис" для получения списка АЗС и их конфигураций **через HTTP **запрос на **url **с префиксом **/integration/station?apikey={apikey **}, запрос типа **GET **, timeout 10 секунд.
22
23 В ответ Топаз "Web Офис" дает ответ в формате **JSON**
24
25 **...**
26
Ярослава Ерина 11.1 27 {{code language="javascript"}}
28 {
Ярослава Ерина 9.2 29 // идентификатор станции АЗС
30 string Id
31 // статус станции: true – доступна, false – выключена
32 bool Enable,
33 // наименование станции
34 string Name,
35 // адрес станции
36 string Address,
37 // гео точка на карте
38 location Location
Ярослава Ерина 6.1 39 {
Ярослава Ерина 9.2 40 double Lat,
41 double Lon },
42 // словарь доступных ТРК
43 Dictionary Columns {
44 // номер колонки
45 (int32) Key:
46 {
Ярослава Ерина 6.1 47 // список доступных типов топлива
48 "Fuels": [ "a92", "a95", "diesel_premium", ... N ]
49 }
50 } ... N
Ярослава Ерина 11.1 51 }
52 {{/code}}
Ярослава Ерина 1.1 53
54 **Возможные идентификаторы топлива**
55
56 |ID|Марка
57 |diesel|дизель
58 |diesel_premium|брендированный дизель
59 |a80|бензин марки А80
60 |a92|бензин марки А92
61 |a92_premium|брендированный бензин марки А92
62 |a95|бензин марки А95
63 |a95_premium|брендированный бензин марки А95
64 |a98|бензин марки А98
65 |a98_premium|брендированный бензин марки А98
66 |a100|бензин марки А100
67 |a100_premium|брендированный бензин марки А100
68 |propane|газ пропан
69 |metan|метан
70
71 == Получение прайс-листа ==
72
73 Внешняя система опрашивает Топаз "Web Офис" для получения прайс-листа **HTTP **запросом на **url **с префиксом **/integration/price?apikey={apikey} **, запрос типа **GET **, timeout 10секунд.
74
Ярослава Ерина 11.1 75 В ответ Топаз "Web Офис" дает ответ в формате **JSON**{{{}}}
Ярослава Ерина 1.1 76
Ярослава Ерина 11.1 77 {{code language="javascript"}}
78 {
79 {
80 // идентификатор станции внутри Топаз "Web Офис"
81 string StationId,
82 // идентификатор топлива
83 string ProductId,
84 // цена за 1 литр
85 double Price
86 },
87 …. N
88 }
89 {{/code}}
Ярослава Ерина 1.1 90
Ярослава Ерина 7.1 91
92
Ярослава Ерина 12.1 93 **Пример ответа**{{{}}}
Ярослава Ерина 1.1 94
Ярослава Ерина 12.1 95 {{code language="javascript"}}
96 {
97 {“StationId”: “0001”, “ProductId”: “a92”, “Price”: 38.66},
98 {“StationId”: “0001”, “ProductId”: “a95_premium”, “Price”: 45.21},
99 {“StationId”: “0002”, “ProductId”: “a92”, “Price”: 38.98},
100 }
101 {{/code}}
Ярослава Ерина 1.1 102
103 == Обработка заказа ==
104
105 [[image:https://wiki.topazelectro.ru/download/attachments/1179735/image2023-1-19_16-21-33.png?version=1&modificationDate=1716374642000&api=v2]]
106
107 Информирование Топаз "Web Офис" о заказе и их статусах осуществляется **HTTP **запросом на **url **с префиксом **/integration/order **, запрос типа **POST **, timeout 10 секунд.
108
109
Ярослава Ерина 13.1 110 **Тело запроса содержит JSON вида Order**{{{}}}
Ярослава Ерина 1.1 111
Ярослава Ерина 13.1 112 {{code language="none"}}
113 {
114 // идентификатор заказа
115 string Id
116 // дата и время создания в UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
117 String DateCreate
118 // значение заказа
119 double OrderVolume
120 // идентификатор станции АЗС
121 string StationExtendedId
122 // номер колонки
123 int ColumnId
124 // идентификатор топлива
125 string FuelId
126 // стоимость 1 литра топлива
127 double PriceFuel
128 // сумма заказа
129 double Sum
130 // кол-во литров
131 double Litre
132 // итого оплачено
133 double SumPaid
134 // статус заказа
135 OrderStatus Status
136 // дата и время завершения заказа UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
137 String DateEnd
138 // идентификатор причины отмены заказа
139 string ReasonId
140 // причина отмены
141 string Reason
142 // итого сумма литров залито
143 double LitreCompleted
144 // итого оплачено по завершению заказа
145 double SumPaidCompleted
146 // идентификатор договора
147 string ContractId
148 }
149 {{/code}}
Ярослава Ерина 1.1 150
151 Параметр **OrderType **– тип заказа может принимать следующие значения:
152
153 * **Money **– заправка на фиксированную сумму, **OrderVolume **– сумма рублей
154 * **Liters **– заправка на литры, **OrderVolume **– кол-вол литров
155
156 Параметр **Status **– статус заказа может принимать следующие значения
157
158 * **OrderCreated **– заказ создан и полностью оплачен
159 * **Expire **– статус от АЗС не поступил в течение 30 минут
160 * **Completed **– заказа завершен успешно
161 * **StationCanceled **– заказ отменен оператором АЗС или же Топаз "Web Офис"
162 * **UserCanceled **– заказ отменен пользователем
163
164 Параметр **ContractId **– стандартными типами договора, по которому обрабатывается заказ
165
166 * **Individual **– договор возмездного оказания услуг (физические лица)
167 * **Corporation **- договор купли продажи топлива (юридические лица)
168
169 Так же можно указать любые другие типы договора по договоренности между сетью АЗС и внешней системой.
170
171 При получении заказа в статусе **OrderCreated **Топаз "Web Офис" проверяет ряд параметров **StationExtendedId **– в случае если идентификатор станции не найден в Топаз "Web Офис", то Топаз "Web Офис" дает ответ **400**
172
173 **FuelId **+ **PriceFuel **– в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ **402**
174
175 == Передача статусов о заказе ==
176
177 === Статус Accept ===
178
179 Данный статус сообщает внешней системе о том, что заказ принят и обработан в Топаз "Web Офис"
180
181 Данный статус Топаз "Web Офис"отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг
182
183 В случае если внешняя система дала ответ, отличный от **200 ОК **, то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ
184
185 **базовый url + /api/order/accept POST**
186
187 **apikey={apikey}&orderId={ordeId}**
188
189 все параметры являются обязательными
190
191 === Статус Fueling ===
192
193 Данный статус сообщает внешней системе о том, что Топаз "Web Офис" готов запустить колонку (начать пролив)
194
195 Данный статус Топаз "Web Офис" отсылает перед началом пуска колонки
196
197 В случае если внешняя система дала ответ, отличный от **200 ОК **, то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ
198
199 **базовый url + /api/order/fueling POST**
200
201 **apikey={apikey}&orderId={ordeId}**
202
203 все параметры являются обязательными
204
205 === Статус Canceled ===
206
207 Данный статус сообщает внешней системе о том, что заказ следует отменить
208
209 **базовый url + /api/order/canceled**
210
211 **POST**
212
213 **apikey={apikey}&orderId={ordeId}&reason={reason}**
214
215 все параметры являются обязательными
216
217 **reason – **текстовая причина отмены
218
219 === Статус Completed ===
220
221 Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито
222
223 В случае если внешняя система дала ответ отличный от **200 ОК **, то Топаз "Web Офис" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа **200 ОК**
224
225 **базовый url + /api/order/completed POST**
226
227 **apikey={apikey}&orderId={ordeId}&litre={litre}&extendedOrderId={extendedOrderId}&**
228
229 **extendedDate={extendedDate}**
230
231 все параметры являются обязательными
232
233 **litre **– кол-во пролитых литров, указывается как **double **с разделителем точка **extendedOrderId **– идентификатор заказа в АСУ сети
234
235 **extendedDate **– дата по которой АСУ строит отчет для сверки, формат **dd.MM.yyyy HH:mm:ss**
236
237 === Отправка счетчика налива ===
238
239 В момент процесса налива Топаз "Web Офис" может сообщать внешней системе статус счетчика налива
240
241 Для этого с периодичностью от 5 – 10 секунд Топаз "Web Офис" выполняет следующий запрос
242
243 **базовый url + /api/order/volume**
244
245 **POST**
246
247 **apikey={apikey}&orderId={ordeId}&litre={litre}**
248
249 все параметры являются обязательными
250
251 **litre **– кол-во пролитых на момент отправки запроса литров, указывается как double с разделителем точка
252
253 == Проверка статуса работы станции ==
254
255 Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ url с префиксом
256
257 **/integration/ping?apikey={apikey}&stationId={stationId}&columnId={columnId}, stationId **– идентификатор станции
258
259 **columnId **– идентификатор ТРК
260
261 запрос типа **GET **, timeout 10 секунд.
262
263 == Статусы ответов ==
264
265 **200 ОК **– станция и ТРК готова принять и обработать заказ
266
267 **400 **– станция или ТРК не найдена (не верный идентификатор станции или ТРК) **404 **– ТРК занята / ТРК не готова принять заказ
268
269 любой ответ не **200 ОК **– интерпретируется как на станции нет интернета / станция не доступна