Перейти к содержанию

API интеграции с ВИНК

Обзор

FuelProcessing интегрирована с 11 внешними топливными сервисами (ВИНКами) для синхронизации карт, транзакций, лимитов и балансов.

Общая архитектура

graph TB
    subgraph "FuelProcessing"
        APIEXECUTOR[ApiExecutor<br/>Coordinator]
        FACTORY[ApiServiceFactory<br/>Factory]
    end

    subgraph "API Clients"
        TRACK[TrackApiService]
        TATNEFT[TatneftApiService]
        GAZPROM[GazpromApiService]
        LUKOIL[LukoilApiService]
        ROSNEFT[RosneftApiService]
        VEZDEHOD[VezdehodApiService]
        NATCAR[NatCarApiService]
        INFORKOM[InforkomApiService]
        SOFT[SoftEngineeringApiService]
        TAIF[TaifNKApiService]
        GLOBAL[GlobaltruckApiService]
    end

    subgraph "External VINCs"
        VTRACK[Track API]
        VTATNEFT[Tatneft API]
        VGAZPROM[Gazpromneft API]
        VLUKOIL[Lukoil API]
        VROSNEFT[Rosneft API]
        VVEZDEHOD[Vezdekhod API]
        VNATCAR[NatCar API]
        VINFORKOM[Inforkom API]
        VSOFT[ASMAP API]
        VTAIF[Taif-NK API]
        VGLOBAL[Globaltruck API]
    end

    APIEXECUTOR --> FACTORY
    FACTORY --> TRACK
    FACTORY --> TATNEFT
    FACTORY --> GAZPROM
    FACTORY --> LUKOIL
    FACTORY --> ROSNEFT
    FACTORY --> VEZDEHOD
    FACTORY --> NATCAR
    FACTORY --> INFORKOM
    FACTORY --> SOFT
    FACTORY --> TAIF
    FACTORY --> GLOBAL

    TRACK --> VTRACK
    TATNEFT --> VTATNEFT
    GAZPROM --> VGAZPROM
    LUKOIL --> VLUKOIL
    ROSNEFT --> VROSNEFT
    VEZDEHOD --> VVEZDEHOD
    NATCAR --> VNATCAR
    INFORKOM --> VINFORKOM
    SOFT --> VSOFT
    TAIF --> VTAIF
    GLOBAL --> VGLOBAL

Общий интерфейс IApiService

Все API клиенты реализуют единый интерфейс:

public interface IApiService
{
    bool IsTest { get; set; }
    void InitRestClient(DirectContractWithVendor settings, bool isTest = false);

    // Синхронизация
    List<Card> GetCards(int directContractWithVendorId);
    void GetTransactions();
    void GetGasStations();
    void GetBalance();

    // Управление
    List<SimpleRepeatItem> AddLimitsToCards(List<Limit> limit);
    void RestoreLimits(List<LimitVinkHistory> model);
    void BlockCard(CardBlockRepeat cardInfo);
    RepeatResultAnswer RepeatBlockCard(CardBlockRepeat cardInfo);

    // Запросы
    IEnumerable<ApiLimitInfo> GetLimits(string cardNumber);
}

Сравнение ВИНК

ВИНК Аутентификация Особенности
Track ApiPassword + ApiLogin Пагинация карт, HTML-парсинг баланса
Tatneft REST + SOAP (сертификат) Двойной метод, VPN required
Gazprom ApiKey + Bearer Ночные отчёты, защита >500 карт
Lukoil Клиент сертификат (.p12) Certificate auth
Rosneft ApiLogin + ApiPassword Авто-бренды, частичные транзакции
Vezdehod ApiKey + ApiLogin Самый простой API
NatCar ApiLogin + ApiPassword Ограниченная функциональность
Inforkom ApiLogin + ApiPassword 36 месяцев транзакций
SoftEngineering ApiKey + ApiLogin API key auth
TaifNK ApiLogin + ApiPassword Token auth
Globaltruck Username/Password + Token Microservices

Типы синхронизации

public enum VinkApiTypeSync
{
    Cards,              // Синхронизация карт
    GasStations,        // Синхронизация АЗС
    HistoryTransactions, // Исторические транзакции
    Balance,            // Баланс договора
    AddLimitsToCards    // Установка лимитов
}

Расписание синхронизации

Тип Интервал Описание
Cards 2 часа Синхронизация карт
GasStations 48 часов Синхронизация АЗС
Balance 20 минут Синхронизация балансов
HistoryTransactions 35 минут История транзакций
BlockCard On demand Блокировка карт
AddLimitsToCards On demand Установка лимитов

Обработка ошибок

ApiResponseCodes

public enum ApiResponseCodes
{
    Success = 0,
    NoProxy = 1,
    Timeout = 2,
    NetworkError = 3,
    InvalidResponse = 4,
    MaxRetriesExceeded = 5,
    ServerError = 6
}

Retry логика

private void ActionWithMonitoring(Action action, DirectContractWithVendor settings,
    VinkApiTypeSync typeSync, string message = "")
{
    try
    {
        apiMonitoring.InProcess = true;
        action();
        apiMonitoring.SyncResult = true;
    }
    catch (Exception e)
    {
        apiMonitoring.SyncResult = false;
        apiMonitoring.ErrorCount++;
        Log.Error(e, message);
    }
    finally
    {
        apiMonitoring.InProcess = false;
    }
}

Мониторинг синхронизации

ApiMonitoring

public class ApiMonitoring
{
    public int CompanyId { get; set; }
    public VinkType VinkName { get; set; }
    public VinkApiTypeSync VinkApi { get; set; }
    public bool InProcess { get; set; }
    public bool SyncResult { get; set; }
    public DateTime SyncDateTime { get; set; }
    public DateTime SyncDateTimeEnd { get; set; }
    public int ErrorCount { get; set; }
}

Документация по конкретным ВИНК

Добавление нового ВИНКа

  1. Создайте класс {Name}ApiService : IApiService
  2. Добавьте значение в VinkType enum
  3. Зарегистрируйте в ApiServiceFactory
  4. Добавьте специфичные настройки в DirectContractWithVendor

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