Исходный код вики Протокол интеграции систем внешних наливов с Топаз "Web Офис"
Версия 11.1 от Ярослава Ерина на 2024/07/30 06:30
Скрыть последних авторов
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 1 | ====== **v 1.0.1** ====== |
| 2 | |||
| 3 | == Настройка перед интеграцией == | ||
| 4 | |||
| 5 | |||
| 6 | Перед началом интеграции, уполномоченный сотрудник компании, предоставляющей услуги внешних наливов, передает в ООО "Топаз-сервис" следующую информацию: | ||
| 7 | |||
| 8 | 1. Базовый url тестового окружения системы внешнего налива | ||
| 9 | 1. Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива | ||
| 10 | 1. Базовый url боевого окружения системы внешнего налива | ||
| 11 | 1. Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива | ||
| 12 | 1. Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис" | ||
| 13 | 1. Иконку системы внешних наливов в формате svg с соотношением сторон 1:1 | ||
| 14 | |||
| 15 | После получения информации по указанным пунктам, от ООО "Топаз-сервис" будет предоставлен тестовый доступ для настройки интеграции. | ||
| 16 | |||
| 17 | Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы внешних наливов в Топаз "Web Офис". Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке externalSystemApikey | ||
| 18 | |||
| 19 | == Получение списка АЗС и их конфигураций == | ||
| 20 | |||
| 21 | Внешняя система опрашивает Топаз "Web Офис" для получения списка АЗС и их конфигураций **через HTTP **запрос на **url **с префиксом **/integration/station?apikey={apikey **}, запрос типа **GET **, timeout 10 секунд. | ||
| 22 | |||
| 23 | В ответ Топаз "Web Офис" дает ответ в формате **JSON** | ||
| 24 | |||
| 25 | **...** | ||
| 26 | |||
| |
11.1 | 27 | {{code language="javascript"}} |
| 28 | { | ||
| |
9.2 | 29 | // идентификатор станции АЗС |
| 30 | string Id | ||
| 31 | // статус станции: true – доступна, false – выключена | ||
| 32 | bool Enable, | ||
| 33 | // наименование станции | ||
| 34 | string Name, | ||
| 35 | // адрес станции | ||
| 36 | string Address, | ||
| 37 | // гео точка на карте | ||
| 38 | location Location | ||
| |
6.1 | 39 | { |
| |
9.2 | 40 | double Lat, |
| 41 | double Lon }, | ||
| 42 | // словарь доступных ТРК | ||
| 43 | Dictionary Columns { | ||
| 44 | // номер колонки | ||
| 45 | (int32) Key: | ||
| 46 | { | ||
| |
6.1 | 47 | // список доступных типов топлива |
| 48 | "Fuels": [ "a92", "a95", "diesel_premium", ... N ] | ||
| 49 | } | ||
| 50 | } ... N | ||
| |
11.1 | 51 | } |
| 52 | {{/code}} | ||
| |
1.1 | 53 | |
| 54 | **Возможные идентификаторы топлива** | ||
| 55 | |||
| 56 | |ID|Марка | ||
| 57 | |diesel|дизель | ||
| 58 | |diesel_premium|брендированный дизель | ||
| 59 | |a80|бензин марки А80 | ||
| 60 | |a92|бензин марки А92 | ||
| 61 | |a92_premium|брендированный бензин марки А92 | ||
| 62 | |a95|бензин марки А95 | ||
| 63 | |a95_premium|брендированный бензин марки А95 | ||
| 64 | |a98|бензин марки А98 | ||
| 65 | |a98_premium|брендированный бензин марки А98 | ||
| 66 | |a100|бензин марки А100 | ||
| 67 | |a100_premium|брендированный бензин марки А100 | ||
| 68 | |propane|газ пропан | ||
| 69 | |metan|метан | ||
| 70 | |||
| 71 | == Получение прайс-листа == | ||
| 72 | |||
| 73 | Внешняя система опрашивает Топаз "Web Офис" для получения прайс-листа **HTTP **запросом на **url **с префиксом **/integration/price?apikey={apikey} **, запрос типа **GET **, timeout 10секунд. | ||
| 74 | |||
| |
11.1 | 75 | В ответ Топаз "Web Офис" дает ответ в формате **JSON**{{{}}} |
| |
1.1 | 76 | |
| |
11.1 | 77 | {{code language="javascript"}} |
| 78 | { | ||
| 79 | { | ||
| 80 | // идентификатор станции внутри Топаз "Web Офис" | ||
| 81 | string StationId, | ||
| 82 | // идентификатор топлива | ||
| 83 | string ProductId, | ||
| 84 | // цена за 1 литр | ||
| 85 | double Price | ||
| 86 | }, | ||
| 87 | …. N | ||
| 88 | } | ||
| 89 | {{/code}} | ||
| |
1.1 | 90 | |
| |
7.1 | 91 | |
| 92 | {{code language="javascript"}} | ||
| 93 | { | ||
| 94 | { | ||
| 95 | // идентификатор станции внутри Топаз "Web Офис" | ||
| 96 | string StationId, | ||
| 97 | // идентификатор топлива | ||
| 98 | string ProductId, | ||
| 99 | // цена за 1 литр | ||
| 100 | double Price | ||
| 101 | }, …. N | ||
| 102 | } | ||
| 103 | {{/code}} | ||
| 104 | |||
| 105 | |||
| |
1.1 | 106 | **Пример ответа** |
| 107 | |||
| |
2.1 | 108 | {{{{ {“StationId”: “0001”, “ProductId”: “a92”, “Price”: 38.66}, {“StationId”: “0001”, “ProductId”: “a95_premium”, “Price”: 45.21}, {“StationId”: “0002”, “ProductId”: “a92”, “Price”: 38.98}, }}}} |
| |
1.1 | 109 | |
| 110 | == Обработка заказа == | ||
| 111 | |||
| 112 | [[image:https://wiki.topazelectro.ru/download/attachments/1179735/image2023-1-19_16-21-33.png?version=1&modificationDate=1716374642000&api=v2]] | ||
| 113 | |||
| 114 | Информирование Топаз "Web Офис" о заказе и их статусах осуществляется **HTTP **запросом на **url **с префиксом **/integration/order **, запрос типа **POST **, timeout 10 секунд. | ||
| 115 | |||
| 116 | |||
| 117 | **Тело запроса содержит JSON вида Order** | ||
| 118 | |||
| |
2.1 | 119 | {{{{ // идентификатор заказа 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 }}}} |
| |
1.1 | 120 | |
| 121 | Параметр **OrderType **– тип заказа может принимать следующие значения: | ||
| 122 | |||
| 123 | * **Money **– заправка на фиксированную сумму, **OrderVolume **– сумма рублей | ||
| 124 | * **Liters **– заправка на литры, **OrderVolume **– кол-вол литров | ||
| 125 | |||
| 126 | Параметр **Status **– статус заказа может принимать следующие значения | ||
| 127 | |||
| 128 | * **OrderCreated **– заказ создан и полностью оплачен | ||
| 129 | * **Expire **– статус от АЗС не поступил в течение 30 минут | ||
| 130 | * **Completed **– заказа завершен успешно | ||
| 131 | * **StationCanceled **– заказ отменен оператором АЗС или же Топаз "Web Офис" | ||
| 132 | * **UserCanceled **– заказ отменен пользователем | ||
| 133 | |||
| 134 | Параметр **ContractId **– стандартными типами договора, по которому обрабатывается заказ | ||
| 135 | |||
| 136 | * **Individual **– договор возмездного оказания услуг (физические лица) | ||
| 137 | * **Corporation **- договор купли продажи топлива (юридические лица) | ||
| 138 | |||
| 139 | Так же можно указать любые другие типы договора по договоренности между сетью АЗС и внешней системой. | ||
| 140 | |||
| 141 | При получении заказа в статусе **OrderCreated **Топаз "Web Офис" проверяет ряд параметров **StationExtendedId **– в случае если идентификатор станции не найден в Топаз "Web Офис", то Топаз "Web Офис" дает ответ **400** | ||
| 142 | |||
| 143 | **FuelId **+ **PriceFuel **– в случае если стоимость топлива в Топаз "Web Офис" отличается от присланной, то Топаз "Web Офис" дает ответ **402** | ||
| 144 | |||
| 145 | == Передача статусов о заказе == | ||
| 146 | |||
| 147 | === Статус Accept === | ||
| 148 | |||
| 149 | Данный статус сообщает внешней системе о том, что заказ принят и обработан в Топаз "Web Офис" | ||
| 150 | |||
| 151 | Данный статус Топаз "Web Офис"отсылает после того, как были произведены некоторые действия с заказом (например, заказ сохранен в базе данных) и система готова перейти на следующий шаг | ||
| 152 | |||
| 153 | В случае если внешняя система дала ответ, отличный от **200 ОК **, то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ | ||
| 154 | |||
| 155 | **базовый url + /api/order/accept POST** | ||
| 156 | |||
| 157 | **apikey={apikey}&orderId={ordeId}** | ||
| 158 | |||
| 159 | все параметры являются обязательными | ||
| 160 | |||
| 161 | === Статус Fueling === | ||
| 162 | |||
| 163 | Данный статус сообщает внешней системе о том, что Топаз "Web Офис" готов запустить колонку (начать пролив) | ||
| 164 | |||
| 165 | Данный статус Топаз "Web Офис" отсылает перед началом пуска колонки | ||
| 166 | |||
| 167 | В случае если внешняя система дала ответ, отличный от **200 ОК **, то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ | ||
| 168 | |||
| 169 | **базовый url + /api/order/fueling POST** | ||
| 170 | |||
| 171 | **apikey={apikey}&orderId={ordeId}** | ||
| 172 | |||
| 173 | все параметры являются обязательными | ||
| 174 | |||
| 175 | === Статус Canceled === | ||
| 176 | |||
| 177 | Данный статус сообщает внешней системе о том, что заказ следует отменить | ||
| 178 | |||
| 179 | **базовый url + /api/order/canceled** | ||
| 180 | |||
| 181 | **POST** | ||
| 182 | |||
| 183 | **apikey={apikey}&orderId={ordeId}&reason={reason}** | ||
| 184 | |||
| 185 | все параметры являются обязательными | ||
| 186 | |||
| 187 | **reason – **текстовая причина отмены | ||
| 188 | |||
| 189 | === Статус Completed === | ||
| 190 | |||
| 191 | Данный статус сообщает внешней системе о том, что заказ выполнен и топливо залито | ||
| 192 | |||
| 193 | В случае если внешняя система дала ответ отличный от **200 ОК **, то Топаз "Web Офис" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа **200 ОК** | ||
| 194 | |||
| 195 | **базовый url + /api/order/completed POST** | ||
| 196 | |||
| 197 | **apikey={apikey}&orderId={ordeId}&litre={litre}&extendedOrderId={extendedOrderId}&** | ||
| 198 | |||
| 199 | **extendedDate={extendedDate}** | ||
| 200 | |||
| 201 | все параметры являются обязательными | ||
| 202 | |||
| 203 | **litre **– кол-во пролитых литров, указывается как **double **с разделителем точка **extendedOrderId **– идентификатор заказа в АСУ сети | ||
| 204 | |||
| 205 | **extendedDate **– дата по которой АСУ строит отчет для сверки, формат **dd.MM.yyyy HH:mm:ss** | ||
| 206 | |||
| 207 | === Отправка счетчика налива === | ||
| 208 | |||
| 209 | В момент процесса налива Топаз "Web Офис" может сообщать внешней системе статус счетчика налива | ||
| 210 | |||
| 211 | Для этого с периодичностью от 5 – 10 секунд Топаз "Web Офис" выполняет следующий запрос | ||
| 212 | |||
| 213 | **базовый url + /api/order/volume** | ||
| 214 | |||
| 215 | **POST** | ||
| 216 | |||
| 217 | **apikey={apikey}&orderId={ordeId}&litre={litre}** | ||
| 218 | |||
| 219 | все параметры являются обязательными | ||
| 220 | |||
| 221 | **litre **– кол-во пролитых на момент отправки запроса литров, указывается как double с разделителем точка | ||
| 222 | |||
| 223 | == Проверка статуса работы станции == | ||
| 224 | |||
| 225 | Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ url с префиксом | ||
| 226 | |||
| 227 | **/integration/ping?apikey={apikey}&stationId={stationId}&columnId={columnId}, stationId **– идентификатор станции | ||
| 228 | |||
| 229 | **columnId **– идентификатор ТРК | ||
| 230 | |||
| 231 | запрос типа **GET **, timeout 10 секунд. | ||
| 232 | |||
| 233 | == Статусы ответов == | ||
| 234 | |||
| 235 | **200 ОК **– станция и ТРК готова принять и обработать заказ | ||
| 236 | |||
| 237 | **400 **– станция или ТРК не найдена (не верный идентификатор станции или ТРК) **404 **– ТРК занята / ТРК не готова принять заказ | ||
| 238 | |||
| 239 | любой ответ не **200 ОК **– интерпретируется как на станции нет интернета / станция не доступна |