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

Версия 40.1 от Ярослава Ерина на 2026/01/16 11:04

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