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

Редактировал(а) Dmitriy 2026/04/23 06:18

От 19.1 до 18.1

От версии 18.1

отредактировано Ярослава Ерина
на 2024/09/25 08:48

Изменить комментарий: К данной версии нет комментариев

К версии 1.1

отредактировано Ярослава Ерина
на 2024/07/17 12:36

Изменить комментарий: К данной версии нет комментариев

Необработанный
Обработанный

Сводка

Свойства страницы (1 изменено, 0 добавлено, 0 удалено)

Подробности

Свойства страницы

Содержимое

@@ -14,51 +14,48 @@
  После получения информации по указанным пунктам, от ООО "Топаз-сервис" будет предоставлен тестовый доступ для настройки интеграции.
--Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы внешних наливов в Топаз "Web Офис".
++Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы внешних наливов в Топаз "Web Офис". Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке externalSystemApikey
--(% class="box errormessage" %)
--(((
--Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке externalSystemApikey
--)))
--
--== Адрес для отправки запросов ==
--
--Базовым адресом **(baseUrl)** для выполнения запросов является  [[https:~~/~~/topazoffice.ru/ms/external-fueling/integration>>https://topazoffice.ru/ms/external-fueling/integration]]
--
  == Получение списка АЗС и их конфигураций ==
--Внешняя система опрашивает Топаз "Web Офис" для получения списка АЗС и их конфигураций **через HTTP **запрос на **baseUrl **с префиксом **/station?apikey={apikey **}, запрос типа **GET **, timeout 10 секунд.
++Внешняя система опрашивает Топаз "Web Офис" для получения списка АЗС и их конфигураций **через HTTP **запрос на **url **с префиксом **/integration/station?apikey={apikey **}, запрос типа **GET **, timeout 10 секунд.
  В ответ Топаз "Web Офис" дает ответ в формате **JSON**
  **...**
--{{code language="javascript"}}
--{
--// идентификатор станции АЗС
--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
--}
--{{/code}}
++{{{{
++ // идентификатор станции АЗС
++ 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
++}}}}
  **Возможные идентификаторы топлива**
@@ -79,83 +79,75 @@
  == Получение прайс-листа ==
--Внешняя система опрашивает Топаз "Web Офис" для получения прайс-листа **HTTP **запросом на **baseUrl **с префиксом **/price?apikey={apikey} **, запрос типа **GET **, timeout 10секунд.
++Внешняя система опрашивает Топаз "Web Офис" для получения прайс-листа **HTTP **запросом на **url **с префиксом **/integration/price?apikey={apikey} **, запрос типа **GET **, timeout 10секунд.
--В ответ Топаз "Web Офис" дает ответ в формате **JSON**{{{}}}
++В ответ Топаз "Web Офис" дает ответ в формате **JSON**
--{{code language="javascript"}}
--{
-- {
-- // идентификатор станции внутри Топаз "Web Офис"
-- string StationId,
-- // идентификатор топлива
-- string ProductId,
-- // цена за 1 литр
-- double Price
-- },
--…. N
--}
--{{/code}}
++{{{{
++  {
++   // идентификатор станции внутри Топаз "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},
++}}}}
--**Пример ответа**{{{}}}
--
--{{code language="javascript"}}
--{
--{“StationId”: “0001”, “ProductId”: “a92”, “Price”: 38.66},
--{“StationId”: “0001”, “ProductId”: “a95_premium”, “Price”: 45.21},
--{“StationId”: “0002”, “ProductId”: “a92”, “Price”: 38.98},
--}
--{{/code}}
--
  == Обработка заказа ==
  [[image:https://wiki.topazelectro.ru/download/attachments/1179735/image2023-1-19_16-21-33.png?version=1&modificationDate=1716374642000&api=v2]]
--Информирование Топаз "Web Офис" о заказе и их статусах осуществляется **HTTP **запросом на **baseUrl **с префиксом **/order **, запрос типа **POST **, timeout 10 секунд.
++Информирование Топаз "Web Офис" о заказе и их статусах осуществляется **HTTP **запросом на **url **с префиксом **/integration/order **, запрос типа **POST **, timeout 10 секунд.
--**Тело запроса содержит JSON вида Order**{{{}}}
++**Тело запроса содержит JSON вида Order**
--{{code language="none"}}
--{
--// идентификатор заказа
--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
--}
--{{/code}}
++{{{{
++ // идентификатор заказа
++ 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 **– тип заказа может принимать следующие значения:
@@ -162,6 +162,7 @@
  * **Money **– заправка на фиксированную сумму, **OrderVolume **– сумма рублей
  * **Liters **– заправка на литры, **OrderVolume **– кол-вол литров
++
  Параметр **Status **– статус заказа может принимать следующие значения
  * **OrderCreated **– заказ создан и полностью оплачен
@@ -170,6 +170,7 @@
  * **StationCanceled **– заказ отменен оператором АЗС или же Топаз "Web Офис"
  * **UserCanceled **– заказ отменен пользователем
++
  Параметр **ContractId **– стандартными типами договора, по которому обрабатывается заказ
  * **Individual **– договор возмездного оказания услуг (физические лица)
@@ -191,7 +191,7 @@
  В случае если внешняя система дала ответ, отличный от **200 ОК **, то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ
--**baseUrl + /api/order/accept POST**
++**базовый url + /api/order/accept POST**
  **apikey={apikey}&orderId={ordeId}**
@@ -205,7 +205,7 @@
  В случае если внешняя система дала ответ, отличный от **200 ОК **, то Топаз "Web Офис" отсылает статус Canceled и прекращает обработку заказ
--**baseUrl + /api/order/fueling POST**
++**базовый url + /api/order/fueling POST**
  **apikey={apikey}&orderId={ordeId}**
@@ -215,7 +215,7 @@
  Данный статус сообщает внешней системе о том, что заказ следует отменить
--**baseUrl + /api/order/canceled**
++**базовый url + /api/order/canceled**
  **POST**
@@ -231,7 +231,7 @@
  В случае если внешняя система дала ответ отличный от **200 ОК **, то Топаз "Web Офис" отсылает запросы с некоторым отложенным количеством времени до момента получения ответа **200 ОК**
--**baseUrl + /api/order/completed POST**
++**базовый url + /api/order/completed POST**
  **apikey={apikey}&orderId={ordeId}&litre={litre}&extendedOrderId={extendedOrderId}&**
@@ -249,7 +249,7 @@
  Для этого с периодичностью от 5 – 10 секунд Топаз "Web Офис" выполняет следующий запрос
--**baseUrl + /api/order/volume**
++**базовый url + /api/order/volume**
  **POST**
@@ -261,9 +261,9 @@
  == Проверка статуса работы станции ==
--Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ **baseUrl **с префиксом
++Перед формирование заказ внешняя система делает запрос на станцию для определения доступности и готовности станции принять заказ url с префиксом
--**/ping?apikey={apikey}&stationId={stationId}&columnId={columnId}, stationId **– идентификатор станции
++**/integration/ping?apikey={apikey}&stationId={stationId}&columnId={columnId}, stationId **– идентификатор станции
  **columnId **– идентификатор ТРК