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

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

Редактировал(а) Ярослава Ерина 2026/03/31 07:43
Последние авторы
1 == Описание API для подключения внешнего дисконтного центра ==
2
3 (% class="wikigeneratedid" id="H42143E43443544043643043D438435" %)
4 (((
5 Содержание
6 )))
7
8 {{toc/}}
9
10 === Настройка перед интеграцией ===
11
12 Для начала работы необходимо зарегистрироваться в Личном кабинете Интегратора
13 ~1. Для регистрации пройдите по ссылке: [[https:~~/~~/topazoffice.ru/#/auth/integrator-registration/dc>>https://topazoffice.ru/#/auth/integrator-registration/dc]]
14 2. После ввода логина и пароля на почту будет отправлено письмо для подтверждения регистрации
15 3. Перейдите по ссылке из письма для подтверждения учетной записи.
16 4. Авторизуйтесь в Топаз Web-Office ([[https:~~/~~/topazoffice.ru/#/login>>url:https://topazoffice.ru/#/login]])
17 5. В открывшейся форме заполните поля:
18 •   Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"
19 •   Прикрепите иконку Вашей системы в формате svg с соотношением сторон 1:1. Эти название и иконку будут видеть конечные клиенты в Топаз "Web Офис"
20 •   Базовый url тестового окружения системы внешнего налива
21 •   Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
22 •   Базовый url боевого окружения системы внешнего налива
23 •   Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
24 6. Нажмите на кнопку "Создать", после этого вы получите уникальный API-ключ, он отобразится в соответствующем поле.
25
26 (% class="box errormessage" %)
27 (((
28 Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке: **externalSystemApikey**
29 )))
30
31 == Методы API Топаз "Web Офис" ==
32
33 (% class="box warningmessage" %)
34 (((
35 **Базовый URL для отправки запросов: [[https:~~/~~/topazoffice.ru/ms/discount-service/api/v1/integration>>https://topazoffice.ru/ms/discount-service/api/v1/integration]]**
36 )))
37
38 === Получение списка АЗС ===
39
40 Система интегратора опрашивает ТопазВебОфис для получения списка АЗС и их конфигураций по HTTP.
41
42 (% class="box infomessage" %)
43 (((
44 Запрос
45
46 **GET  /station**
47 параметры:
48 - **apikey** String
49 - **stationId** UUID - не обязательный
50
51
52 Ответы:
53
54 **200**
55
56 {{code language="javascript"}}
57 [
58 {
59 // Id станции
60 "id": "uuid",
61 // Признак, является ли станция активной
62 "enable": true,
63 // Наименование
64 "name": "string",
65 // Адрес станции
66 "address": "string",
67 // Координаты на карте
68 "location": {
69 "lon": 0.00,
70 "lat": 0.00
71 },
72 // Карта топлива, содержит стороны и виды топлива
73 "columns": {
74 // Номер стороны
75 "1": {
76 // Состояние поста. READY - готов принять заказ, BUSY - занят
77 "state": "READY",
78 // Виды топлива
79 "fuels": [
80 "diesel"
81 ]
82 },
83 "2": {
84 "state": "READY",
85 "fuels": [
86 "diesel"
87 ]
88 },
89 "3": {
90 "state": "READY",
91 "fuels": [
92 "diesel"
93 ]
94 }
95 },
96 // Информация о видах топлива, названии и внешних кодах
97 "fuelInfo": [
98 {
99 // Тип топлива. Если значение null, то сопоставление не проводилось
100 "fuelType": "string",
101 // Наименование топлива
102 "name": "string",
103 // Внешний код топлива
104 "extCode": "string"
105 },
106 {
107 "fuelType": "a95",
108 "name": "Аи95",
109 "extCode": "95"
110 }
111 ]
112 }
113 ]
114 {{/code}}
115
116
117 **400 **
118 {
119 "message": String
120 }
121 \\Возможные варианты сообщений:
122 Не найден apikey
123 Не найден stationId
124 Нет подписки
125 Нет коннекта Т-АЗС
126 Т-АЗС не зарегистрирована
127 )))
128
129
130 **Возможные идентификаторы топлива**
131
132 |ID|Марка
133 |diesel|дизель
134 |diesel_premium|брендированный дизель
135 |a80|бензин марки А80
136 |a92|бензин марки А92
137 |a92_premium|брендированный бензин марки А92
138 |a95|бензин марки А95
139 |a95_premium|брендированный бензин марки А95
140 |a98|бензин марки А98
141 |a98_premium|брендированный бензин марки А98
142 |a100|бензин марки А100
143 |a100_premium|брендированный бензин марки А100
144 |propane|газ пропан
145 |metan|метан
146
147 === Проверка доступности АЗС ===
148
149 Система интегратора получает информацию о текущем состоянии АЗС по HTTP
150
151 (% class="box infomessage" %)
152 (((
153 Запрос
154
155 **GET /ping**
156 параметры:
157 - **apikey **String
158 - **stationId **UUID
159
160 - **pumpId** Integer (необязательный)  - Номер стороны
161
162
163 Ответ
164
165 200 - АЗС доступна
166 \\ 400 - в теле указана причина ошибки
167 {
168 "message": String
169 }
170 Возможные варианты сообщений:
171 Не найден apikey
172 Не найден stationId
173 Нет подписки
174 Нет коннекта Т-АЗС
175 Т-АЗС не зарегистрирована
176 )))
177
178 == Методы API Интегратора ==
179
180 === Поиск карты ===
181
182 Топаз "Web Офис" при получении кода карты от АСУ запрашивает у системы интегратора информацию о карте для информирования оператора о данных карты и привязанных схемах.
183
184 (((
185 (% class="box successmessage" %)
186 (((
187 **POST /cards/find**
188
189 |(% style="width:479px" %)**Запрос**|(% style="width:1003px" %)**Ответ**
190 |(% style="width:479px" %)(((
191 параметры:
192 - **apikey **String
193
194
195 {{code language="javascript"}}
196 {
197 // Код карты или Qr-код
198 "cardCode": "string"
199 }
200 {{/code}}
201 )))|(% style="width:1003px" %)(((
202 **200**
203
204
205 {{code language="javascript"}}
206 {
207 // уникальный Id карты в системе интегратора
208 "id": "uuid",
209 // Внешний код
210 "extCode": "string",
211 // Признак активности
212 "enabled": true,
213 // Наименование карты
214 "name": "string",
215 // Уникальный номер карты
216 "code": "string",
217 // Срок действия карты
218 "useUntilDate": "2025-02-13",
219 // Телефон владельца
220 "customerPhone": "string"
221 }
222 {{/code}}
223
224
225 (((
226 **400 - **В теле указана причина ошибки
227 {
228 "message": String
229 }
230 )))
231 )))
232
233
234 )))
235
236 === Получить баланс бонусов по карте ===
237
238 Перед формированием заказа Топаз "Web Офис" запрашивает информацию о доступных бонусах на карте в системе интегратора.
239
240 (% class="box successmessage" %)
241 (((
242 **POST /bonuses/balance**
243
244 |**Запрос**|**Ответ**
245 |(((
246 параметры:
247 - **apikey **String
248
249 тело:
250
251
252 {{code language="javascript"}}
253 {
254 // Код карты или Qr-код
255 "cardCode": "string"
256 }
257 {{/code}}
258 )))|(((
259 **200** - (0.0) Количество бонусов с разделителем точка
260
261 **400 **- в теле указана причина ошибки
262 {
263 "message": String
264 }
265 )))
266 )))
267
268 === Получить полный расчет по заказу (дисконт + бонусы) ===
269
270 (% class="box successmessage" %)
271 (((
272 **POST /orders/calc**
273
274 |(% style="width:714px" %)**Запрос**|(% style="width:768px" %)**Ответ**
275 |(% style="width:714px" %)(((
276 параметры:
277 - **apikey: **String,
278 \\ ~/~/ Код АЗС, с которой поступил запрос
279 - **station: **String
280
281 ~/~/ Id АЗС, с которой поступил запрос
282
283 stationId:** UUID**
284
285 тело:
286
287 {{code language="javascript"}}
288 {
289 // Yникальный Id объекта в системе
290 "id": "uuid",
291 // Карта
292 "card": {
293 // Уникальный номер карты
294 "code": "string"
295 },
296 // Номер заказа
297 "number": "string",
298 // Позиции заказа
299 "rows": [
300 {
301 // Товар
302 "item": {
303 // Уникальный Id объекта в системе
304 "id": "uuid",
305 // Id компании
306 "companyId": "uuid",
307 // Внешний код
308 "extCode": "string",
309 // Наименование
310 "name": "string",
311 // Дочерние элементы (для группы)
312 "childs": [
313 null
314 ],
315 // Признак что это группа
316 "group": true,
317 // Тип товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары)
318 "type": "FUEL"
319 },
320 // Количество
321 "qty": 0,
322 // Цена
323 "price": 0,
324 // Сумма
325 "summ": 0,
326 // Итого будет списано бонусов
327 "totalWriteOffBonus": 0,
328 // Признак полного чека (для топлива)
329 "fullCheck": true
330 }
331 ],
332 // Количество бонусов на списание
333 "bonusesToWriteoff": 0,
334 // Дата создания
335 "createdAt": "2025-02-13T13:04:55.511Z",
336 // Сумма итого по заказу
337 "totalSumm": 0,
338 // Тип заказа (MONEY - на сумму, LITRE - на литры)
339 "orderType": "MONEY",
340 // Часть итоговой суммы заказа, которая будет списана наличными
341 "cashTotalSum": 0,
342 // Округление при расчете на литры
343 "roundingMode": "UP",
344 // Тип списания бонусов. Добавить объем или уменьшить сумму (ADD_LITRE, DISCOUNT_SUMM)
345 "bonusWriteOffMode": "ADD_LITRE",
346 // Расчет только по обычным скидкам (для товаров)
347 "preliminary": true
348 }
349 {{/code}}
350 )))|(% style="width:768px" %)(((
351 **200**
352
353 тело:
354
355 {{code language="javascript"}}
356 {
357 // Id заказа
358 "orderId": "uuid",
359 // Итоговое количество начисленных бонусов по заказу
360 "totalBonus": 0,
361 // Итоговая скидка по заказу
362 "totalDiscount": 0,
363 // Итоговая сумма по заказу
364 "totalSumm": 0,
365 // Позиции заказа
366 "rows": [
367 {
368 "item": {
369 // Уникальный Id объекта в системе
370 "id": "uuid",
371 // Id компании
372 "companyId": "uuid",
373 // Внешний код
374 "extCode": "string",
375 // Наименование
376 "name": "string",
377 // Дочерние элементы (для группы)
378 "childs": [
379 null
380 ],
381 // Признак, что это группа
382 "group": true,
383 // Тип товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары)
384 "type": "FUEL"
385 },
386 // Количество
387 "qty": 0,
388 // Цена
389 "price": 0,
390 // Сумма
391 "summ": 0,
392 // Бонус начисленный по позиции
393 "addedBonuses": 0,
394 // Скидка
395 "discount": 0,
396 // Бонусов списано по позиции
397 "writeOffBonuses": 0
398 }
399 ],
400 // Статус, указывает, допускается ли продажа
401 "ok": true,
402 // Информация по схемам
403 "schemas": [
404 {
405 // Уникальный Id объекта в системе
406 "id": "uuid",
407 // Наименование схемы
408 "name": "string",
409 // Внешний код
410 "extCode": "string",
411 // Товар
412 "item": {
413 // Уникальный Id объекта в системе
414 "id": "uuid",
415 // Id компании
416 "companyId": "uuid",
417 // Внешний код
418 "extCode": "string",
419 // Наименование
420 "name": "string",
421 // Дочерние элементы (для группы)
422 "childs": [
423 null
424 ],
425 // Признак, что это группа
426 "group": true,
427 // Тип товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары)
428 "type": "FUEL"
429 },
430 // Товары
431 "items": [
432 {
433 // Уникальный Id объекта в системе
434 "id": "uuid",
435 // Id компании
436 "companyId": "uuid",
437 // Внешний код
438 "extCode": "string",
439 // Наименование
440 "name": "string",
441 // Дочерние элементы (для группы)
442 "childs": [
443 null
444 ],
445 // Признак что это группа
446 "group": true,
447 // Тип товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары)
448 "type": "FUEL"
449 }
450 ],
451 // Признак активности
452 "enabled": true,
453 // Критерии активности
454 "actCriterias": [
455 {
456 "id": "uuid",
457 "childs": [
458 null
459 ],
460 "type": "string"
461 }
462 ],
463 // Использовать категорию товара для схемы
464 "useItemCategory": true,
465 // Категория товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары)
466 "itemCategory": "FUEL",
467 // Тип оплаты: наличные/карта/любой/СБП (ANY, CASH, CARD, SBP)
468 "paymentType": "ANY",
469 // Тип схемы
470 "type": "DiscountMultiTresholdScheme"
471 }
472 ]
473 }
474 {{/code}}
475
476
477 **404 - **Схема не найдена
478 )))
479 |(% style="width:714px" %) |(% style="width:768px" %)
480 )))
481
482 === Сохранение заказа без расчета по дисконтным схемам. Бонусы будут начислены. ===
483
484 Данный запрос может быть сформирован и отправлен в том случае, если на АЗС отсутствовал интернет на момент завершения. Информация о заказе отправляется при появлении интернета.
485
486 (% class="box successmessage" %)
487 (((
488 **POST /orders/store**(% id="cke_bm_336271S" style="display:none" %) (%%)
489
490 |**Запрос**|**Ответ**
491 |(((
492 параметры:
493 - **apikey **String,
494 \\ ~/~/ Код АЗС, с которой поступил запрос
495 - **station: **String
496
497 ~/~/ Id АЗС, с которой поступил запрос
498
499 stationId:** UUID**
500
501 тело:
502
503 {{code language="javascript"}}
504 {
505 // Yникальный Id объекта в системе
506 "id": "uuid",
507 // Карта
508 "card": {
509 // Yникальный Id карты в системе
510 "id": "uuid",
511 // Внешний код
512 "extCode": "string",
513 // Признак активности
514 "enabled": true,
515 // Наименование карты
516 "name": "string",
517 // Уникальный номер карты
518 "code": "string",
519 // Срок действия карты
520 "useUntilDate": "2025-02-13",
521 // Признак автоматической блокировки
522 "autoBlock": true,
523 // Признак возможности работы оффлайн
524 "offline": true,
525 // Телефон владельца
526 "customerPhone": "string",
527 // Эмиссия карты
528 "emission": {
529 // Уникальный Id эмиссии в системе
530 "id": "uuid",
531 // Внешний код
532 "extCode": "string",
533 // Наименование эмиссии
534 "name": "string",
535 // Признак активности
536 "enabled": true,
537 // Подключенные дисконтные схемы к ЭМИССИИ
538 "dicsountSchemaIds": [
539 "uuid"
540 ],
541 // Подключенные бонусные схемы к ЭМИССИИ
542 "bonusSchemaIds": [
543 "uuid"
544 ]
545 },
546 // Подключенные дисконтные схемы к КАРТЕ
547 "dicsountSchemaIds": [
548 "uuid"
549 ],
550 // Подключенные бонусные схемы к КАРТЕ
551 "bonusSchemaIds": [
552 "uuid"
553 ],
554 // Количество бонусов
555 "balance": 0
556 },
557 // Номер заказа
558 "number": "string",
559 // Позиции заказа
560 "rows": [
561 {
562 // Товар
563 "item": {
564 // Уникальный Id объекта в системе
565 "id": "uuid",
566 // Id компании
567 "companyId": "uuid",
568 // Внешний код
569 "extCode": "string",
570 // Наименование
571 "name": "string",
572 // Дочерние элементы (для группы)
573 "childs": [
574 null
575 ],
576 // Признак что это группа
577 "group": true,
578 // Тип товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары)
579 "type": "FUEL"
580 },
581 // Количество
582 "qty": 0,
583 // Цена
584 "price": 0,
585 // Сумма
586 "summ": 0,
587 // Итого будет начислено бонусов
588 "totalAddBonus": 0,
589 // Итого будет списано бонусов
590 "totalWriteOffBonus": 0,
591 // Признак полного чека (для топлива)
592 "fullCheck": true
593 }
594 ],
595 // Количество бонусов на списание
596 "bonusesToWriteoff": 0,
597 // Дата создания
598 "createdAt": "2025-02-13T13:04:55.511Z",
599 // Сумма итого по заказу
600 "totalSumm": 0,
601 // Тип заказа (MONEY - на сумму, LITRE - на литры)
602 "orderType": "MONEY",
603 // Часть итоговой суммы заказа, которая будет списана наличными
604 "cashTotalSum": 0,
605 // Округление при расчете на литры
606 "roundingMode": "UP",
607 // Тип списания бонусов. Добавить объем или уменьшить сумму (ADD_LITRE, DISCOUNT_SUMM)
608 "bonusWriteOffMode": "ADD_LITRE",
609 // Итого добавлено бонусов за заказ
610 "totalAddBonus": 0,
611 // Купоны
612 "couponIds": [
613 "uuid"
614 ],
615 // Ид внешней системы дисконта
616 "externalSystemId": "uuid",
617 // Расчет только по обычным скидкам (для товаров)
618 "preliminary": true
619 }
620 {{/code}}
621 )))|(((
622
623
624 **200**
625
626 **404 **- схема не найдена
627 )))
628 )))
629
630 === Возврат заказа ===
631
632 (% class="box successmessage" %)
633 (((
634 **POST /orders/refund**
635
636 |**Запрос**|**Ответ**
637 |(((
638 параметры:
639 - **apikey **String,
640 \\ ~/~/ Код АЗС, с которой поступил запрос
641 - **station: **String
642
643 ~/~/ Id АЗС, с которой поступил запрос
644
645 stationId:** UUID**
646
647 тело:
648
649
650 {{code language="javascript"}}
651 {
652 // Yникальный Id объекта в системе
653 "orderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
654 // Товары
655 "items": [
656 {
657 // Внешний код товара
658 "extCode": "string",
659 // Количество
660 "qty": 0
661 }
662 ]
663 }
664 {{/code}}
665 )))|(((
666 **200                                                                                                         **
667 )))
668 )))
669
670 === Закрытие заказа ===
671
672 Закрывает заказ по id расчета, списывает бонусы.
673
674 (% class="box infomessage" %)
675 (((
676 **GET /orders/close/**
677
678 |**Запрос**|**Ответ**
679 |(((
680 параметры:
681 - **apikey **String
682 - **id **String,
683 \\ ~/~/ Код АЗС, с которой поступил запрос
684 - **station: **String
685
686 ~/~/ Id АЗС, с которой поступил запрос
687
688 stationId:** UUID**
689 )))|(((
690 **200 - Ok
691 400 - Заказ пустой
692 404 - Расчет не найден**
693 )))
694 )))
695
696 === Алгоритм действий при выполнении заказа ===
697
698 * Оператор оформляет заказ и считывает QR-код или код карты
699 * АСУ передает полученный код во внешнюю систему и получает информацию о карте и доступных схемах для отображения оператору
700 * Отдельно запрашивается информация о доступных бонусах на карте
701 * АСУ запрашивает полный расчет скидок и бонусов, основанных на перечне товаров
702 * После выполнения заказа направляется запрос на закрытие заказа.
703 * Если на момент закрытия заказа пропал интернет, заказ откладывается в АСУ для отправки позднее. Скидка в таком случае не применяется.
704 * В случае возврата товара отправляется запрос, содержащий внешние коды товаров и их количество. Требуется найти по уникальному идентификатору номер заказа, скорректировать количество и выполнить перерасчет
705 )))