Исходный код вики Протокол интеграции систем внешних наливов с Топаз "Web Офис"

Редактировал(а) Dmitriy 2026/04/23 06:18

version	line-number	content
27.1	1	v 1.0.1
	2
1.1	3	== Настройка перед интеграцией ==
	4
45.1	5	Для начала работы необходимо зарегистрироваться в Личном кабинете Интегратора
1.1	6
46.1	7	~1. Для регистрации пройдите по ссылке: [[https:~~/~~/topazoffice.ru/#/auth/integrator-registration/ef>>https://topazoffice.ru/#/auth/integrator-registration/ef]]
1.1	8
45.1	9	2. После ввода логина и пароля на почту будет отправлено письмо для подтверждения регистрации
	10
	11	3. Перейдите по ссылке из письма для подтверждения учетной записи.
	12
	13	4. Авторизуйтесь в Топаз Web-Office ([[https:~~/~~/topazoffice.ru/#/login>>url:https://topazoffice.ru/#/login]] )
	14
	15	5. В открывшейся форме заполните поля:
	16
	17	* Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"
	18	* Прикрепите иконку Вашей системы в формате svg с соотношением сторон 1:1. Эти название и иконку будут видеть конечные клиенты в Топаз "Web Офис"
43.1	19	* Базовый url тестового окружения системы внешнего налива
	20	* Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
	21	* Базовый url боевого окружения системы внешнего налива
	22	* Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
1.1	23
45.1	24	6. Нажмите на кнопку "Создать", после этого вы получите уникальный API-ключ, он отобразится в соответствующем поле.
43.1	25
18.1	26	(% class="box errormessage" %)
	27	(((
28.1	28	(% class="wikigeneratedid" id="H41443043D43D44B43943A43B44E44743D43543E43144543E43443843C43E43144343443544243F43544043543443043243044244C43243E43244143544543743043F44043E44143044543E44243243D43544843D43543944143844144243543C44B4322242243E43F430437-WebOffice2243243743043343E43B43E43243A43528header29externalSystemApikey" %)
	29	(((
34.1	30	=== Данный ключ необходимо будет передавать во всех запросах от внешней системы в "Топаз-Web Office" в заголовке (header) externalSystemApikey ===
18.1	31	)))
28.1	32	)))
18.1	33
20.1	34	== ApiKey ==
19.1	35
	36	(% class="wikigeneratedid" %)
	37	Интегратору необходимо для каждого своего клиента (сети АЗС) сформировать и хранить в собственной базе данных уникальный Apikey.
	38	С помощью этого Apikey происходит идентификация клиента (сети АЗС) при обмене между "Топаз-Web Office" и системой Интегратора.
	39
15.1	40	== Адрес для отправки запросов ==
	41
16.1	42	Базовым адресом (baseUrl) для выполнения запросов является [[https:~~/~~/topazoffice.ru/ms/external-fueling/integration>>https://topazoffice.ru/ms/external-fueling/integration]]
15.1	43
33.1	44	----
24.1	45
51.1	46	== Методы API "Топаз-Web Офис": ==
24.1	47
30.1	48	1. Получение списка АЗС и их конфигураций
24.1	49	1. Получение прайс-листа
	50	1. Получение и обработка заказа
	51	1. Проверка статуса работы станции
	52
1.1	53	== Получение списка АЗС и их конфигураций ==
	54
19.1	55	Внешняя система опрашивает "Топаз-Web Office" для получения списка АЗС и их конфигураций через HTTP запрос на baseUrl с префиксом /station?apikey={apikey }, запрос типа GET , timeout 10 секунд.
1.1	56
	57	В ответ Топаз "Web Офис" дает ответ в формате JSON
	58
	59	...
	60
22.1	61	{{code language="javascript" layout="LINENUMBERS"}}
11.1	62	{
9.2	63	// идентификатор станции АЗС
37.1	64	string id
9.2	65	// статус станции: true – доступна, false – выключена
37.1	66	bool enable,
9.2	67	// наименование станции
37.1	68	string name,
9.2	69	// адрес станции
37.1	70	string address,
9.2	71	// гео точка на карте
37.1	72	location location
6.1	73	{
37.1	74	double lat,
	75	double lon },
9.2	76	// словарь доступных ТРК
37.1	77	Dictionary columns {
9.2	78	// номер колонки
	79	(int32) Key:
	80	{
6.1	81	// список доступных типов топлива
37.1	82	"fuels": [ "a92", "a95", "diesel_premium", ... N ]
6.1	83	}
	84	} ... N
11.1	85	}
	86	{{/code}}
1.1	87
	88	Возможные идентификаторы топлива
	89
35.1	90	(% border="1" %)
36.1	91	\|(% style="background-color:#e5e4e2; border-color:black" %)ID\|(% style="background-color:#e5e4e2; border-color:black" %)Марка
1.1	92	\|diesel\|дизель
	93	\|diesel_premium\|брендированный дизель
	94	\|a80\|бензин марки А80
	95	\|a92\|бензин марки А92
	96	\|a92_premium\|брендированный бензин марки А92
	97	\|a95\|бензин марки А95
	98	\|a95_premium\|брендированный бензин марки А95
	99	\|a98\|бензин марки А98
	100	\|a98_premium\|брендированный бензин марки А98
	101	\|a100\|бензин марки А100
	102	\|a100_premium\|брендированный бензин марки А100
	103	\|propane\|газ пропан
	104	\|metan\|метан
	105
33.1	106	== ==
	107
1.1	108	== Получение прайс-листа ==
	109
19.1	110	Внешняя система опрашивает "Топаз-Web Office" для получения прайс-листа HTTP запросом на baseUrl с префиксом /price?apikey={apikey} , запрос типа GET , timeout 10секунд.
1.1	111
11.1	112	В ответ Топаз "Web Офис" дает ответ в формате JSON{{{}}}
1.1	113
22.1	114	{{code language="javascript" layout="LINENUMBERS"}}
11.1	115	{
	116	{
	117	// идентификатор станции внутри Топаз "Web Офис"
36.3	118	string stationId,
11.1	119	// идентификатор топлива
36.3	120	string productId,
11.1	121	// цена за 1 литр
36.3	122	double price
	123	// Внешний код топлива
	124	string fuelExtendedId
11.1	125	},
	126	…. N
	127	}
	128	{{/code}}
1.1	129
12.1	130	Пример ответа{{{}}}
1.1	131
12.1	132	{{code language="javascript"}}
	133	{
37.1	134	{"stationId": "0001", "productId": "a92", "price": 38.66, "fuelExtendedId": "92"},
	135	{"stationId": "0001", "productId": "a95_premium", "price": 45.21, "fuelExtendedId": "95"},
	136	{"stationId": "0002", "productId": "a92", "price": 38.98, , "fuelExtendedId": "92"},
12.1	137	}
	138	{{/code}}
1.1	139
33.1	140	== ==
	141
24.1	142	== Получение и обработка заказа ==
1.1	143
33.1	144	[[image:https://wiki.topazelectro.ru/download/attachments/1179735/image2023-1-19_16-21-33.png?version=1&modificationDate=1716374642000&api=v2\|\|data-xwiki-image-style-border="true"]]
1.1	145
19.1	146	Информирование "Топаз-Web Office" о заказе и их статусах осуществляется HTTP запросом на baseUrl с префиксом /order , запрос типа POST , timeout 10 секунд.
1.1	147
22.1	148	Тело запроса содержит JSON вида Order{{{}}}
1.1	149
22.1	150	{{code language="javascript" layout="LINENUMBERS"}}
13.1	151	{
20.4	152	// Идентификатор заказа
	153	String Id
39.1	154	// дата и время создания в UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z', yyyy-MM-dd'T'HH:mm:ss.SSS'Z', либо yyyy-MM-dd HH:mm:ss
20.4	155	String DateCreate
13.1	156	// идентификатор станции АЗС
20.4	157	String StationExtendedId
40.1	158	// Идентификатор АЗС в системе Интегратора (Необязательное поле)
	159	String StationId
20.4	160	// Тип заказа
	161	String OrderType
	162	// номер стороны (поста)
13.1	163	int ColumnId
20.4	164	// Идентификатор топлива
	165	String FuelId
	166	// Стоимость 1 литра топлива
13.1	167	double PriceFuel
20.4	168	// Сумма заказа
13.1	169	double Sum
20.4	170	// Размер заказа в литрах
13.1	171	double Litre
20.4	172	// Итого оплачено
13.1	173	double SumPaid
20.4	174	// Статус заказа
13.1	175	OrderStatus Status
39.1	176	// дата и время завершения заказа UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z', yyyy-MM-dd'T'HH:mm:ss.SSS'Z', либо yyyy-MM-dd HH:mm:ss
13.1	177	String DateEnd
20.4	178	// Идентификатор причины отмены заказа
	179	String ReasonId
	180	// Причина отмены
	181	String Reason
	182	// Итого заправлено
13.1	183	double LitreCompleted
20.4	184	// Итого оплачено по завершению заказа
13.1	185	double SumPaidCompleted
20.4	186	// Идентификатор договора
	187	String ContractId
	188	// Способ оплаты
	189	String PayType
13.1	190	}
	191	{{/code}}
1.1	192
22.1	193	Обязательными полями при создании нового заказа являются:
	194
	195	{{code layout="LINENUMBERS" language="javascript"}}
	196	{
	197	"Id": "string",
	198	"DateCreate": "string",
	199	"OrderType": "Money",
	200	"StationExtendedId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	201	"ColumnId": 0,
	202	"FuelId": "diesel"
	203	"PriceFuel": 0,
	204	"Sum": 0,
	205	"Litre": 0,
	206	"Status": "OrderCreated"
	207	"ContractId": "string"
	208	}
	209	{{/code}}
	210
1.1	211	Параметр OrderType – тип заказа может принимать следующие значения:
	212
20.3	213	* Money – заправка на фиксированную сумму
	214	* Liters – заправка на литры
1.1	215
	216	Параметр Status – статус заказа может принимать следующие значения
	217
	218	* OrderCreated – заказ создан и полностью оплачен
20.3	219	* Accepted - АЗС готова начать налив
	220	* Expired – статус от АЗС не поступил в течение 30 минут
1.1	221	* Completed – заказа завершен успешно
	222	* StationCanceled – заказ отменен оператором АЗС или же Топаз "Web Офис"
	223	* UserCanceled – заказ отменен пользователем
	224
	225	Параметр ContractId – стандартными типами договора, по которому обрабатывается заказ
	226
	227	* Individual – договор возмездного оказания услуг (физические лица)
	228	* Corporation - договор купли продажи топлива (юридические лица)
	229
	230	Так же можно указать любые другие типы договора по договоренности между сетью АЗС и внешней системой.
	231
	232	При получении заказа в статусе OrderCreated Топаз "Web Офис" проверяет ряд параметров StationExtendedId – в случае если идентификатор станции не найден в Топаз "Web Офис", то Топаз "Web Офис" дает ответ 400
	233
24.1	234	FuelId + PriceFuel – в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ 402.
1.1	235
	236
41.1	237	== Отмена заказа ==
	238
42.1	239	Отмена заказа возможна даже после его старта. Для инициации отмены необходимо отправить тот же заказ со статусом (% style="background-color:#dddddd; font-family:Courier New,Courier,monospace" %)UserCanceled(%%). Если на момент получения запроса на отмену процесс налива ещё не начался, заказ будет отменён.
41.1	240
	241	В случае, если отмена инициирована после начала налива, система остановит процесс пролива и зафиксирует заказ как отменённый. В этом случае в ответе будет указано количество литров, фактически налитых до момента остановки.
	242
	243
24.1	244	== Проверка статуса работы станции ==
	245
	246	Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ baseUrl с префиксом
	247
	248	/ping?apikey={apikey}&stationId={stationId}&columnId={columnId},
	249
	250	stationId – идентификатор станции
	251
	252	columnId – идентификатор стороны ТРК
	253
	254	запрос типа GET , timeout 10 секунд.
	255
	256	==== Статусы ответов ====
	257
	258	200 ОК – станция и ТРК готова принять и обработать заказ
	259
35.1	260	400 – станция или ТРК не найдена (неверный идентификатор станции или ТРК)
24.1	261
35.1	262	404 – ТРК занята / ТРК не готова принять заказ
	263
24.1	264	любой ответ не 200 ОК – интерпретируется как на станции нет интернета / станция не доступна
	265
	266	----
	267
	268	Для получения статусов Интегратору необходимо со своей стороны реализовать сервис для их получения и обработки.
	269
26.1	270	== Методы REST API интегратора (внешней системы): ==
24.1	271
51.1	272
	273
	274	=== Получение статусов от Топаз Web-офис ===
	275
	276
	277
24.1	278	1. Статус Accepted
	279	1. Статус Fueling
	280	1. Статус Canceled
	281	1. Статус Completed
49.1	282	1. Отправка счетчика налива Volume
24.1	283
	284	Данные запросы "Топаз-Web Office" отправляет Интегратору.
	285
47.1	286	(% class="box infomessage" %)
	287	(((
50.1	288	##Все методы, отправляющие статусы заказа (##Accepted, Fueling, Canceled, Completed, Volume),## отправляют данные в теле в формате x-www-form-urlencoded##
47.1	289	)))
	290
24.1	291	=== Статус Accepted ===
	292
19.1	293	Данный статус сообщает внешней системе о том, что заказ принят и обработан в "Топаз-Web Office"
1.1	294
19.1	295	Данный статус "Топаз-Web Office" отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг
1.1	296
19.1	297	В случае если внешняя система дала ответ, отличный от 200 ОК , то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ
1.1	298
23.1	299	baseUrl + /api/order/accept
1.1	300
23.1	301	POST
	302
1.1	303	apikey={apikey}&orderId={ordeId}
	304
	305	все параметры являются обязательными
	306
33.1	307	=== ===
	308
24.1	309	=== Статус Fueling ===
1.1	310
19.1	311	Данный статус сообщает внешней системе о том, что "Топаз-Web Office" готов запустить колонку (начать пролив)
1.1	312
19.1	313	Данный статус "Топаз-Web Office" отсылает перед началом пуска колонки
1.1	314
19.1	315	В случае если внешняя система дала ответ, отличный от 200 ОК , то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ
1.1	316
23.1	317	baseUrl + /api/order/fueling
1.1	318
23.1	319	POST
	320
1.1	321	apikey={apikey}&orderId={ordeId}
	322
	323	все параметры являются обязательными
	324
33.1	325	=== ===
	326
24.1	327	=== Статус Canceled ===
1.1	328
	329	Данный статус сообщает внешней системе о том, что заказ следует отменить
	330
17.1	331	baseUrl + /api/order/canceled
1.1	332
	333	POST
	334
	335	apikey={apikey}&orderId={ordeId}&reason={reason}
	336
	337	все параметры являются обязательными
	338
	339	reason – текстовая причина отмены
	340
33.1	341	=== ===
	342
24.1	343	=== Статус Completed ===
1.1	344
	345	Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито
	346
19.1	347	В случае если внешняя система дала ответ отличный от 200 ОК , то "Топаз-Web Office" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа 200 ОК
1.1	348
17.1	349	baseUrl + /api/order/completed POST
1.1	350
50.1	351	apikey={apikey}&orderId={ordeId}&litre={litre}&summ={summ}&extendedOrderId={extendedOrderId}&extendedDate={extendedDate}
1.1	352
	353	все параметры являются обязательными
	354
50.1	355	litre – кол-во пролитых литров, указывается как double с разделителем точка,
1.1	356
50.1	357	summ - итоговая сумма заказа,
	358
	359	extendedOrderId – идентификатор заказа в АСУ сети
	360
1.1	361	extendedDate – дата по которой АСУ строит отчет для сверки, формат dd.MM.yyyy HH:mm:ss
	362
33.1	363	=== ===
	364
24.1	365	=== Отправка счетчика налива ===
1.1	366
19.1	367	В момент процесса налива "Топаз-Web Office" может сообщать внешней системе статус счетчика налива
1.1	368
19.1	369	Для этого с периодичностью от 5 – 10 секунд "Топаз-Web Office" выполняет следующий запрос
1.1	370
17.1	371	baseUrl + /api/order/volume
1.1	372
	373	POST
	374
	375	apikey={apikey}&orderId={ordeId}&litre={litre}
	376
	377	все параметры являются обязательными
	378
	379	litre – кол-во пролитых на момент отправки запроса литров, указывается как double с разделителем точка
51.1	380
	381
	382	=== Отправка статусов в Топаз Web Офис ===
	383
	384	Для согласованности заказов после каждого полученного статуса от Топаз Web Офис необходимо отправить статус в системе Интегратора.
	385	Для этого необходимо повторить запрос /order, с измененными полями OrderStatus, в соответствии с состоянием заказа в системе Интегратора.
	386	При отправке статуса Completed допускается присылать размер реально налитых литров и оплаченных средств LitreCompleted, SumPaidCompleted