FuelProcessing.ClientApi — REST API¶

Обзор¶

FuelProcessing.ClientApi — REST API для внешних интеграций. Поддерживает две версии: v1 (базовая) и v2 (улучшенная).

Базовый URL¶

Production: https://api.example.com
Sandbox:    https://sandbox-api.example.com

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

JWT Токены¶

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

Authorization: Bearer <your-jwt-token>

Параметры токена: - Алгоритм: HMAC SHA256 - Время жизни: 1440 минут (24 часа)

Получение токена¶

curl -X POST https://api.example.com/api/v2/account/authuser \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "YourPassword123"
  }'

Response v2:

{
  "isSuccess": true,
  "model": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "fio": "Иванов Иван Иванович",
    "email": "user@example.com",
    "role": "Пользователь",
    "companyTitle": "ООО Ромашка"
  }
}

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

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

{
  "isSuccess": true,
  "message": "Найдено 10 карт",
  "model": { ... },
  "errors": null
}

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

Endpoints¶

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

POST /api/v2/account/authuser¶

Аутентификация и получение токена.

Request:

{
  "email": "user@example.com",
  "password": "YourPassword123"
}

Response:

{
  "isSuccess": true,
  "model": {
    "token": "...",
    "fio": "Иванов Иван Иванович",
    "email": "user@example.com",
    "role": "Пользователь",
    "companyTitle": "ООО Ромашка"
  }
}

Карты¶

GET /api/v2/card/cards¶

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

Query Parameters:

Параметр	Тип	Описание
cardType	string	Фильтр по типу карты
contractTitle	string	Фильтр по контракту
size	int	Количество карт (макс. 100)
page	int	Номер страницы

Response:

{
  "isSuccess": true,
  "message": "Найдено 25 карт",
  "model": {
    "items": [
      {
        "cardType": "Евро",
        "cardNumber": "1234567890",
        "isActive": true,
        "pinCode": "1234",
        "contractTitle": "Договор №123"
      }
    ],
    "page": 1,
    "totalPages": 3
  }
}

POST /api/v2/card/changecardstatus¶

Изменить статус блокировки карты.

Query Parameters:

Параметр	Тип	Описание
setBlocked	bool	`true` — заблокировать, `false` — разблокировать
cardNumber	string	Номер карты

Response:

{
  "isSuccess": true,
  "model": "Карта успешно разблокирована"
}

GET /api/v2/card/blockhistory¶

Получить историю блокировок карты (только v2).

Query Parameters:

Параметр	Тип	Описание
cardNumber	string	Номер карты

Response:

{
  "isSuccess": true,
  "model": {
    "cardNumber": "1234567890",
    "items": [
      {
        "changedAt": "2025-01-05T10:30:00",
        "status": "Заблокирована пользователем",
        "statusCode": "BlockByUser",
        "iconId": "block_user"
      }
    ]
  }
}

Лимиты¶

GET /api/v2/limit/getfueltypes¶

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

Response:

{
  "isSuccess": true,
  "model": {
    "fuelTypes": ["АИ-80", "АИ-92", "АИ-95", "ДТ"],
    "fuelCategories": ["Бензин", "Дизель"],
    "limitTypes": ["День", "Неделя", "Месяц"]
  }
}

GET /api/v2/limit/getcardlimits¶

Получить лимиты по карте.

Query Parameters:

Параметр	Тип	Описание
cardNumber	string	Номер карты

Response:

{
  "isSuccess": true,
  "model": {
    "cardNumber": "1234567890",
    "limits": [
      {
        "id": 1,
        "dayLimit": 1000,
        "weekLimit": 5000,
        "mounthLimit": 15000,
        "fuelCategory": "Бензин",
        "fuelType": "АИ-95",
        "limitType": "Месяц"
      }
    ]
  }
}

POST /api/v2/limit/setcardlimits¶

Установить лимиты по карте.

Request Body:

{
  "cardNumber": "1234567890",
  "typeLimit": "Месяц",
  "limits": [
    {
      "dayLimit": 1000,
      "weekLimit": 5000,
      "mounthLimit": 15000,
      "fuelCategory": "Бензин",
      "fuelType": "АИ-95"
    }
  ]
}

POST /api/v2/limit/deletecardlimit¶

Удалить лимит по ID.

Query Parameters:

Параметр	Тип	Описание
idLimit	int	ID лимита для удаления

