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

Версия 37.5 от Dmitriy на 2025/02/19 10:23

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