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

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

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