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

Редактировал(а) Ярослава Ерина 2026/02/09 11:30

version	line-number	content
1.1	1	== Описание API для подключения внешнего расчетного центра ==
	2
3.1	3	=== Содержание ===
1.1	4
13.1	5	* [[Настройка перед интеграцией>>doc:\|\|anchor="desc"]]
28.1	6	* [[Методы API Топаз "Web Офис">>doc:\|\|anchor="metods_wo"]]
6.1	7	* [[Получение списка АЗС>>doc:\|\|anchor="station"]]
9.1	8	* [[Проверка доступности АЗС>>doc:\|\|anchor="ping"]]
28.1	9	* [[Методы API Интегратора>>doc:\|\|anchor="integrator_methods"]]
38.1	10	* [[Проверка наличия идентификатора (топливной карты)>>doc:\|\|anchor="card_info"]]
11.1	11	* [[Проверка актуальности заказа и получение идентификатора>>doc:\|\|anchor="start"]]
	12	* [[Завершение заказа>>doc:\|\|anchor="finish"]]
	13	* [[UML-диаграмма базовых операций>>doc:\|\|anchor="uml"]]
	14	* [[Алгоритм действий при выполнении заказа>>doc:\|\|anchor="algoritm"]]
2.1	15
13.1	16	=== {{id name="desc"/}}Настройка перед интеграцией ===
	17
