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

Тестовая страница песочницы 1

Редактировал(а) Ярослава Ерина 2025/06/04 10:36

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

Содержание

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

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

  1. Базовый url тестового окружения системы интегратора
  2. Список ip адресов, с которых будут приходить запросы от тестового окружения системы интегратора
  3. Базовый url боевого окружения системы интегратора
  4. Список ip адресов, с которых будут приходить запросы от боевого окружения системы интегратора
  5. Официальное название системы интегратора, которое будет указано в Топаз "Web Офис"
  6. Иконку системы интегратора в формате svg с соотношением сторон 1:1

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

Также будет предоставлен секретный ключ (тестового и боевого окружения) для идентификации системы интегратора в Топаз "Web Офис". Данный ключ необходимо будет передавать во всех запросах от внешней системы в Топаз "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 информация о завершении позже будет повторно отправлена во внешнюю систему