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

Версия 17.1 от Ярослава Ерина на 2024/09/18 06:46

version	line-number	content
1.1	1	====== v 1.0.1 ======
	2
	3	== Настройка перед интеграцией ==
	4
	5
	6	Перед началом интеграции, уполномоченный сотрудник компании, предоставляющей услуги внешних наливов, передает в ООО "Топаз-сервис" следующую информацию:
	7
	8	1. Базовый url тестового окружения системы внешнего налива
	9	1. Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
	10	1. Базовый url боевого окружения системы внешнего налива
	11	1. Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
	12	1. Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"
	13	1. Иконку системы внешних наливов в формате svg с соотношением сторон 1:1
	14
	15	После получения информации по указанным пунктам, от ООО "Топаз-сервис" будет предоставлен тестовый доступ для настройки интеграции.
	16
	17	Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы внешних наливов в Топаз "Web Офис". Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке externalSystemApikey
	18
15.1	19	== Адрес для отправки запросов ==
	20
16.1	21	Базовым адресом (baseUrl) для выполнения запросов является [[https:~~/~~/topazoffice.ru/ms/external-fueling/integration>>https://topazoffice.ru/ms/external-fueling/integration]]
15.1	22
1.1	23	== Получение списка АЗС и их конфигураций ==
	24
17.1	25	Внешняя система опрашивает Топаз "Web Офис" для получения списка АЗС и их конфигураций через HTTP запрос на baseUrl с префиксом /station?apikey={apikey }, запрос типа GET , timeout 10 секунд.
1.1	26
	27	В ответ Топаз "Web Офис" дает ответ в формате JSON
	28
	29	...
	30
11.1	31	{{code language="javascript"}}
	32	{
9.2	33	// идентификатор станции АЗС
	34	string Id
	35	// статус станции: true – доступна, false – выключена
	36	bool Enable,
	37	// наименование станции
	38	string Name,
	39	// адрес станции
	40	string Address,
	41	// гео точка на карте
	42	location Location
6.1	43	{
9.2	44	double Lat,
	45	double Lon },
	46	// словарь доступных ТРК
	47	Dictionary Columns {
	48	// номер колонки
	49	(int32) Key:
	50	{
6.1	51	// список доступных типов топлива
	52	"Fuels": [ "a92", "a95", "diesel_premium", ... N ]
	53	}
	54	} ... N
11.1	55	}
	56	{{/code}}
1.1	57
	58	Возможные идентификаторы топлива
	59
	60	\|ID\|Марка
	61	\|diesel\|дизель
	62	\|diesel_premium\|брендированный дизель
	63	\|a80\|бензин марки А80
	64	\|a92\|бензин марки А92
	65	\|a92_premium\|брендированный бензин марки А92
	66	\|a95\|бензин марки А95
	67	\|a95_premium\|брендированный бензин марки А95
	68	\|a98\|бензин марки А98
	69	\|a98_premium\|брендированный бензин марки А98
	70	\|a100\|бензин марки А100
	71	\|a100_premium\|брендированный бензин марки А100
	72	\|propane\|газ пропан
	73	\|metan\|метан
	74
	75	== Получение прайс-листа ==
	76
17.1	77	Внешняя система опрашивает Топаз "Web Офис" для получения прайс-листа HTTP запросом на baseUrl с префиксом /price?apikey={apikey} , запрос типа GET , timeout 10секунд.
1.1	78
11.1	79	В ответ Топаз "Web Офис" дает ответ в формате JSON{{{}}}
1.1	80
11.1	81	{{code language="javascript"}}
	82	{
	83	{
	84	// идентификатор станции внутри Топаз "Web Офис"
	85	string StationId,
	86	// идентификатор топлива
	87	string ProductId,
	88	// цена за 1 литр
	89	double Price
	90	},
	91	…. N
	92	}
	93	{{/code}}
1.1	94
7.1	95
	96
12.1	97	Пример ответа{{{}}}
1.1	98
12.1	99	{{code language="javascript"}}
	100	{
	101	{“StationId”: “0001”, “ProductId”: “a92”, “Price”: 38.66},
	102	{“StationId”: “0001”, “ProductId”: “a95_premium”, “Price”: 45.21},
	103	{“StationId”: “0002”, “ProductId”: “a92”, “Price”: 38.98},
	104	}
	105	{{/code}}
1.1	106
	107	== Обработка заказа ==
	108
	109	[[image:https://wiki.topazelectro.ru/download/attachments/1179735/image2023-1-19_16-21-33.png?version=1&modificationDate=1716374642000&api=v2]]
	110
17.1	111	Информирование Топаз "Web Офис" о заказе и их статусах осуществляется HTTP запросом на baseUrl с префиксом /order , запрос типа POST , timeout 10 секунд.
1.1	112
	113
13.1	114	Тело запроса содержит JSON вида Order{{{}}}
1.1	115
13.1	116	{{code language="none"}}
	117	{
	118	// идентификатор заказа
	119	string Id
	120	// дата и время создания в UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
	121	String DateCreate
	122	// значение заказа
	123	double OrderVolume
	124	// идентификатор станции АЗС
	125	string StationExtendedId
	126	// номер колонки
	127	int ColumnId
	128	// идентификатор топлива
	129	string FuelId
	130	// стоимость 1 литра топлива
	131	double PriceFuel
	132	// сумма заказа
	133	double Sum
	134	// кол-во литров
	135	double Litre
	136	// итого оплачено
	137	double SumPaid
	138	// статус заказа
	139	OrderStatus Status
	140	// дата и время завершения заказа UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
	141	String DateEnd
	142	// идентификатор причины отмены заказа
	143	string ReasonId
	144	// причина отмены
	145	string Reason
	146	// итого сумма литров залито
	147	double LitreCompleted
	148	// итого оплачено по завершению заказа
	149	double SumPaidCompleted
	150	// идентификатор договора
	151	string ContractId
	152	}
	153	{{/code}}
1.1	154
	155	Параметр OrderType – тип заказа может принимать следующие значения:
	156
	157	* Money – заправка на фиксированную сумму, OrderVolume – сумма рублей
	158	* Liters – заправка на литры, OrderVolume – кол-вол литров
	159
	160	Параметр Status – статус заказа может принимать следующие значения
	161
	162	* OrderCreated – заказ создан и полностью оплачен
	163	* Expire – статус от АЗС не поступил в течение 30 минут
	164	* Completed – заказа завершен успешно
	165	* StationCanceled – заказ отменен оператором АЗС или же Топаз "Web Офис"
	166	* UserCanceled – заказ отменен пользователем
	167
	168	Параметр ContractId – стандартными типами договора, по которому обрабатывается заказ
	169
	170	* Individual – договор возмездного оказания услуг (физические лица)
	171	* Corporation - договор купли продажи топлива (юридические лица)
	172
	173	Так же можно указать любые другие типы договора по договоренности между сетью АЗС и внешней системой.
	174
	175	При получении заказа в статусе OrderCreated Топаз "Web Офис" проверяет ряд параметров StationExtendedId – в случае если идентификатор станции не найден в Топаз "Web Офис", то Топаз "Web Офис" дает ответ 400
	176
	177	FuelId + PriceFuel – в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ 402
	178
	179	== Передача статусов о заказе ==
	180
	181	=== Статус Accept ===
	182
	183	Данный статус сообщает внешней системе о том, что заказ принят и обработан в Топаз "Web Офис"
	184
	185	Данный статус Топаз "Web Офис"отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг
	186
	187	В случае если внешняя система дала ответ, отличный от 200 ОК , то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ
	188
17.1	189	baseUrl + /api/order/accept POST
1.1	190
	191	apikey={apikey}&orderId={ordeId}
	192
	193	все параметры являются обязательными
	194
	195	=== Статус Fueling ===
	196
	197	Данный статус сообщает внешней системе о том, что Топаз "Web Офис" готов запустить колонку (начать пролив)
	198
	199	Данный статус Топаз "Web Офис" отсылает перед началом пуска колонки
	200
	201	В случае если внешняя система дала ответ, отличный от 200 ОК , то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ
	202
17.1	203	baseUrl + /api/order/fueling POST
1.1	204
	205	apikey={apikey}&orderId={ordeId}
	206
	207	все параметры являются обязательными
	208
	209	=== Статус Canceled ===
	210
	211	Данный статус сообщает внешней системе о том, что заказ следует отменить
	212
17.1	213	baseUrl + /api/order/canceled
1.1	214
	215	POST
	216
	217	apikey={apikey}&orderId={ordeId}&reason={reason}
	218
	219	все параметры являются обязательными
	220
	221	reason – текстовая причина отмены
	222
	223	=== Статус Completed ===
	224
	225	Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито
	226
	227	В случае если внешняя система дала ответ отличный от 200 ОК , то Топаз "Web Офис" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа 200 ОК
	228
17.1	229	baseUrl + /api/order/completed POST
1.1	230
	231	apikey={apikey}&orderId={ordeId}&litre={litre}&extendedOrderId={extendedOrderId}&
	232
	233	extendedDate={extendedDate}
	234
	235	все параметры являются обязательными
	236
	237	litre – кол-во пролитых литров, указывается как double с разделителем точка extendedOrderId – идентификатор заказа в АСУ сети
	238
	239	extendedDate – дата по которой АСУ строит отчет для сверки, формат dd.MM.yyyy HH:mm:ss
	240
	241	=== Отправка счетчика налива ===
	242
	243	В момент процесса налива Топаз "Web Офис" может сообщать внешней системе статус счетчика налива
	244
	245	Для этого с периодичностью от 5 – 10 секунд Топаз "Web Офис" выполняет следующий запрос
	246
17.1	247	baseUrl + /api/order/volume
1.1	248
	249	POST
	250
	251	apikey={apikey}&orderId={ordeId}&litre={litre}
	252
	253	все параметры являются обязательными
	254
	255	litre – кол-во пролитых на момент отправки запроса литров, указывается как double с разделителем точка
	256
	257	== Проверка статуса работы станции ==
	258
17.1	259	Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ baseUrl с префиксом
1.1	260
17.1	261	/ping?apikey={apikey}&stationId={stationId}&columnId={columnId}, stationId – идентификатор станции
1.1	262
	263	columnId – идентификатор ТРК
	264
	265	запрос типа GET , timeout 10 секунд.
	266
	267	== Статусы ответов ==
	268
	269	200 ОК – станция и ТРК готова принять и обработать заказ
	270
	271	400 – станция или ТРК не найдена (не верный идентификатор станции или ТРК) 404 – ТРК занята / ТРК не готова принять заказ
	272
	273	любой ответ не 200 ОК – интерпретируется как на станции нет интернета / станция не доступна