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

Версия 31.1 от Ярослава Ерина на 2024/12/11 12:55

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