FuelProcessing.Api — Terminal API¶

Обзор¶

FuelProcessing.Api — REST API для терминалов топливных заправок. Используется мобильными приложениями и терминалами на АЗС для проведения транзакций, управления топливом и авторизации операторов.

Базовый URL¶

Все эндпоинты используют префикс /api/terminal/.

Аутентификация¶

JWT Токены¶

API использует JWT токены для аутентификации:

Authorization: Bearer <your-jwt-token>

Параметры токена: - Алгоритм: HMAC SHA256 - Ключ шифрования: symmetric key - Время жизни: 1440 минут (24 часа) - Издатель: MyAuthServer - Аудитория: MyAuthClient

Получение токена заправки¶

Для работы с API необходимо сначала получить токен заправки:

curl -X GET "https://api.example.com/api/terminal/account/initgasstation?token=<gas-station-identifier>"

Response:

{
  "isSuccess": true,
  "model": {
    "gas_station_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Авторизация оператора¶

curl -X POST https://api.example.com/api/terminal/account/auth \
  -H "Content-Type: application/json" \
  -d '{
    "username": "operator@example.com",
    "password": "Password123",
    "gasStationToken": "<gas-station-token>"
  }'

Response:

{
  "isSuccess": true,
  "model": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "username": "operator@example.com",
    "gasStationAdress": "г. Москва, ул. Примерная, д. 1",
    "gasStationTokenIsBlocked": false
  }
}

Формат ответа¶

Все ответы API обёрнуты в ApiAnswer<T>:

{
  "isSuccess": true,
  "message": "Операция выполнена успешно",
  "model": { ... },
  "errors": null
}

HTTP статусы: - 200 OK — успешный запрос - 401 Unauthorized — токен не предоставлен или невалиден - 400 Bad Request — ошибка валидации

Endpoints¶

Авторизация (AccountController)¶

GET /api/terminal/account/initgasstation¶

Инициализация заправки — получение токена для дальнейшей работы.

Query Parameters:

Параметр	Тип	Обязательный	Описание
token	string	Да	Уникальный идентификатор заправки

Response:

{
  "isSuccess": true,
  "model": {
    "gas_station_token": "строка токена"
  }
}

POST /api/terminal/account/auth¶

Авторизация оператора на терминале.

Request Body:

{
  "username": "operator@example.com",
  "password": "Password123",
  "gasStationToken": "токен заправки"
}

Response:

{
  "isSuccess": true,
  "model": {
    "access_token": "jwt токен",
    "username": "operator@example.com",
    "gasStationAdress": "адрес заправки",
    "gasStationTokenIsBlocked": false
  }
}

GET /api/terminal/account/checkauth¶

Проверка авторизации (требуется JWT токен).

Response:

{
  "isSuccess": true,
  "model": {}
}

GET /api/terminal/account/initfirebase¶

Регистрация устройства для push-уведомлений.

Query Parameters:

Параметр	Тип	Обязательный	Описание
deviceId	string	Да	Идентификатор устройства (Firebase token)

GET /api/terminal/account/sendpush¶

Тестовая отправка push-уведомления.

Топливо (FuelController)¶

POST /api/terminal/fuel/list¶

Получить список доступных видов топлива на текущей заправке с ценами.

Request Body: (пустой)

Response:

{
  "isSuccess": true,
  "model": [
    {
      "id": 1,
      "title": "АИ-95",
      "price": 55.50,
      "dateUpdated": "05.01.2025 10:30"
    },
    {
      "id": 2,
      "title": "ДТ",
      "price": 58.00,
      "dateUpdated": "05.01.2025 10:30"
    }
  ]
}

POST /api/terminal/fuel/edit¶

Редактирование цен на топливо.

Request Body:

{
  "priceList": [
    {
      "id": 1,
      "price": 56.00
    },
    {
      "id": 2,
      "price": 58.50
    }
  ]
}

Response:

{
  "isSuccess": true,
  "message": "Цены обновлены"
}

Транзакции (TransactionsController)¶

POST /api/terminal/transactions/cardverification¶

Верификация карты перед созданием транзакции.

Request Body:

{
  "stsNumber": "1234567890"
}

Response:

{
  "isSuccess": true,
  "model": {
    "transactionToken": "токен для создания транзакции",
    "stsNumber": "1234567890",
    "id": 123,
    "isAvailable": true,
    "pin": "1234",
    "limits": [
      {
        "id": 1,
        "title": "АИ-95",
        "liters": 100
      },
      {
        "id": 2,
        "title": "ДТ",
        "liters": 50
      }
    ]
  }
}

POST /api/terminal/transactions/create¶

Создание новой транзакции.

Request Body:

{
  "transactionToken": "токен из верификации",
  "stsNumber": "1234567890",
  "pin": "1234",
  "fuelTypeId": 1,
  "litersSum": 25.5,
  "autoInput": false
}

Поля запроса:

Поле	Тип	Обязательный	Описание
transactionToken	string	Да	Токен, полученный при верификации карты
stsNumber	string	Да	Номер СТС карты
pin	string	Да	PIN-код карты
fuelTypeId	int	Да	ID вида топлива
litersSum	decimal	Да	Количество литров
autoInput	bool	Нет	true — авто-ввод СТС, false — ручной
transactionId	int	Нет	ID транзакции (только при редактировании)

Response:

{
  "isSuccess": true,
  "model": {
    "id": 456,
    "pinVerification": true,
    "cardBlocking": false,
    "fullSum": 1415.25,
    "fuelPrice": 55.50
  }
}