Транзакции¶

POST /api/v2/transaction/gettransactions¶

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

Request Body:

{
  "startDateTime": "01.01.2025 00:00",
  "endDateTime": "31.01.2025 23:59",
  "cardNumber": "1234567890",
  "size": 50,
  "page": 1
}

Response:

{
  "isSuccess": true,
  "message": "Найдено 150 транзакций",
  "model": {
    "items": [
      {
        "createDate": "2025-01-05T10:30:00",
        "cardNumber": "1234567890",
        "gasStationAdress": "г. Москва, ул. Примерная, д. 1",
        "fuelType": "АИ-95",
        "volume": 25.5,
        "pricePerItemDiscount": 50.00,
        "discount": 5.00,
        "sum": 1275.00
      }
    ],
    "page": 1,
    "totalPages": 3
  }
}

Прямые договоры¶

GET /api/v2/directcontract/balanceaction¶

Получить балансы по прямым договорам.

Response:

{
  "isSuccess": true,
  "message": "Найдено контрактов: 2 на общую сумму 50000",
  "model": [
    {
      "contractNumber": "ДП-123/2025",
      "contractStatus": "Активный",
      "isActive": true,
      "balance": 30000.00,
      "overdraft": 10000.00,
      "tempOverdraft": 5000.00,
      "tempOverdraftUntil": "2025-02-01T00:00:00"
    }
  ]
}

GET /api/v2/directcontract/paymentrequisites¶

Получить платёжные реквизиты.

Response:

{
  "isSuccess": true,
  "model": {
    "items": [
      {
        "directContractId": 1,
        "contractNumber": "ДП-123/2025",
        "companySellerTitle": "ООО Продавец",
        "companyBill": "РС СберБанк 12345678901234567890",
        "paymentLink": "https://bank.example.com/pay"
      }
    ]
  }
}

GET /api/v2/directcontract/paymentinvoiceinfo¶

Получить информацию для формирования счёта на оплату.

Query Parameters:

Параметр	Тип	Описание
directContractId	int	ID прямого договора
sum	decimal	(опционально) Сумма платежа для формирования URL

Response:

{
  "isSuccess": true,
  "model": {
    "payNumber": "123",
    "format": "PDF",
    "url": "https://api.example.com/DirectPurchaseContract/GetAllStatementInHtml?PayNumber=123&Contract=...&Format=PDF&Sum=10000.00"
  }
}

Возможные ошибки: - Договор не найден. — Договор не существует или недоступен для текущего пользователя - Номер платежа уже использовался по этому договору. — Номер платежа должен быть уникальным - Номер платежа должен быть больше X. — Номер должен быть больше последнего использованного

POST /api/v2/directcontract/paymentinvoice¶

Сформировать и скачать счёт на оплату в формате PDF.

Request Body:

{
  "directContractId": 1,
  "sum": 10000.00
}

Response:

Возвращает PDF файл с заголовками: - X-Pay-Number: Номер платежа - X-Format: Формат (PDF) - Content-Disposition: Имя файла для сохранения (например, Счет на оплату 05_01_2026 10.pdf)

Возможные ошибки: - Некорректные параметры запроса. — Неверный формат или отсутствуют обязательные поля - Договор не найден. — Договор не существует или недоступен - Номер платежа уже использовался по этому договору. — Номер платежа должен быть уникальным - Номер платежа должен быть больше X. — Номер должен быть больше последнего использованного - Не удалось сформировать PDF. — Ошибка при генерации PDF

Swagger¶

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

https://clientapi.oilonline.ru/swagger

Версии: - v1: /swagger/v1/swagger.json - v2: /swagger/v2/swagger.json (рекомендуется)

История изменений документации¶

2026-03-11: обновлены внешние ссылки и Swagger URL после смены доменного имени с onlineoil.ru на lk.oilonline.ru.

Коды ошибок¶

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

Rate Limiting¶

В текущей реализации rate limiting на уровне приложения не настроен. Рекомендуется использовать reverse proxy (Nginx) для ограничения запросов.

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

AuthRequest (V2)¶

public class AuthRequest
{
    public string Email { get; set; }     // Email пользователя
    public string Password { get; set; }  // Пароль пользователя
}

AuthResponse (V2)¶

public class AuthResponse
{
    public string Token { get; set; }        // JWT токен
    public string Fio { get; set; }         // ФИО пользователя
    public string Email { get; set; }       // Email пользователя
    public string Role { get; set; }        // Роль (на русском)
    public string CompanyTitle { get; set; } // Название компании
}

