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

Версия 46.1 от Ярослава Ерина на 2026/02/09 11:56

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
	46	== Методы API "Топаз-Web Office": ==
	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
	272	1. Статус Accepted
	273	1. Статус Fueling
	274	1. Статус Canceled
	275	1. Статус Completed
	276	1. Отправка счетчика налива
	277
	278	Данные запросы "Топаз-Web Office" отправляет Интегратору.
	279
	280	=== Статус Accepted ===
	281
19.1	282	Данный статус сообщает внешней системе о том, что заказ принят и обработан в "Топаз-Web Office"
1.1	283
19.1	284	Данный статус "Топаз-Web Office" отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг
1.1	285
19.1	286	В случае если внешняя система дала ответ, отличный от 200 ОК , то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ
1.1	287
23.1	288	baseUrl + /api/order/accept
1.1	289
23.1	290	POST
	291
1.1	292	apikey={apikey}&orderId={ordeId}
	293
	294	все параметры являются обязательными
	295
33.1	296	=== ===
	297
24.1	298	=== Статус Fueling ===
1.1	299
19.1	300	Данный статус сообщает внешней системе о том, что "Топаз-Web Office" готов запустить колонку (начать пролив)
1.1	301
19.1	302	Данный статус "Топаз-Web Office" отсылает перед началом пуска колонки
1.1	303
19.1	304	В случае если внешняя система дала ответ, отличный от 200 ОК , то "Топаз-Web Office" отсылает статус Canceled и прекращает обработку заказ
1.1	305
23.1	306	baseUrl + /api/order/fueling
1.1	307
23.1	308	POST
	309
1.1	310	apikey={apikey}&orderId={ordeId}
	311
	312	все параметры являются обязательными
	313
33.1	314	=== ===
	315
24.1	316	=== Статус Canceled ===
1.1	317
	318	Данный статус сообщает внешней системе о том, что заказ следует отменить
	319
17.1	320	baseUrl + /api/order/canceled
1.1	321
	322	POST
	323
	324	apikey={apikey}&orderId={ordeId}&reason={reason}
	325
	326	все параметры являются обязательными
	327
	328	reason – текстовая причина отмены
	329
33.1	330	=== ===
	331
24.1	332	=== Статус Completed ===
1.1	333
	334	Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито
	335
19.1	336	В случае если внешняя система дала ответ отличный от 200 ОК , то "Топаз-Web Office" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа 200 ОК
1.1	337
17.1	338	baseUrl + /api/order/completed POST
1.1	339
23.1	340	apikey={apikey}&orderId={ordeId}&litre={litre}&extendedOrderId={extendedOrderId}&extendedDate={extendedDate}
1.1	341
	342	все параметры являются обязательными
	343
	344	litre – кол-во пролитых литров, указывается как double с разделителем точка extendedOrderId – идентификатор заказа в АСУ сети
	345
	346	extendedDate – дата по которой АСУ строит отчет для сверки, формат dd.MM.yyyy HH:mm:ss
	347
33.1	348	=== ===
	349
24.1	350	=== Отправка счетчика налива ===
1.1	351
19.1	352	В момент процесса налива "Топаз-Web Office" может сообщать внешней системе статус счетчика налива
1.1	353
19.1	354	Для этого с периодичностью от 5 – 10 секунд "Топаз-Web Office" выполняет следующий запрос
1.1	355
17.1	356	baseUrl + /api/order/volume
1.1	357
	358	POST
	359
	360	apikey={apikey}&orderId={ordeId}&litre={litre}
	361
	362	все параметры являются обязательными
	363
	364	litre – кол-во пролитых на момент отправки запроса литров, указывается как double с разделителем точка