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

Версия 23.1 от Dmitriy на 2024/12/06 10:17

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