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

====== **v 1.0.1** ======

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

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

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**

**...**

**{{code language="javascript"}}{

28

// идентификатор станции АЗС

29

string Id

30

// статус станции: true – доступна, false – выключена

31

bool Enable,

32

// наименование станции

string Name,

// адрес станции

string Address,

// гео точка на карте

location Location

{

double Lat,

double Lon },

// словарь доступных ТРК

Dictionary Columns {

// номер колонки

(int32) Key:

{

// список доступных типов топлива

47

"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 }}}}

53

54

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

|ID|Марка

|diesel|дизель

|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

|propane|газ пропан

|metan|метан

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

72

73

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

74

75

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

76

77

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

{

{

// идентификатор станции внутри Топаз "Web Офис"

84

string StationId,

85

// идентификатор топлива

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}, }}}}

97

98

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

99

100

[[image:https://wiki.topazelectro.ru/download/attachments/1179735/image2023-1-19_16-21-33.png?version=1&modificationDate=1716374642000&api=v2]]

101

102

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

103

104

105

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

106

107

{{{{ // идентификатор заказа 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 }}}}

108

109

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

110

111

* **Money **– заправка на фиксированную сумму, **OrderVolume **– сумма рублей

112

* **Liters **– заправка на литры, **OrderVolume **– кол-вол литров

113

114

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

115

116

* **OrderCreated **– заказ создан и полностью оплачен

117

* **Expire **– статус от АЗС не поступил в течение 30 минут

118

* **Completed **– заказа завершен успешно

119

* **StationCanceled **– заказ отменен оператором АЗС или же Топаз "Web Офис"

120

* **UserCanceled **– заказ отменен пользователем

121

122

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

123

124

* **Individual **– договор возмездного оказания услуг (физические лица)

125

* **Corporation **- договор купли продажи топлива (юридические лица)

126

127

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

128

129

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

130

131

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

132

133

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

134

135

=== Статус Accept ===

136

137

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

138

139

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

140

141

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

142

143

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

144

145

**apikey={apikey}&orderId={ordeId}**

146

147

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

148

149

=== Статус Fueling ===

150

151

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

152

153

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

154

155

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

156

157

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

158

159

**apikey={apikey}&orderId={ordeId}**

160

161

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

162

163

=== Статус Canceled ===

164

165

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

166

167

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

**POST**

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

172

173

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

174

175

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

176

177

=== Статус Completed ===

178

179

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

180

181

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

182

183

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

184

185

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

186

187

**extendedDate={extendedDate}**

188

189

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