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

Версия 43.1 от Ярослава Ерина на 2026/02/09 10:34

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