Перед началом интеграции, уполномоченный сотрудник компании, предоставляющей услуги внешних наливов, передает в ООО "Топаз-сервис" следующую информацию:
После получения информации по указанным пунктам, от ООО "Топаз-сервис" будет предоставлен тестовый доступ для настройки интеграции.
Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы внешних наливов в Топаз "Web Офис". Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке externalSystemApikey
Внешняя система опрашивает Топаз "Web Офис" для получения списка АЗС и их конфигураций через HTTP запрос на url с префиксом /integration/station?apikey={apikey }, запрос типа GET , timeout 10 секунд.
В ответ Топаз "Web Офис" дает ответ в формате JSON
{
// идентификатор станции АЗС
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
} |
Возможные идентификаторы топлива
ID | Марка |
diesel | дизель |
diesel_premium | брендированный дизель |
a80 | бензин марки А80 |
a92 | бензин марки А92 |
a92_premium | брендированный бензин марки А92 |
a95 | бензин марки А95 |
a95_premium | брендированный бензин марки А95 |
a98 | бензин марки А98 |
a98_premium | брендированный бензин марки А98 |
a100 | бензин марки А100 |
a100_premium | брендированный бензин марки А100 |
propane | газ пропан |
metan | метан |
Внешняя система опрашивает Топаз "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 – тип заказа может принимать следующие значения:
Параметр Status – статус заказа может принимать следующие значения
Параметр ContractId – стандартными типами договора, по которому обрабатывается заказ
Так же можно указать любые другие типы договора по договоренности между сетью АЗС и внешней системой.
При получении заказа в статусе OrderCreated Топаз "Web Офис" проверяет ряд параметров StationExtendedId – в случае если идентификатор станции не найден в Топаз "Web Офис", то Топаз "Web Офис" дает ответ 400
FuelId + PriceFuel – в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ 402
Данный статус сообщает внешней системе о том, что заказ принят и обработан в Топаз "Web Офис"
Данный статус Топаз "Web Офис"отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг
В случае если внешняя система дала ответ, отличный от 200 ОК , то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ
базовый url + /api/order/accept POST
apikey={apikey}&orderId={ordeId}
все параметры являются обязательными
Данный статус сообщает внешней системе о том, что Топаз "Web Офис" готов запустить колонку (начать пролив)
Данный статус Топаз "Web Офис" отсылает перед началом пуска колонки
В случае если внешняя система дала ответ, отличный от 200 ОК , то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ
базовый url + /api/order/fueling POST
apikey={apikey}&orderId={ordeId}
все параметры являются обязательными
Данный статус сообщает внешней системе о том, что заказ следует отменить
базовый url + /api/order/canceled
POST
apikey={apikey}&orderId={ordeId}&reason={reason}
все параметры являются обязательными
reason – текстовая причина отмены
Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито
В случае если внешняя система дала ответ отличный от 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 ОК – интерпретируется как на станции нет интернета / станция не доступна