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

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

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