45.1	18	Для начала работы необходимо зарегистрироваться в Личном кабинете Интегратора
46.1	19	~1. Для регистрации пройдите по ссылке: [[https:~~/~~/topazoffice.ru/#/auth/integrator-registration/sc>>https://topazoffice.ru/#/auth/integrator-registration/sc]]
45.1	20	2. После ввода логина и пароля на почту будет отправлено письмо для подтверждения регистрации
	21	3. Перейдите по ссылке из письма для подтверждения учетной записи.
46.1	22	4. Авторизуйтесь в Топаз Web-Office ([[https:~~/~~/topazoffice.ru/#/login>>https://topazoffice.ru/#/login]])
45.1	23	5. В открывшейся форме заполните поля:
	24	• Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"
	25	• Прикрепите иконку Вашей системы в формате svg с соотношением сторон 1:1. Эти название и иконку будут видеть конечные клиенты в Топаз "Web Офис"
	26	• Базовый url тестового окружения системы внешнего налива
	27	• Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
	28	• Базовый url боевого окружения системы внешнего налива
	29	• Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
	30	6. Нажмите на кнопку "Создать", после этого вы получите уникальный API-ключ, он отобразится в соответствующем поле.
13.1	31
29.1	32	(% class="box errormessage" %)
	33	(((
44.1	34	Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке: externalSystemApikey
29.1	35	)))
13.1	36
	37
27.1	38	== {{id name="metods_wo"/}}Методы API Топаз "Web Офис" ==
17.1	39
4.1	40	=== {{id name="station"/}}Получение списка АЗС ===
3.1	41
7.1	42	Система интегратора опрашивает ТопазВебОфис для получения списка АЗС и их конфигураций по HTTP.
	43
	44
8.1	45	(% class="box infomessage" %)
	46	(((
10.1	47	Запрос
	48
30.1	49	Заголовок: externalSystemApikey
	50
	51
9.1	52	GET /station
7.1	53	параметры:
8.1	54	- apikey String
	55	- stationId UUID - не обязательный
10.1	56
	57
21.1	58	Ответы:
10.1	59
21.1	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
2.1	104	{
	105	"message": String
8.1	106	}
	107	\\Возможные варианты сообщений:
2.1	108	Не найден apikey
	109	Не найден stationId
	110	Нет подписки
	111	Нет коннекта Т-АЗС
	112	Т-АЗС не зарегистрирована
8.1	113	)))
2.1	114
9.1	115	=== {{id name="ping"/}}Проверка доступности АЗС ===
2.1	116
9.1	117	Система интегратора получает информацию о текущем состоянии АЗС по HTTP
	118
	119
	120	(% class="box infomessage" %)
	121	(((
10.1	122	Запрос
30.1	123	Заголовок: externalSystemApikey
10.1	124
30.1	125	**
	126	GET /ping**
9.1	127	параметры:
	128	- stationId UUID
10.1	129
	130
9.1	131	Ответ
10.1	132
9.1	133	200 - АЗС доступна
10.1	134	\\ 400 - в теле указана причина ошибки
9.1	135	{
	136	"message": String
	137	}
	138	Возможные варианты сообщений:
	139	Не найден stationId
	140	Нет подписки
	141	Нет коннекта Т-АЗС
	142	Т-АЗС не зарегистрирована
	143	)))
	144
22.1	145	=== ===
17.1	146
27.1	147	== {{id name="integrator_methods"/}}Методы API Интегратора ==
17.1	148
38.1	149	=== {{id name="card_info"/}}Проверка наличия идентификатора (топливной карты) ===
34.1	150
	151	(% class="box infomessage" %)
	152	(((
	153	(% id="cke_bm_20686S" style="display:none" %) (%%)Запроос
36.1	154	\\POST /card/info
34.1	155	параметры:
	156	- apikey String
	157
36.1	158	- code String
34.1	159
	160	Ответ
	161	200
	162
	163	{{code language="javascript"}}
	164	{
36.1	165	// Наименование карты
	166	"name": String,
	167	// Код карты
	168	"code": String,
	169	// Активна или неактивна карта
	170	"enabled": boolean,
34.1	171	}
	172	{{/code}}
	173
35.1	174
34.1	175	400 - В теле указана причина ошибки
	176	{
	177	"message": String
	178	}
	179	)))
	180
	181
10.1	182	=== {{id name="start"/}}Проверка актуальности заказа и получение идентификатора ===
9.1	183
15.1	184	Топаз "Web Офис" при получении заказа от АСУ запрашивает у системы интегратора информацию о заказе для решения о дальнейших действиях.
10.1	185
	186	(% class="box infomessage" %)
	187	(((
	188	Запрос
21.1	189	\\POST /order/start
10.1	190	параметры:
	191	- apikey String
21.1	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	Ответ
22.1	217	200
21.1	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 - В теле указана причина ошибки
10.1	236	{
	237	"message": String
	238	}
	239	)))
	240
	241	=== {{id name="finish"/}}Завершение заказа ===
	242
15.1	243	При завершении налива Топаз "Web Офис" передает информацию о выполненном заказе в систему интегратора.
10.1	244
14.1	245	Запрос выполняется независимо от причины завершения.
10.1	246
14.1	247	Возможные причины:
	248
10.1	249	- успешный налив,
	250	- частичный налив,
	251	- отмена.
	252
	253	(% class="box infomessage" %)
	254	(((
	255	Запрос
	256	\\POST /order/finish
	257	параметры:
	258	- apikey String
21.1	259
23.1	260	тело:
	261
21.1	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
23.1	276
	277	Ответ
10.1	278	200 - Заказ успешно завершен
12.1	279	\\ 400 - в теле указана причина ошибки
10.1	280	{
	281	"message": String
	282	}
	283	)))
	284
40.1	285	=== ===
39.1	286
11.1	287	=== {{id name="uml"/}}UML-диаграмма базовых операций ===
3.1	288
2.1	289
39.1	290
	291	[[image:UML обмен с внешним РЦ.jpg]]
	292
22.1	293	=== ===
3.1	294
41.1	295	=== ===
40.1	296
11.1	297	=== {{id name="algoritm"/}}Алгоритм действий при выполнении заказа ===
2.1	298
	299
	300	* Оператор оформляет заказ и считывает QR-код или код карты
12.1	301	* АСУ передает полученный код ([[/order/start>>doc:\|\|anchor="start"]])
2.1	302	* Внешняя система по коду валидирует заказ и возвращает данные по нему
	303	** Если в ответе поле fuelingAllowed = false, отпуск топлива запрещен, причина указана в поле reason
	304	** Если ответ 400, отпуск запрещен, причина указана в сообщении
	305	** Если ответ не был получен по таймауту, отпуск запрещен
	306	* Данные по заказу передаются в АСУ
12.1	307	* АСУ в случае разрешенного отпуска сверяет доступный объем (availableVolume)
2.1	308	** Если доступный объем меньше запрашиваемого, отпуск производится в размере доступного объема
12.1	309	* При завершении заказа, АСУ отправляет уведомление ([[/order/finish>>doc:\|\|anchor="finish"]])
2.1	310	** Если заказ отменен, поле orderState = CANCEL
	311	** Если заказ налит, поле orderState = FACT
	312	** В поле volume указывается фактически налитый объем
	313	* В ответ на уведомление о завершении заказа внешняя система отправляет 200
	314	** В случае ответа 200 заказ считается завершенным
	315	** В случае ответа 400 информация о завершении позже будет повторно отправлена во внешнюю систему