Перейти к содержимому

Исходный код вики Интеграция с внешним РЦ

Редактировал(а) Ярослава Ерина 2026/02/09 11:30
Последние авторы
1 == Описание API для подключения внешнего расчетного центра ==
2
3 === Содержание ===
4
5 * [[Настройка перед интеграцией>>doc:||anchor="desc"]]
6 * [[Методы API Топаз "Web Офис">>doc:||anchor="metods_wo"]]
7 * [[Получение списка АЗС>>doc:||anchor="station"]]
8 * [[Проверка доступности АЗС>>doc:||anchor="ping"]]
9 * [[Методы API Интегратора>>doc:||anchor="integrator_methods"]]
10 * [[Проверка наличия идентификатора (топливной карты)>>doc:||anchor="card_info"]]
11 * [[Проверка актуальности заказа и получение идентификатора>>doc:||anchor="start"]]
12 * [[Завершение заказа>>doc:||anchor="finish"]]
13 * [[UML-диаграмма базовых операций>>doc:||anchor="uml"]]
14 * [[Алгоритм действий при выполнении заказа>>doc:||anchor="algoritm"]]
15
16 === {{id name="desc"/}}Настройка перед интеграцией ===
17
18 Для начала работы необходимо зарегистрироваться в Личном кабинете Интегратора
19 ~1. Для регистрации пройдите по ссылке: [[https:~~/~~/topazoffice.ru/#/auth/integrator-registration/sc>>https://topazoffice.ru/#/auth/integrator-registration/sc]]
20 2. После ввода логина и пароля на почту будет отправлено письмо для подтверждения регистрации
21 3. Перейдите по ссылке из письма для подтверждения учетной записи.
22 4. Авторизуйтесь в Топаз Web-Office ([[https:~~/~~/topazoffice.ru/#/login>>https://topazoffice.ru/#/login]])
23 5. В открывшейся форме заполните поля:
24 •   Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"
25 •   Прикрепите иконку Вашей системы в формате svg с соотношением сторон 1:1. Эти название и иконку будут видеть конечные клиенты в Топаз "Web Офис"
26 •   Базовый url тестового окружения системы внешнего налива
27 •   Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
28 •   Базовый url боевого окружения системы внешнего налива
29 •   Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
30 6. Нажмите на кнопку "Создать", после этого вы получите уникальный API-ключ, он отобразится в соответствующем поле.
31
32 (% class="box errormessage" %)
33 (((
34 Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке: **externalSystemApikey**
35 )))
36
37
38 == {{id name="metods_wo"/}}Методы API Топаз "Web Офис" ==
39
40 === {{id name="station"/}}Получение списка АЗС ===
41
42 Система интегратора опрашивает ТопазВебОфис для получения списка АЗС и их конфигураций по HTTP.
43
44
45 (% class="box infomessage" %)
46 (((
47 Запрос
48
49 Заголовок: **externalSystemApikey**
50
51
52 **GET  /station**
53 параметры:
54 - **apikey** String
55 - **stationId** UUID - не обязательный
56
57
58 Ответы:
59
60 **200**
61
62 {{code language="javascript"}}
63 [
64 {
65 // Id станции
66 "id": "uuid",
67 // Признак, является ли станция активной
68 "enable": true,
69 // Наименование
70 "name": "string",
71 // Адрес станции
72 "address": "string",
73 // Координаты на карте
74 "location": {
75 "lon": 0.00,
76 "lat": 0.00
77 },
78 // Карта топлива, содержит стороны и виды топлива
79 "columns": {
80 // Номер стороны
81 "1": {
82 // Виды топлива
83 "fuels": [
84 "diesel"
85 ]
86 },
87 "2": {
88 "fuels": [
89 "diesel"
90 ]
91 },
92 "3": {
93 "fuels": [
94 "diesel"
95 ]
96 }
97 }
98 }
99 ]
100 {{/code}}
101
102
103 **400 **
104 {
105 "message": String
106 }
107 \\Возможные варианты сообщений:
108 Не найден apikey
109 Не найден stationId
110 Нет подписки
111 Нет коннекта Т-АЗС
112 Т-АЗС не зарегистрирована
113 )))
114
115 === {{id name="ping"/}}Проверка доступности АЗС ===
116
117 Система интегратора получает информацию о текущем состоянии АЗС по HTTP
118
119
120 (% class="box infomessage" %)
121 (((
122 Запрос
123 Заголовок: **externalSystemApikey**
124
125 **
126 GET /ping**
127 параметры:
128 - **stationId **UUID
129
130
131 Ответ
132
133 200 - АЗС доступна
134 \\ 400 - в теле указана причина ошибки
135 {
136 "message": String
137 }
138 Возможные варианты сообщений:
139 Не найден stationId
140 Нет подписки
141 Нет коннекта Т-АЗС
142 Т-АЗС не зарегистрирована
143 )))
144
145 === ===
146
147 == {{id name="integrator_methods"/}}Методы API Интегратора ==
148
149 === {{id name="card_info"/}}Проверка наличия идентификатора (топливной карты) ===
150
151 (% class="box infomessage" %)
152 (((
153 (% id="cke_bm_20686S" style="display:none" %) (%%)Запроос
154 \\**POST /card/info**
155 параметры:
156 - **apikey **String
157
158 - **code **String
159
160 Ответ
161 **200**
162
163 {{code language="javascript"}}
164 {
165 // Наименование карты
166     "name": String,
167 // Код карты
168 "code": String,
169 // Активна или неактивна карта
170     "enabled": boolean,
171 }
172 {{/code}}
173
174
175 **400 - **В теле указана причина ошибки
176 {
177 "message": String
178 }
179 )))
180
181
182 === {{id name="start"/}}Проверка актуальности заказа и получение идентификатора ===
183
184 Топаз "Web Офис" при получении заказа от АСУ запрашивает у системы интегратора информацию о заказе для решения о дальнейших действиях.
185
186 (% class="box infomessage" %)
187 (((
188 Запрос
189 \\**POST /order/start**
190 параметры:
191 - **apikey **String
192 Тело:
193
194 {{code language="javascript"}}
195 {
196 // Id топлива в Топаз Web-Офис
197 "fuelExtendedId": "string",
198 // Цена топлива
199 "price": double,
200 // Объем заказа
201 "volume": double,
202 // Время заказа в UTC
203 "orderDateTime": "2025-02-12T11:49:37.584Z",
204 // Код предъявленной карты
205 "cardCode": "string",
206 // Код карты водителя, если имеется
207 "driverCardCode": "string",
208 // QR-код, предъявленный во время заказа
209 "qrCode": "string",
210 // Номер смены на АЗС
211 "sessionNumber": integer
212 }
213 {{/code}}
214
215
216 Ответ
217 **200**
218
219 {{code language="javascript"}}
220 {
221 // Идентификатор заказа в системе интегратора
222     "transactionId": String,
223 // Цена топлива
224 "price": double,
225 // Доступный объем топлива для данного заказа
226     "availableVolume": double,
227 // Разрешен/запрещен отпуск топлива
228     "fuelingAllowed": Boolean,
229 // Причина, если отпуск запрещен
230     "reason": String
231 }
232 {{/code}}
233
234
235 **400 - **В теле указана причина ошибки
236 {
237 "message": String
238 }
239 )))
240
241 === {{id name="finish"/}}Завершение заказа ===
242
243 При завершении налива Топаз "Web Офис" передает информацию о выполненном заказе в систему интегратора.
244
245 Запрос выполняется независимо от причины завершения.
246
247 Возможные причины:
248
249 - успешный налив,
250 - частичный налив,
251 - отмена.
252
253 (% class="box infomessage" %)
254 (((
255 Запрос
256 \\**POST /order/finish**
257 параметры:
258 - **apikey **String
259
260 тело:
261
262 {{code language="javascript"}}
263 {
264 // Номер заказа
265 "orderNumber": integer,
266 // Объем заказа
267 "volume": BigDecimal,
268 // Статус заказа: FACT - фактически налито, CANCEL - отмена
269 "orderState": Enum [FACT, CANCEL],
270 // Идентификатор заказа в системе интегратора
271 "transactionId": String
272 }
273 {{/code}}
274
275
276
277 Ответ
278 200 - Заказ успешно завершен
279 \\ 400 - в теле указана причина ошибки
280 {
281 "message": String
282 }
283 )))
284
285 === ===
286
287 === {{id name="uml"/}}UML-диаграмма базовых операций ===
288
289
290
291 [[image:UML обмен с внешним РЦ.jpg]]
292
293 === ===
294
295 === ===
296
297 === {{id name="algoritm"/}}Алгоритм действий при выполнении заказа ===
298
299
300 * Оператор оформляет заказ и считывает QR-код или код карты
301 * АСУ передает полученный код ([[/order/start>>doc:||anchor="start"]])
302 * Внешняя система по коду валидирует заказ и возвращает данные по нему
303 ** Если в ответе поле fuelingAllowed = false, отпуск топлива запрещен, причина указана в поле reason
304 ** Если ответ 400, отпуск запрещен, причина указана в сообщении
305 ** Если ответ не был получен по таймауту, отпуск запрещен
306 * Данные по заказу передаются в АСУ
307 * АСУ в случае разрешенного отпуска сверяет доступный объем (availableVolume)
308 ** Если доступный объем меньше запрашиваемого, отпуск производится в размере доступного объема
309 * При завершении заказа, АСУ отправляет уведомление ([[/order/finish>>doc:||anchor="finish"]])
310 ** Если заказ отменен, поле orderState = CANCEL
311 ** Если заказ налит, поле orderState = FACT
312 ** В поле volume указывается фактически налитый объем
313 * В ответ на уведомление о завершении заказа внешняя система отправляет 200
314 ** В случае ответа 200 заказ считается завершенным
315 ** В случае ответа 400 информация о завершении позже будет повторно отправлена во внешнюю систему