Протокол интеграции систем внешних наливов с Топаз "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

...

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

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

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

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

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

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

Информирование Топаз "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 ОК – интерпретируется как на станции нет интернета / станция не доступна