Перейти к содержимому

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

Редактировал(а) Ярослава Ерина 2026/02/09 11:30

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

Содержание

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

Для начала работы необходимо зарегистрироваться в Личном кабинете Интегратора
1. Для регистрации пройдите по ссылке: https://topazoffice.ru/#/auth/integrator-registration/sc
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 Офис"

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

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

Запрос

Заголовок: externalSystemApikey
 

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": {
       // Виды топлива
        "fuels": [
         "diesel"
        ]
      },
     "2": {
       "fuels": [
         "diesel"
        ]
      },
     "3": {
       "fuels": [
         "diesel"
        ]
      }
    }
  }
]

    400 
    {
        "message": String
    }

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

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

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

Запрос
Заголовок: externalSystemApikey


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

Ответ

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

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

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

Проверка наличия идентификатора (топливной карты)

Запроос

POST /card/info
параметры:
            - apikey String

            - code String

Ответ
200

{
   // Наименование карты
    "name": String,
   // Код карты
    "code": String,
   // Активна или неактивна карта
    "enabled": boolean,
}

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

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

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

Запрос

POST /order/start
параметры:
            - apikey String
Тело: 

{
 // Id топлива в Топаз Web-Офис
  "fuelExtendedId": "string",
 // Цена топлива
  "price": double,
 // Объем заказа
  "volume": double,
 // Время заказа в UTC
  "orderDateTime": "2025-02-12T11:49:37.584Z",
 // Код предъявленной карты
  "cardCode": "string",
 // Код карты водителя, если имеется
  "driverCardCode": "string",
 // QR-код, предъявленный во время заказа
  "qrCode": "string",
 // Номер смены на АЗС
  "sessionNumber": integer
}

Ответ
200

{
   // Идентификатор заказа в системе интегратора
    "transactionId": String,
   // Цена топлива
    "price": double,
   // Доступный объем топлива для данного заказа
    "availableVolume": double,
   // Разрешен/запрещен отпуск топлива
    "fuelingAllowed": Boolean,
   // Причина, если отпуск запрещен
    "reason": String
}

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

Завершение заказа

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

Запрос выполняется независимо от причины завершения.

Возможные причины:

    - успешный налив,
    - частичный налив,
    - отмена.

Запрос

POST /order/finish
параметры:
            - apikey String

тело:

{
  // Номер заказа
   "orderNumber": integer,
  // Объем заказа
   "volume": BigDecimal,
  // Статус заказа: FACT - фактически налито, CANCEL - отмена
   "orderState": Enum [FACT, CANCEL],
  // Идентификатор заказа в системе интегратора
   "transactionId": String
}

Ответ
    200 - Заказ успешно завершен

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

UML-диаграмма базовых операций

UML обмен с внешним РЦ.jpg

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

  • Оператор оформляет заказ и считывает QR-код или код карты
  • АСУ передает полученный код (/order/start)
  • Внешняя система по коду валидирует заказ и возвращает данные по нему
    • Если в ответе поле fuelingAllowed = false, отпуск топлива запрещен, причина указана в поле reason
    • Если ответ 400, отпуск запрещен, причина указана в сообщении
    • Если ответ не был получен по таймауту, отпуск запрещен
  • Данные по заказу передаются в АСУ
  • АСУ в случае разрешенного отпуска сверяет доступный объем (availableVolume)
    • Если доступный объем меньше запрашиваемого, отпуск производится в размере доступного объема
  • При завершении заказа, АСУ отправляет уведомление (/order/finish)
    • Если заказ отменен, поле orderState = CANCEL
    • Если заказ налит, поле orderState = FACT
    • В поле volume указывается фактически налитый объем
  • В ответ на уведомление о завершении заказа внешняя система отправляет 200
    • В случае ответа 200 заказ считается завершенным
    • В случае ответа 400 информация о завершении позже будет повторно отправлена во внешнюю систему