Поля ответа:

Поле	Описание
pinVerification	true — PIN верный, false — неверный
cardBlocking	true — карта заблокирована (3 неверных PIN)
id	ID созданной транзакции
fullSum	Полная сумма транзакции
fuelPrice	Цена за литр

POST /api/terminal/transactions/uploadphoto¶

Загрузка фотографии чека/транзакции.

Request Body:

{
  "transactionId": 456,
  "photoBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}

POST /api/terminal/transactions/edit¶

Редактирование существующей транзакции.

Request Body: (тот же что и при создании, + transactionId)

{
  "transactionId": 456,
  "transactionToken": "токен из верификации",
  "stsNumber": "1234567890",
  "pin": "1234",
  "fuelTypeId": 1,
  "litersSum": 30.0,
  "autoInput": false
}

POST /api/terminal/transactions/list¶

Получить список транзакций терминала.

Request Body:

{
  "date": "05.01.2025 10:00",
  "timeZone": 180,
  "page": 1
}

Поля запроса:

Поле	Тип	Описание
date	string	Дата и время в формате dd.MM.yyyy HH:mm
timeZone	int	Смещение временной зоны в минутах
page	int	Номер страницы (10 элементов на странице)

Response:

{
  "isSuccess": true,
  "model": {
    "items": [
      {
        "id": 456,
        "createDate": "2025-01-05T10:30:00",
        "fuelType": "АИ-95",
        "volume": 25.5,
        "sum": 1415.25
      }
    ],
    "page": 1,
    "totalPages": 5
  }
}

Офлайн транзакции (OfflineTransactionController)¶

GET /api/terminal/offlinetransaction/listlimits¶

Скачать файл лимитов для офлайн работы.

Response: Файл data.zip с лимитами карт.

POST /api/terminal/offlinetransaction/generate¶

Генерация файла лимитов (административная функция).

POST /api/terminal/offlinetransaction/create¶

Создание офлайн транзакции.

Request Body: (тот же что и обычная транзакция)

{
  "transactionToken": "токен из верификации",
  "stsNumber": "1234567890",
  "pin": "1234",
  "fuelTypeId": 1,
  "litersSum": 25.5,
  "autoInput": false
}

POST /api/terminal/offlinetransaction/getofflinelimitupdatedata¶

Получить дату последнего обновления файла лимитов.

Response:

{
  "isSuccess": true,
  "model": {
    "data": "05.01.2025"
  }
}

Контракты данных (DTOs)¶

AuthRequest¶

public class AuthRequest
{
    public string username { get; set; }      // Email или логин
    public string password { get; set; }      // Пароль
    public string gasStationToken { get; set; } // Токен заправки
}

AuthData¶

public class AuthData
{
    public string access_token { get; }       // JWT токен
    public string username { get; }           // Логин пользователя
    public string gasStationAdress { get; }   // Адрес заправки
    public bool gasStationTokenIsBlocked { get; } // Заблокирована ли заправка
}

AuthGasStationData¶

public class AuthGasStationData
{
    public string gas_station_token { get; set; } // Токен заправки (выдаётся один раз)
}

TransactionRequest¶

public class TransactionRequest
{
    public int? TransactionId { get; set; }        // ID при редактировании
    public string TransactionToken { get; set; }   // Токен из верификации
    public string STSNumber { get; set; }          // Номер СТС карты
    public string PIN { get; set; }                // PIN-код
    public int FuelTypeId { get; set; }            // ID вида топлива
    public decimal LitersSum { get; set; }         // Количество литров
    public bool AutoInput { get; set; }            // Тип ввода СТС
}

TransactionResponse¶

public class TransactionResponse
{
    public bool PINVerification { get; set; }  // Проверка PIN
    public bool CardBlocking { get; set; }     // Блокировка карты
    public int Id { get; set; }                // ID транзакции
    public decimal FullSum { get; set; }       // Полная сумма
    public decimal FuelPrice { get; set; }     // Цена топлива
}

CardInfoRequest¶

public class CardInfoRequest
{
    public string StsNumber { get; set; }  // Номер СТС
}

CardInfoResponse¶

public class CardInfoResponse
{
    public string TransactionToken { get; set; }  // Токен транзакции
    public string STSNumber { get; set; }         // Номер СТС
    public int Id { get; set; }                   // ID карты
    public bool IsAvailable { get; set; }         // Доступность
    public List<CardInfoLimit> Limits { get; set; } // Лимиты
    public string Pin { get; set; }               // PIN-код
}

ApiFuelInfo¶

public class ApiFuelInfo
{
    public int Id { get; set; }           // ID вида топлива
    public string Title { get; set; }     // Название
    public decimal Price { get; set; }    // Цена
    public string DateUpdated { get; set; } // Дата обновления цены
}

Поток работы терминала¶

Инициализация: Получить токен заправки (InitGasStation)
Авторизация: Авторизовать оператора (Auth)
Проверка карты: Верифицировать карту перед транзакцией (CardVerification)
Создание транзакции: Создать транзакцию (Create)
Загрузка фото (опционально): Загрузить чек (UploadPhoto)

Swagger¶

Интерактивная документация доступна по адресу:

https://api.example.com/swagger

Коды ошибок¶

HTTP Код	Описание
200	Успешный запрос
400	Ошибка валидации входных данных
401	Пользователь не авторизован
500	Внутренняя ошибка сервера

Связанная документация¶

Client API — REST API для клиентов
Transaction Handler — Обработка транзакций