CardRequestClientApi¶

public class CardRequestClientApi
{
    public int Page { get; set; }           // Номер страницы
    public int Size { get; set; }           // Размер страницы (макс. 100)
    public string CardType { get; set; }    // Фильтр по типу карты
    public string ContractTitle { get; set; } // Фильтр по контракту
}

CardResponseClientApi¶

public class CardResponseClientApi
{
    public List<CardItem> Items { get; set; } // Список карт
    public int Page { get; set; }             // Текущая страница
    public int TotalPages { get; set; }       // Общее количество страниц
}

CardItem (V2)¶

public class CardItem
{
    public string CardType { get; set; }      // Тип карты (Евро, и т.д.)
    public string CardNumber { get; set; }    // Номер карты
    public bool IsActive { get; set; }        // Активна ли карта
    public string PinCode { get; set; }       // PIN-код
    public string ContractTitle { get; set; } // Название контракта
}

CardBlockHistoryItem (V2)¶

public class CardBlockHistoryItem
{
    public DateTime ChangedAt { get; set; }   // Дата изменения
    public string Status { get; set; }        // Описание статуса
    public string StatusCode { get; set; }    // Код статуса (BlockByUser, etc.)
    public string IconId { get; set; }        // ID иконки для UI
}

LimitRequest¶

public class LimitRequest
{
    public string CardNumber { get; set; }    // Номер карты
}

LimitResponse¶

public class LimitResponse
{
    public string CardNumber { get; set; }             // Номер карты
    public List<ApiLimitInfo> Limits { get; set; }     // Список лимитов
}

ApiLimitInfo¶

public class ApiLimitInfo
{
    public int Id { get; set; }                // ID лимита
    public decimal DayLimit { get; set; }      // Дневной лимит (литры)
    public decimal WeekLimit { get; set; }     // Недельный лимит
    public decimal MounthLimit { get; set; }    // Месячный лимит
    public string FuelCategory { get; set; }   // Категория топлива
    public string FuelType { get; set; }       // Тип топлива
    public string LimitType { get; set; }      // Тип лимита (День/Неделя/Месяц)
}

ApiLimitRequest¶

public class ApiLimitRequest
{
    public string CardNumber { get; set; }           // Номер карты
    public string TypeLimit { get; set; }            // Тип лимита
    public List<ApiLimitForService> Limits { get; set; } // Лимиты
}

FuelTypesResponse¶

public class FuelTypesResponse
{
    public List<string> FuelTypes { get; set; }      // Список видов топлива
    public List<string> FuelCategories { get; set; } // Список категорий
    public List<string> LimitTypes { get; set; }     // Типы лимитов
}

DirectContractBalanceActionItem¶

public class DirectContractBalanceActionItem
{
    public string ContractNumber { get; set; }        // Номер контракта
    public string ContractStatus { get; set; }        // Статус контракта
    public bool IsActive { get; set; }                // Активен ли
    public decimal Balance { get; set; }              // Баланс
    public decimal Overdraft { get; set; }            // Овердрафт
    public decimal TempOverdraft { get; set; }        // Временный овердрафт
    public DateTime? TempOverdraftUntil { get; set; } // До когда временный овердрафт
}

CompanyPaymentRequisitesItem¶

public class CompanyPaymentRequisitesItem
{
    public int DirectContractId { get; set; }          // ID прямого контракта
    public string ContractNumber { get; set; }         // Номер контракта
    public string CompanySellerTitle { get; set; }     // Продавец
    public string CompanyBill { get; set; }            // Банковские реквизиты
    public string PaymentLink { get; set; }            // Ссылка на оплату
}

Конфигурация JWT¶

Параметры токена¶

Параметр	Значение	Описание
ISSUER	`MyAuthServer`	Издатель токена
AUDIENCE	`MyAuthClient`	Потребитель токена
LIFETIME	`1440` минут	Время жизни (24 часа)
Algorithm	HMAC SHA256	Алгоритм подписи

Заголовки¶

Заголовок	Описание
`Authorization: Bearer <token>`	JWT токен
`gas-station-token`	Токен заправки (для Terminal API)

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

Terminal API — API для терминалов на АЗС
Web Interface — MVC интерфейс
Справочник: Роли — ролевая авторизация