Интеграция с внешними ДЦ

Редактировал(а) Ярослава Ерина 2026/03/31 07:43

Описание API для подключения внешнего дисконтного центра

Содержание

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

Для начала работы необходимо зарегистрироваться в Личном кабинете Интегратора
1. Для регистрации пройдите по ссылке: https://topazoffice.ru/#/auth/integrator-registration/dc
2. После ввода логина и пароля на почту будет отправлено письмо для подтверждения регистрации
3. Перейдите по ссылке из письма для подтверждения учетной записи.
4. Авторизуйтесь в Топаз Web-Office (https://topazoffice.ru/#/login)
5. В открывшейся форме заполните поля:
•   Официальное название системы внешних наливов, которое будет указано в Топаз "Web Офис"
•   Прикрепите иконку Вашей системы в формате svg с соотношением сторон 1:1. Эти название и иконку будут видеть конечные клиенты в Топаз "Web Офис"
•   Базовый url тестового окружения системы внешнего налива
•   Список ip адресов, с которых будут приходить запросы от тестового окружения системы внешнего налива
•   Базовый url боевого окружения системы внешнего налива
•   Список ip адресов, с которых будут приходить запросы от боевого окружения системы внешнего налива
6. Нажмите на кнопку "Создать", после этого вы получите уникальный API-ключ, он отобразится в соответствующем поле.

Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "Web Офис" в заголовке: externalSystemApikey

Методы API Топаз "Web Офис"

Базовый URL для отправки запросов: https://topazoffice.ru/ms/discount-service/api/v1/integration

Получение списка АЗС

Система интегратора опрашивает ТопазВебОфис для получения списка АЗС и их конфигураций по HTTP.

Запрос

GET /station
параметры:
- apikey String
- stationId UUID - не обязательный

Ответы:

200

[
  {
   // Id станции
   "id": "uuid",
   // Признак, является ли станция активной
   "enable": true,
   // Наименование
   "name": "string",
   // Адрес станции
   "address": "string",
   // Координаты на карте
   "location": {
     "lon": 0.00,
     "lat": 0.00
    },
   // Карта топлива, содержит стороны и виды топлива
   "columns": {
     // Номер стороны
     "1": {
       // Состояние поста. READY - готов принять заказ, BUSY - занят
       "state": "READY",
       // Виды топлива
       "fuels": [
         "diesel"
        ]
      },
     "2": {
       "state": "READY",
       "fuels": [
         "diesel"
        ]
      },
     "3": {
       "state": "READY",
       "fuels": [
         "diesel"
        ]
      }
    },
   // Информация о видах топлива, названии и внешних кодах
   "fuelInfo": [
      {
       // Тип топлива. Если значение null, то сопоставление не проводилось
       "fuelType": "string",
       // Наименование топлива
       "name": "string",
       // Внешний код топлива
       "extCode": "string"
      },
      {
       "fuelType": "a95",
       "name": "Аи95",
       "extCode": "95"
      }
    ]
  }
]

    400
    {
        "message": String
    }

Возможные варианты сообщений:
            Не найден apikey
            Не найден stationId
            Нет подписки
            Нет коннекта Т-АЗС
            Т-АЗС не зарегистрирована

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

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	метан

Проверка доступности АЗС

Система интегратора получает информацию о текущем состоянии АЗС по HTTP

Запрос

GET /ping
параметры:
- apikey String
- stationId UUID

- pumpId Integer (необязательный) - Номер стороны

Ответ

    200 - АЗС доступна

    400 - в теле указана причина ошибки
    {
        "message": String
    }
Возможные варианты сообщений:
            Не найден apikey
            Не найден stationId
            Нет подписки
            Нет коннекта Т-АЗС
            Т-АЗС не зарегистрирована

Методы API Интегратора

Поиск карты

Топаз "Web Офис" при получении кода карты от АСУ запрашивает у системы интегратора информацию о карте для информирования оператора о данных карты и привязанных схемах.

POST /cards/find

Запрос

Ответ

параметры:
- apikey String

{
// Код карты или Qr-код
"cardCode": "string"
}

200

{
// уникальный Id карты в системе интегратора
"id": "uuid",
// Внешний код
"extCode": "string",
// Признак активности
"enabled": true,
// Наименование карты
"name": "string",
// Уникальный номер карты
"code": "string",
// Срок действия карты
"useUntilDate": "2025-02-13",
// Телефон владельца
"customerPhone": "string"
}

400 - В теле указана причина ошибки
    {
        "message": String
    }

Получить баланс бонусов по карте

Перед формированием заказа Топаз "Web Офис" запрашивает информацию о доступных бонусах на карте в системе интегратора.

POST /bonuses/balance

Запрос	Ответ
параметры: - apikey String тело: { // Код карты или Qr-код "cardCode": "string" }	200 - (0.0) Количество бонусов с разделителем точка 400 - в теле указана причина ошибки { "message": String }

Получить полный расчет по заказу (дисконт + бонусы)

POST /orders/calc

Запрос	Ответ
параметры: - apikey: String, // Код АЗС, с которой поступил запрос - station: String // Id АЗС, с которой поступил запрос stationId: UUID тело: { // Yникальный Id объекта в системе "id": "uuid", // Карта "card": { // Уникальный номер карты "code": "string" }, // Номер заказа "number": "string", // Позиции заказа "rows": [ { // Товар "item": { // Уникальный Id объекта в системе "id": "uuid", // Id компании "companyId": "uuid", // Внешний код "extCode": "string", // Наименование "name": "string", // Дочерние элементы (для группы) "childs": [ null ], // Признак что это группа "group": true, // Тип товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары) "type": "FUEL" }, // Количество "qty": 0, // Цена "price": 0, // Сумма "summ": 0, // Итого будет списано бонусов "totalWriteOffBonus": 0, // Признак полного чека (для топлива) "fullCheck": true } ], // Количество бонусов на списание "bonusesToWriteoff": 0, // Дата создания "createdAt": "2025-02-13T13:04:55.511Z", // Сумма итого по заказу "totalSumm": 0, // Тип заказа (MONEY - на сумму, LITRE - на литры) "orderType": "MONEY", // Часть итоговой суммы заказа, которая будет списана наличными "cashTotalSum": 0, // Округление при расчете на литры "roundingMode": "UP", // Тип списания бонусов. Добавить объем или уменьшить сумму (ADD_LITRE, DISCOUNT_SUMM) "bonusWriteOffMode": "ADD_LITRE", // Расчет только по обычным скидкам (для товаров) "preliminary": true }	200 тело: { // Id заказа "orderId": "uuid", // Итоговое количество начисленных бонусов по заказу "totalBonus": 0, // Итоговая скидка по заказу "totalDiscount": 0, // Итоговая сумма по заказу "totalSumm": 0, // Позиции заказа "rows": [ { "item": { // Уникальный Id объекта в системе "id": "uuid", // Id компании "companyId": "uuid", // Внешний код "extCode": "string", // Наименование "name": "string", // Дочерние элементы (для группы) "childs": [ null ], // Признак, что это группа "group": true, // Тип товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары) "type": "FUEL" }, // Количество "qty": 0, // Цена "price": 0, // Сумма "summ": 0, // Бонус начисленный по позиции "addedBonuses": 0, // Скидка "discount": 0, // Бонусов списано по позиции "writeOffBonuses": 0 } ], // Статус, указывает, допускается ли продажа "ok": true, // Информация по схемам "schemas": [ { // Уникальный Id объекта в системе "id": "uuid", // Наименование схемы "name": "string", // Внешний код "extCode": "string", // Товар "item": { // Уникальный Id объекта в системе "id": "uuid", // Id компании "companyId": "uuid", // Внешний код "extCode": "string", // Наименование "name": "string", // Дочерние элементы (для группы) "childs": [ null ], // Признак, что это группа "group": true, // Тип товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары) "type": "FUEL" }, // Товары "items": [ { // Уникальный Id объекта в системе "id": "uuid", // Id компании "companyId": "uuid", // Внешний код "extCode": "string", // Наименование "name": "string", // Дочерние элементы (для группы) "childs": [ null ], // Признак что это группа "group": true, // Тип товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары) "type": "FUEL" } ], // Признак активности "enabled": true, // Критерии активности "actCriterias": [ { "id": "uuid", "childs": [ null ], "type": "string" } ], // Использовать категорию товара для схемы "useItemCategory": true, // Категория товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары) "itemCategory": "FUEL", // Тип оплаты: наличные/карта/любой/СБП (ANY, CASH, CARD, SBP) "paymentType": "ANY", // Тип схемы "type": "DiscountMultiTresholdScheme" } ] } 404 - Схема не найдена

Сохранение заказа без расчета по дисконтным схемам. Бонусы будут начислены.

Данный запрос может быть сформирован и отправлен в том случае, если на АЗС отсутствовал интернет на момент завершения. Информация о заказе отправляется при появлении интернета.

POST /orders/store

Запрос

Ответ

параметры:
            - apikey String,

             // Код АЗС, с которой поступил запрос
             - station: String

// Id АЗС, с которой поступил запрос

stationId: UUID

тело:

{
  // Yникальный Id объекта в системе
"id": "uuid",
// Карта
"card": {
   // Yникальный Id карты в системе
   "id": "uuid",
   // Внешний код
   "extCode": "string",
   // Признак активности
   "enabled": true,
   // Наименование карты
   "name": "string",
   // Уникальный номер карты
   "code": "string",
   // Срок действия карты
   "useUntilDate": "2025-02-13",
   // Признак автоматической блокировки
   "autoBlock": true,
   // Признак возможности работы оффлайн
   "offline": true,
   // Телефон владельца
   "customerPhone": "string",
   // Эмиссия карты
   "emission": {
     // Уникальный Id эмиссии в системе
     "id": "uuid",
     // Внешний код
     "extCode": "string",
     // Наименование эмиссии
     "name": "string",
     // Признак активности
     "enabled": true,
     // Подключенные дисконтные схемы к ЭМИССИИ
     "dicsountSchemaIds": [
       "uuid"
      ],
     // Подключенные бонусные схемы к ЭМИССИИ
     "bonusSchemaIds": [
       "uuid"
      ]
    },
   // Подключенные дисконтные схемы к КАРТЕ
   "dicsountSchemaIds": [
     "uuid"
    ],
   // Подключенные бонусные схемы к КАРТЕ
   "bonusSchemaIds": [
     "uuid"
    ],
   // Количество бонусов
   "balance": 0
  },
// Номер заказа
"number": "string",
// Позиции заказа
"rows": [
    {
     // Товар
     "item": {
       // Уникальный Id объекта в системе
       "id": "uuid",
       // Id компании
       "companyId": "uuid",
       // Внешний код
       "extCode": "string",
       // Наименование
       "name": "string",
       // Дочерние элементы (для группы)
       "childs": [
         null
        ],
       // Признак что это группа
       "group": true,
       // Тип товара (FUEL - топливо, OTHER - товары, ALL - топливо и товары)
       "type": "FUEL"
      },
     // Количество
     "qty": 0,
     // Цена
     "price": 0,
     // Сумма
     "summ": 0,
     // Итого будет начислено бонусов
     "totalAddBonus": 0,
     // Итого будет списано бонусов
     "totalWriteOffBonus": 0,
     // Признак полного чека (для топлива)
     "fullCheck": true
    }
  ],
// Количество бонусов на списание
"bonusesToWriteoff": 0,
// Дата создания
"createdAt": "2025-02-13T13:04:55.511Z",
// Сумма итого по заказу
"totalSumm": 0,
// Тип заказа (MONEY - на сумму, LITRE - на литры)
"orderType": "MONEY",
// Часть итоговой суммы заказа, которая будет списана наличными
"cashTotalSum": 0,
// Округление при расчете на литры
"roundingMode": "UP",
// Тип списания бонусов. Добавить объем или уменьшить сумму (ADD_LITRE, DISCOUNT_SUMM)
"bonusWriteOffMode": "ADD_LITRE",
// Итого добавлено бонусов за заказ
"totalAddBonus": 0,
// Купоны
"couponIds": [
   "uuid"
  ],
// Ид внешней системы дисконта
"externalSystemId": "uuid",
// Расчет только по обычным скидкам (для товаров)
"preliminary": true
}

200

404 - схема не найдена

Возврат заказа

POST /orders/refund

Запрос

Ответ

параметры:
            - apikey String,

             // Код АЗС, с которой поступил запрос
             - station: String

// Id АЗС, с которой поступил запрос

stationId: UUID

тело:

{
// Yникальный Id объекта в системе
"orderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
// Товары
"items": [
    {
     // Внешний код товара
     "extCode": "string",
     // Количество
     "qty": 0
    }
  ]
}

200

Закрытие заказа

Закрывает заказ по id расчета, списывает бонусы.

GET /orders/close/

Запрос	Ответ
параметры: - apikey String - id String, // Код АЗС, с которой поступил запрос - station: String // Id АЗС, с которой поступил запрос stationId: UUID	200 - Ok 400 - Заказ пустой 404 - Расчет не найден

Алгоритм действий при выполнении заказа

Оператор оформляет заказ и считывает QR-код или код карты
АСУ передает полученный код во внешнюю систему и получает информацию о карте и доступных схемах для отображения оператору
Отдельно запрашивается информация о доступных бонусах на карте
АСУ запрашивает полный расчет скидок и бонусов, основанных на перечне товаров
После выполнения заказа направляется запрос на закрытие заказа.
Если на момент закрытия заказа пропал интернет, заказ откладывается в АСУ для отправки позднее. Скидка в таком случае не применяется.
В случае возврата товара отправляется запрос, содержащий внешние коды товаров и их количество. Требуется найти по уникальному идентификатору номер заказа, скорректировать количество и выполнить перерасчет