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