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

v 1.0.1

Настройка перед интеграцией

Перед началом интеграции, уполномоченный сотрудник компании, предоставляющей услуги внешних наливов, передает в ООО "Топаз-сервис" следующую информацию:

1. Базовый url тестового окружения системы внешнего налива
2. Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
3. Базовый url боевого окружения системы внешнего налива
4. Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
5. Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"
6. Иконку системы внешних наливов в формате svg с соотношением сторон 1:1

После получения информации по указанным пунктам, от ООО "Топаз-сервис" будет предоставлен тестовый доступ для настройки интеграции.

Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы внешних наливов в Топаз "Web Офис". Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке externalSystemApikey

Получение списка АЗС и их конфигураций

Внешняя система опрашивает Топаз "Web Офис" для получения списка АЗС и их конфигураций через HTTP запрос на url с префиксом /integration/station?apikey={apikey }, запрос типа GET , timeout 10 секунд.

В ответ Топаз "Web Офис" дает ответ в формате JSON

{
	// идентификатор станции АЗС
	// поле Id для заказа должно быть уникальным, не содержать пробелы и иметь максимальную длину - 60 символов
	string Id
	// статус станции: true - доступна, false - выключена
	bool Enable,
	// наименование станции
	string Name,
	// адрес станции
	string Address,
	// гео точка на карте
	location Location { 
		double Lat, 
		double Lon
	},
	// словарь доступных ТРК
	Dictionary Columns
	{
		// номер колонки (int32)
		Key: {
			// список доступных типов топлива
			"Fuels": [
				"a92",
				"a95",
				"diesel_premium",
				... 
				N
			]
		}
	}
	...
	 N
}

Возможные идентификаторы топлива

Получение прайс-листа

Внешняя система опрашивает Топаз "Web Офис" для получения прайс-листа HTTP запросом на url с префиксом /integration/price?apikey={apikey} , запрос типа GET , timeout 10секунд.

В ответ Топаз "Web Офис" дает ответ в формате JSON

{
		{
			// идентификатор станции внутри Топаз "Web Офис"
			string StationId,
			// идентификатор топлива
			string ProductId,
			// цена за 1 литр
			double Price
		},
		…. N
}

Пример ответа

{
	{“StationId”: “0001”, “ProductId”: “a92”, “Price”: 38.66},
	{“StationId”: “0001”, “ProductId”: “a95_premium”, “Price”: 45.21},
	{“StationId”: “0002”, “ProductId”: “a92”, “Price”: 38.98},
}

Обработка заказа

Информирование Топаз "Web Офис" о заказе и их статусах осуществляется HTTP запросом на url с префиксом /integration/order , запрос типа POST , timeout 10 секунд.

Тело запроса содержит JSON вида Order

{
	// идентификатор заказа
	string Id
	// дата и время создания в UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
	String DateCreate
	// значение заказа
	double OrderVolume
	// идентификатор станции АЗС
	string StationExtendedId
	// номер колонки
	int ColumnId
	// идентификатор топлива
	string FuelId
	// стоимость 1 литра топлива
	double PriceFuel
	// сумма заказа
	double Sum
	// кол-во литров
	double Litre
	// итого оплачено
	double SumPaid
	// статус заказа
	OrderStatus Status
	// дата и время завершения заказа UTC, формат даты yyyy-MM-dd'T'HH:mm:ss.SSSSSSS'Z' либо yyyy-MM-dd HH:mm:ss
	String DateEnd
	// идентификатор причины отмены заказа
	string ReasonId
	// причина отмены
	string Reason
	// итого сумма литров залито
	double LitreCompleted
	// итого оплачено по завершению заказа
	double SumPaidCompleted
	// идентификатор договора
	string ContractId
}

Параметр OrderType – тип заказа может принимать следующие значения:

• Money – заправка на фиксированную сумму, OrderVolume – сумма рублей
• Liters – заправка на литры, OrderVolume – кол-вол литров

Параметр Status – статус заказа может принимать следующие значения

• OrderCreated – заказ создан и полностью оплачен
• Expire – статус от АЗС не поступил в течение 30 минут
• Completed – заказа завершен успешно
• StationCanceled – заказ отменен оператором АЗС или же Топаз "Web Офис"
• UserCanceled – заказ отменен пользователем

Параметр ContractId – стандартными типами договора, по которому обрабатывается заказ

• Individual – договор возмездного оказания услуг (физические лица)
• Corporation - договор купли продажи топлива (юридические лица)

Так же можно указать любые другие типы договора по договоренности между сетью АЗС и внешней системой.

При получении заказа в статусе OrderCreated Топаз "Web Офис" проверяет ряд параметров StationExtendedId – в случае если идентификатор станции не найден в Топаз "Web Офис", то Топаз "Web Офис" дает ответ 400

FuelId + PriceFuel – в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ 402

Передача статусов о заказе

Статус Accept

Данный статус сообщает внешней системе о том, что заказ принят и обработан в Топаз "Web Офис"

Данный статус Топаз "Web Офис"отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг

В случае если внешняя система дала ответ, отличный от 200 ОК , то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ

базовый url + /api/order/accept POST

apikey={apikey}&orderId={ordeId}

все параметры являются обязательными

Статус Fueling

Данный статус сообщает внешней системе о том, что Топаз "Web Офис" готов запустить колонку (начать пролив)

Данный статус Топаз "Web Офис" отсылает перед началом пуска колонки

В случае если внешняя система дала ответ, отличный от 200 ОК , то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ

базовый url + /api/order/fueling POST

apikey={apikey}&orderId={ordeId}

все параметры являются обязательными

Статус Canceled

Данный статус сообщает внешней системе о том, что заказ следует отменить

базовый url + /api/order/canceled

POST

apikey={apikey}&orderId={ordeId}&reason={reason}

все параметры являются обязательными

reason – текстовая причина отмены

Статус Completed

Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито

В случае если внешняя система дала ответ отличный от 200 ОК , то Топаз "Web Офис" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа 200 ОК

базовый url + /api/order/completed POST

apikey={apikey}&orderId={ordeId}&litre={litre}&extendedOrderId={extendedOrderId}&

extendedDate={extendedDate}

все параметры являются обязательными

litre – кол-во пролитых литров, указывается как double с разделителем точка extendedOrderId – идентификатор заказа в АСУ сети

extendedDate – дата по которой АСУ строит отчет для сверки, формат dd.MM.yyyy HH:mm:ss

Отправка счетчика налива

В момент процесса налива Топаз "Web Офис" может сообщать внешней системе статус счетчика налива

Для этого с периодичностью от 5 – 10 секунд Топаз "Web Офис" выполняет следующий запрос

базовый url + /api/order/volume

POST

apikey={apikey}&orderId={ordeId}&litre={litre}

все параметры являются обязательными

litre – кол-во пролитых на момент отправки запроса литров, указывается как double с разделителем точка

Проверка статуса работы станции

Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ url с префиксом

/integration/ping?apikey={apikey}&stationId={stationId}&columnId={columnId}, stationId – идентификатор станции

columnId – идентификатор ТРК

запрос типа GET , timeout 10 секунд.

Статусы ответов

200 ОК – станция и ТРК готова принять и обработать заказ

400 – станция или ТРК не найдена (не верный идентификатор станции или ТРК) 404 – ТРК занята / ТРК не готова принять заказ

любой ответ не 200 ОК – интерпретируется как на станции нет интернета / станция не доступна