API за транзакционни данни на картата Shell B2B Mobility – Ръководство за бързо стартиране

Версия на API: 2.3.5 | Удостоверяване: OAuth 2.0 | Статус: Производствена версия

Вижте ощепреглед

API-то за данни за транзакции с карти на Shell е API, базирано на REST, което позволява на разработчиците да извличат и анализират данни за транзакции от горивните карти на Shell чрез програмиране. API-то предоставя достъп до транзакции с цени, такси, ценообразуване на базата на обем, правила за бонуси, изключения и обобщения за използването на картите.

Забележка: Това ръководство обхваща само крайни точки, автентифицирани чрез OAuth 2.0 (базов път: /transaction-data/v1). Старите крайни точки с Basic Auth (/fleetmanagement/v1/transaction) не са включени, тъй като постепенно се извеждат от употреба.

Основни функции

Извличане на подробности за транзакциите с цени, включително транзакции за електромобили
Достъп до подробности за транзакциите с гориво, включително артикули за продажба и такси
Извличане на обобщени данни за транзакциите с гориво и NFR
Заявка за ценообразуване на базата на обем и правила за бонуси
Извличане на позиции за такси и обобщени данни за таксите
Достъп до изключения, свързани с карти и транзакции
Анализ на данните за използването на картите и разходите
Поддръжка на заявки за транзакции с няколко плащатели

Важно съобщение - OAuth 2.0

ВАЖНО: OAuth 2.0 вече е стандартният метод за удостоверяване

Нови интеграции: Използвайте OAuth 2.0 от самото начало
Съществуващи интеграции: Планирайте миграцията си към OAuth 2.0
Стари методи: Basic Auth постепенно се извежда от употреба

Свържете се с техническата поддръжка на Shell, за да получите вашите идентификационни данни за OAuth 2.0 (client_id и client_secret).

Удостоверяване

OAuth 2.0 (стандартен метод за удостоверяване)

API-то за данни за транзакции с карти на Shell използва потока за клиентски идентификационни данни на OAuth 2.0 за сигурно удостоверяване.

ПРЕДУПРЕЖДЕНИЕ: Всички клиенти трябва да планират преминаване към удостоверяване чрез OAuth 2.0. Това е препоръчителният и бъдещ метод за удостоверяване за API-то за данни за транзакции с Shell Card. Старите методи за удостоверяване постепенно се премахват.

Процес на OAuth 2.0

Стъпка 1: Получаване на токен за достъп

Искайте токен за достъп от крайната точка за OAuth токени:

POST /oauth/token
Съдържание-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret

Стъпка 2: Използване на токена за достъп в заявките към API

Authorization: Bearer 
Content-Type: application/json

Управление на токени

Най-добри практики за управление на токени:

Токените за достъп имат ограничен срок на валидност (обикновено 15 минути)
Внедрете кеширане на токени, за да избегнете ненужни заявки за токени
Обновете токените преди изтичането на валидността им, за да гарантирате непрекъсната услуга
Никога не споделяйте client_secret и не го вграждайте в код от страна на клиента

Стратегия за внедряване на OAuth 2.0

Защо да преминете към OAuth 2.0?

Предимства за сигурността:

Протокол за удостоверяване, съответстващ на индустриалните стандарти
Токените за достъп с ограничено време на действие намаляват рисковете за сигурността
При всяко заявка не се предават идентификационни данни
По-добра поддръжка за ротация и отмяна на токени

Оперативни предимства:

Подобрена мащабируемост и производителност
По-добри възможности за мониторинг и одит
Опростено управление на удостоверенията
Интеграция, готова за бъдещето

Път за миграция

Аков момента използвате остарели методи за удостоверяване, следвайте този път за миграция:

Поискайте OAuth 2.0 идентификационни данни от Техническата поддръжка на Shell
Внедрете управление на OAuth токени във вашето приложение
Извършете задълбочени тестове в тестовата/Sandbox среда
Извършвайте паралелна автентификация (OAuth + старата система) по време на прехода
Наблюдавайте и валидирайте OAuth интеграцията
Преминаване към изцяло OAuth след потвърждаване
Преустановяване на старата автентификация след успешна миграция

Среди

API-то е достъпно в две среди:

Среда	Базов URL	Цел
Производствена	https://api.shell.com	Активна производствена среда
Тестова (Sandbox)	https://api-test.shell.com/test	Среда за тестване и разработка

Съвет: Винаги тествайте интеграцията си в тестовата среда, преди да преминете към производствена среда.

Бързо стартиране

1. Получете вашите OAuth идентификационни данни

Свържете се с Техническата поддръжка на Shell
Поискайте OAuth 2.0 идентификационни данни (client_id и client_secret)
Прегледайте условията за ползване

2. Получаване на токен за достъп

Първо, получите своя OAuth токен за достъп:

Пример с cURL:

curl -X POST https://api-test.shell.com/v2/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret"

Отговор:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

3. Изпратете първото си API заявка

Пример: Извличане на транзакции с цени

Пример с cURL:

curl -X POST https://api-test.shell.com/test/transaction-data/v1/priced \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "Filters": {
 "ColCoCode": "5",
 "PayerNumber": "DE26667080",
 "InvoiceStatus": "A",
 "IncludeFees": true,
        "FromDate": "2024-12-01 00:00:00",
 "ToDate": "2025-01-20 00:00:00"
    },
    "Page": 1,
    "PageSize": 1
}'

Пример за отговор:

{
  "RequestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "Status": "SUCCESS",
  "Data": [
    {
 "AccountName": "Blue Colour Ltd",
 "AccountId": 29484,
 "AccountNumber": "DE26667080",
 "AccountShortName": "Mathew",
 "Additional1": "GBALLEGO0002452",
 "Допълнителна информация 2": "GBALLEGO0002452",
 "Допълнителна информация 3": "GBALLEGO0002452",
 "Допълнителна информация 4": "GBALLEGO0002452",
 "Разрешение за клиринг": "Null",
 "AuthorisationCode": 300796,
 "TransactionStatus": "Y",
 "DriverName": "SATTY BHAMRA",
 "CardExpiryPeriod": 2204,
 "CardExpiry": "20220101",
 "Идентификационен номер на групата на картата": 40000,
 "Име на групата на картата": "006240 FIRE BRIGHT SOLUTIONS",
 "Код на издателя": 7002,
      "CardPAN": "7002053465789891000",
 "ReleaseCode": 9,
 "CardSequenceNumber": 617,
 "CardType": "GB STD FLT NAT SINGLE R9",
 „ColCoCode“: „014“,
 „UnitDiscountInvoiceCurrency“: -0,0051,
 „ColCoExchangeRate“: 0,851858,
 „InvoiceCurrencySymbol“: „GBP“,
      "CorrectionFlag": true,
 "CRMNumber": 10,
 "CustomerCountry": "Обединено кралство",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
 "RebateonNetAmountInCustomerCurrency": 0,
 "EffectiveDiscountInCustomerCurrency": -0,22,
 "EffectiveUnitDiscountInCustomerCurrency": -0,0051,
 "UnitPriceInInvoiceCurrency": 1,1024,
      "ДДС по фактура": 0,
 "Брутна сума по фактура": 57,25,
 "Нетна сума по фактура": 47,71,
 "ДДС върху нетната сума във валутата на клиента": 9,54,
 "„Брутна единична цена на дребно за клиента“: 0,
 „Обща брутна стойност на дребно за клиента“: 57,52,
 „Обща нетна стойност на дребно за клиента“: 47,93,
      "Описание на типа на транзакцията": 9.59,
 "Отстъпка върху нетната сума във валутата на транзакцията": -0.22,
 "Ефективна отстъпка във валутата на транзакцията": -0.22,
      "Обменен курс от държава на доставка към държава на получаване": 0,
 "Карти": [
 275549
 ],
      "Отстъпказаединицаввалутатанатранзакцията": -0,005,
 "Брутнасуманатранзакцията": 57,25,
 "Нетнасуманатранзакцията": 47,71,
 "Данъкпотранзакцията": 9,54,
 "ДДС върху нетната сума": 9,54,
 "DelcoListPriceUnitNet": 0,
      "Брутна единична цена на Delco за търговия на дребно": 1,32888,
 "Единична цена в валутата на транзакцията": 1,1074,
 "Нетна единична цена на Delco за търговия на дребно": 1,1074,
 "Брутна обща стойност на Delco за търговия на дребно": 57,52,
 „DelcoRetailValueTotalNet“: 47,93,
 „TransactionCurrencySymbol“: „$“,
 „DiscountType“: 1,
 „DisputeStatus“: false,
 „IsShellSite“: false,
      "FleetIdInput": "YG67OUM",
      "IncomingProductCode": 23,
 "PostingDate": "20210802",
 "PostingTime": "14:15:22",
 "ProductCode": 30,
 "ProductName": "Безоловен бензин – със среден октанов номер",
      "Идентификатор на продуктовата група": 22,
 "Код на валутата на входящата транзакция": "GBP",
 "Описание на обекта на входящата транзакция": "Shell Broadway Ring",
 "Местоположение": "Shell Broadway Ring",
      "Име на обекта": "Shell Broadway Ring",
 "Код на обекта": 32,
 "Номер на обекта": 15,
 "Код на валутата на фактурата": "GBP",
 "Дата на фактурата": "20210802",
      "Номер на фактурата": 3201016193,
 "Гориво": true,
 "Приложим ДДС": "Y",
      "Име на платеца": "Colours Services Ltd",
 "Номер на платеца": "GB12121212",
 "Номер на главния клиент": "GB12121212",
      "PayerGroup": "H312066",
 "PayerGroupName": "12162566 - FUEL CARD SERVICE",
 "CheckDigit": 6,
 "NetInvoiceIndicator": "Y",
 "DelcoCode": 5,
 „NetworkCode“: 3,
 „PurchasedInCountry“: „Обединено кралство“,
 „SiteCountry“: „Обединено кралство“,
 „VATCountry“: „Обединено кралство“,
 „DelcoName“: „Shell U.K. Oil Products Limited“,
      "Мрежа": "Shell",
 "Въведен пробег": 0,
 "Идентификатор на оригиналната продажба": "Null",
 "Описание на идентификатора на автопарка": "YG67OUM",
 "Идентификатор на родителския клиент": 6494,
      "PINIndicator": "Y, N",
 "ProductGroupName": "Такси",
 "PurchasedInCountryCode": "GB",
      "Количество": 43,28,
 "Процент на отстъпката": 0,0022,
 "Номер на касовата бележка": 6803,
 "Флаг за възстановяване": "Y",
 "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "Latitude": 53.83606,
 "Longitude": -1.61854,
      "DelCoExchangeRate": 0.851858,
 "EuroRebateAmount": -0.258259,
 "NetEuroAmount": 56,01,
 "EuroVATAmount": 11,2,
 "ParentCustomerName": "FUEL CARD SERVICES LTD",
 "IsInvoiced": false,
 "TransactionCurrencyCode": "GBP",
      "CreditDebitCode": "D или C",
 "TransactionDate": "20210801",
      "Време на транзакцията": "12:16:58",
 "Идентификатор на позицията в транзакцията": "H305908971030",
 "Идентификатор на транзакцията": "H305908971030",
      "Type": "SALE",
 "TransactionLine": 1,
 "TransactionType": "Purchase",
 "UTCOffset": "Europe/London",
 "VATCategory": "Стандартна ставка на ДДС в Обединеното кралство",
      "VATRate": 0,2,
 "VehicleRegistration": "YG67OUM",
 "IsCancelled": "Y",
 "ColCoGrossAmount": 57,25,
 "ColCoNetAmount": 47,71,
 "ColCoVATAmount": 9,54,
      "OriginalCurrencySymbol": "$",
 "OriginalCurrencyCode": "$",
 "OriginalVATAmount": 0,
 "EmbossText": "PARKLANE PROPERTIES LTD",
      "OriginalExchangeRate": 0,
 "OriginalTransactionItemInvoiceDate": "20220202",
 "FeeTypeId": 1,
 "LineItemDescription": true,
 "FeeRuleDescription": "Simple Fee",
      "Честота": 1,
 "Идентификатор на правилото за такса": 1,
 "Дата на въвеждане в системата": "20210828",
 "Час на въвеждане в системата": "20:21:08",
 "Ръчно въвеждане": "Y",
 "Идентификационен номер на оригиналната транзакция": "Y",
 "Номер на оригиналната фактура за транзакцията": 6750802,
 "OriginalTransactionItemInvoiceId": 234,
 "PayerShortName": "FUEL CARD SERVICES LTD",
 "ReverseCharge": "Y",
 "OriginalGrossAmount": 57,25,
 "OriginalNetAmount": 57,25,
 "UnitOfMeasure": "L",
 "RoadType": "Национален път",
 "CustomerCountryIsoCode": "DE",
 "EVOperator": "Shell Recharge",
 "EVSerialId": "GBALLEGO0002452",
 "EVChargePointSerial": "GBALLEGO0002452",
 "Тип на конектора на зарядната станция": 5,
 "Описание на типа на конектора на зарядната станция": "DC 50 kW",
 "Продължителност на зареждането": "PT3205S",
      "EVChargeStartDate": "2021-08-01",
 "EVChargeStartTime": "20:08:01",
 "EVChargeEndDate": "2022-08-01",
 "EVChargeEndTime": "20:08:01",
 "HostingCollectingCompanyNumber": 0,
      "TransactionId": 0,
 "FuelOnly": true,
 "EVPrintedNumber": "ZZ2WJ53ZZ5",
 "IsRFID": true
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 5
}

Справочник за API крайни точки

Транзакции с цена

Крайна точка	Метод	Описание
/transaction-data/v1/priced	POST	Извличане на подробности за транзакции с цена, включително EV транзакции (OAuth 2.0)
/transaction-data/v1/pricedtransaction	POST	Извличане на подробности за транзакции за гориво с артикули и такси (OAuth 2.0)
/transaction-data/v1/multipayerspricedtransactions	POST	Извличане на подробности за транзакции с цена за няколко платеца (OAuth 2.0)

Често срещани случаи на употреба:

Извличане на транзакции по диапазон на датите
Филтриране по статус на фактурата (Фактурирана, Нефактурирана и др.)
Търсене по PAN на картата или регистрационен номер на превозното средство
Извличане на транзакции за зареждане на електромобили
Заявка за транзакции от различни плащатели

Обобщения на транзакциите

Крайна точка	Метод	Описание
/transaction-data/v1/pricedtransactionssummary	POST	Извличане на обобщение на транзакциите с цена за гориво и NFR с артикули и такси (OAuth 2.0)
/transaction-data/v1/cardusagesummary	POST	Извличане на анализ на разходите и обобщение на използването за дадена карта (OAuth 2.0)

Връща:

Агрегирани данни за транзакциите по период
Общи обеми и суми
Разбивка по тип и категория на продукта
Анализ на разходите по карти

Управление на таксите

Крайна точка	Метод	Описание
/transaction-data/v1/feessummary	POST	Извличане на обобщени данни за таксите за дадения платец (OAuth 2.0)

Информация за таксите:

Извличане на таксовите позиции, приложени към транзакциите
Обобщение на всички такси по период
Разбивка на таксите по тип и категория
Анализ на таксите на ниво платец

Правила,ъз основа на обема

Крайна точка	Метод	Описание
/transaction-data/v1/volumebasedpricing	POST	Извличане на настройките на правилата за такси при просрочване за дадения платец (OAuth 2.0)
/transaction-data/v1/volumebasedbonus	POST	Извличане на настройките на правилата за бонуси и асоциативни бонуси за дадения платец (OAuth 2.0)

Функции, основани на обема:

Достъп правила за ценообразуване въз основа на обема
Извличане на правила за изчисляване на бонуси
Извличане на конфигурации за асоциативни бонуси

Изключения

Крайна точка	Метод	Описание
/transaction-data/v1/изключения	POST	Извличане на изключения, свързани с карти или транзакции (OAuth 2.0)

Видове изключения:

Грешки при валидирането на транзакции
Аномалии при използването на карти
Изключения при оторизация

Често срещани случаи на употреба

В този раздел често срещаните бизнес сценарии са съпоставени с подходящите API крайни точки, за да ви помогнат бързо да определите кои API-та да използвате за вашите конкретни нужди.

Случай на употреба 1: Ежедневно съгласуване на транзакциите/h3>
Сценарий: Трябва да съгласувате ежедневно всички транзакции от картите на вашия автопарк за счетоводни цели.

Препоръчително API: `/transaction-data/v1/priced`

Защо това API: Този краен пункт предоставя изчерпателни подробности за транзакциите, включително транзакции за зареждане на електромобили, поддържа гъвкаво филтриране по дата и включва както фактурирани, така и нефактурирани транзакции. Идеален е за ежедневно съгласуване с поддръжка на пагинация за големи масиви от данни.

Ключови параметри:

`PostingDateFrom` и `PostingDateTo` – Задайте вчерашната дата

`InvoiceStatus` – Използвайте „A“ за всички транзакции

`PageSize` – Задайте стойност 100 за ефективно извличане на данни

Пример за употреба 2: Валидиране и проверка на фактури

Сценарий: Получили сте фактура и трябва да проверите всички подробности по транзакцията, включително такси и начисления.

Препоръчително API: /transaction-data/v1/pricedtransaction

Защо това API: Специално проектиран да предоставя подробна информация за транзакциите с гориво, включително артикулите от продажбата и всички свързани такси. Идеален за валидиране на фактури, тъй като съответства на структурата на фактурата.

Ключови параметри:

InvoiceNumber – Конкретната фактура, която трябва да се валидира
Дата на фактурата – Дата на фактурата от вашата сметка
IncludeFees – Задайте стойност „true“, за да видите всички позиции с такси

Пример за употреба 3: Анализ и отчитане на разхода на гориво

Сценарий: Трябва да анализирате моделите на разхода на гориво в целия си автопарк за изминалия месец, за да оптимизирате маршрутите и да намалите разходите.

Препоръчителни API-та:

/transaction-data/v1/pricedtransactionssummary – За обобщени данни

Защо тези API-та: Крайните точки за обобщение предоставят обобщени данни по продукт, група обекти и период, което ги прави идеални за анализ на тенденциите, без да се налага обработката на големи обеми транзакции.

Ключови параметри:

PostingDateFrom и PostingDateTo – Задайте последните 30 дни
ProductCode – Филтриране по конкретни видове гориво
ProductGroupName – Групиране по категории горива

Пример за употреба 4: Управление на множество автопаркове

Сценарий: Управлявате множество подсметки или платецки профили и се налага да извлечете данни за транзакциите от всички тях с цел изготвяне на консолидирани отчети.

Препоръчително API: /transaction-data/v1/multipayerspricedtransactions

Защо това API: Специално проектирано за извличане на транзакции от множество платецки профили с едно-единствено API-извикване, което значително намалява броя на заявките и подобрява производителността при сценарии с множество автопаркове.

Ключови параметри:

Сметки – Масив от идентификатори и номера на платец (максимум 10 платеца)
Статус на фактуратаСтатус – „A“ за всички транзакции
PostingDateFrom и PostingDateTo – Отчетен период

Пример за употреба 5: Наблюдение на изключения и откриване на измами

Сценарий: Искате да идентифицирате необичайни модели на транзакции, като например транзакции с висока стойност, прекомерни количества гориво или карти с необичайна употреба, за да предотвратите измами или злоупотреби.

Препоръчително API: /transaction-data/v1/exceptions

Защо това API: Създадено специално за идентифициране на транзакции, които надвишават определени прагове, което го прави идеално за мониторинг на изключения и потенциални измами.

Ключови параметри:

Условие – Задайте типа на прага (ValueGreaterThan, VolumeGreaterThan и др.)
Стойност – Определете праговата
Тип на изхода – „Транзакция“ за изключения при транзакции
TransactionsFromDate и TransactionsToDate - Период на наблюдение

Пример за употреба 6: Анализ на такси и комисионни

Сценарий: Трябва да разберете всички такси и комисионни, наложени върху вашата сметка, за да идентифицирате възможности за спестяване на разходи или да проверите фактурирането.

Препоръчително API: /transaction-data/v1/feessummary

Защо този API: Предоставя обобщена информация за таксите по вид такса, продуктова група и група такси, което улеснява анализа на структурите на таксите и идентифицирането на областите с високи разходи.

Ключови параметри:

InvoiceStatus – „I“ само за такси, за които е издадена фактура
FeeTypeGroup – Филтриране по „Такси по карти“, „Такси по сметки“ и др.
PostingDateFrom и PostingDateTo – Период на анализ

Пример за употреба 7: Проследяване на разходите по отделни карти

Сценарий: Шофьор иска историята на транзакциите си за последните 6 месеца или вие трябва да анализирате моделите на разходите за конкретна карта.

Препоръчително API: /transaction-data/v1/cardusagesummary

Защо това API: Предоставя подробен анализ на разходите по отделни карти за последните 7 месеца, групирани по обект и продукт, което е идеално за отчети на ниво карта.

Ключови параметри:

CardId или PAN - Конкретна карта за анализ
CardExpiry – За допълнителна валидация
AccountId – Незадължителен филтър за акаунт

Пример за употреба 8: Проверка на правото на ценообразуване на базата на обем

Сценарий: Искате да проверите дали вашият акаунт отговаря на изискванията за ценови нива, базирани на обем, и да разберете текущите си нива на потребление спрямо определените прагове.

Препоръчително API: /transaction-data/v1/volumebasedpricing

Защо този API: Показва правилата за такси за просрочени плащания, конфигурациите на нивата и текущото потребление по обем, което ви помага да разберете ценовите структури и да планирате как да достигнете по-добри нива.

Ключови параметри:

PayerNumber – Вашата сметка на платец
IncludeHistory – Задайте на „true“, за да видите историческите изчисления
IncludeCurrentPeriodVolume - Задайте на „true“, за да видите разбивка по месеци

Пример за употреба 9: Проследяване на бонуси и отстъпки

Сценарий: Имате споразумения за бонуси, базирани на обем, и искате да проследявате напредъка си към праговете за бонуси и да преглеждате вече спечелените бонуси.

Препоръчително API: /transaction-data/v1/volumebasedbonus

Защо този API: Предоставя пълни подробности за правилата за бонуси, потреблението за текущия период и историческите изчисления на бонусите, което ви позволява да оптимизирате покупките си, за да максимизирате бонусите.

Ключови параметри:

PayerNumber - Вашата сметка на платеца
IncludeHistory - Задайте на „true“, за да видите минали изплащания на бонуси
IncludeCurrentPeriodVolume – Задайте „true“, за да проследявате напредъка за текущия период

Примери за употреба

Пример 1: Извличане на транзакции с цена (включително EV)

Заявка:

POST /transaction-data/v1/priced

{
  "PageSize": 1,
  "Page": 1,
  "Filters": {
    "ColCoCode": "5",
    "ColCoId": 5,
    "InvoiceStatus": "A",
    "PayerNumber": "DE26685263",
    "AccountId": 29484,
    "AccountNumber": "DE26667080",
    "CardPAN": "7002051006629890645",
    "FromDate": "2022-01-01 00:00:00",
    "ToDate": "2022-01-31 00:00:00",
    "IncludeFees": true
  }
}

Отговор:

{
  "RequestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "Status": "SUCCESS",
  "Data": [
    {
 "AccountName": "Blue Colour Ltd",
 "AccountId": 29484,
      "AccountNumber": "DE26667080",
 "AccountShortName": "Mathew",
 "Additional1": "GBALLEGO0002452",
 "Additional2": "GBALLEGO0002452",
 "Допълнителна информация 3": "GBALLEGO0002452",
 "Допълнителна информация 4": "GBALLEGO0002452",
 "Разрешение за клиринг": "Null",
 "AuthorisationCode": 300796,
 "TransactionStatus": "Y",
 "DriverName": "SATTY BHAMRA",
 "CardExpiryPeriod": 2204,
 "CardExpiry": "20220101",
 "CardGroupId": 40000,
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "IssuerCode": 7002,
      "CardPAN": "7002053465789891000",
 "ReleaseCode": 9,
      "CardSequenceNumber": 617,
 "CardType": "GB STD FLT NAT SINGLE R9",
      "ColCoCode": "014",
 "UnitDiscountInvoiceCurrency": -0,0051,
 "ColCoExchangeRate": 0,851858,
 "InvoiceCurrencySymbol": "GBP",
 "CorrectionFlag": true,
 "CRMNumber": 10,
 "CustomerCountry": "Обединено кралство",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
      "Отстъпка върху нетната сума във валутата на клиента": 0,
 "Ефективна отстъпка във валутата на клиента": -0,22,
 "Ефективна отстъпка на единица във валутата на клиента": -0,0051,
 "Единична цена във валутата на фактурата": 1,1024,
 „ДДС по фактура“: 0,
 „Брутна сума по фактура“: 57,25,
 „Нетна сума по фактура“: 47,71,
 „ДДС върху нетната сума във валутата на клиента": 9,54,
 "Брутна единична цена на дребно за клиента": 0,
 "Обща брутна стойност на дребно за клиента": 57,52,
 "Обща нетна стойност на дребно за клиента": 47,93,
      "Описание на типа на транзакцията": 9,59,
 "Отстъпка върху нетната сума във валутата на транзакцията": -0,22,
 "Ефективна отстъпка във валутата на транзакцията": -0,22,
 "Обменен курс от валутата на доставчика към валутата на получателя": 0,
 "Карти": [
 275549
 ],
 "Отстъпка на единица в валутата на транзакцията": -0,005,
 "Брутна сума на транзакцията": 57,25,
 "Нетна сума на транзакцията": 47,71,
      "Данък по транзакцията": 9,54,
      "ДДС върху нетната сума": 9,54,
 "DelcoListPriceUnitNet": 0,
 "DelcoRetailPriceUnitGross": 1,32888,
 "UnitPriceInTransactionCurrency": 1,1074,
 „„DelcoRetailPriceUnitNet“: 1,1074,
 „DelcoRetailValueTotalGross“: 57,52,
 „DelcoRetailValueTotalNet“: 47,93,
 „TransactionCurrencySymbol“: "$",
 "Тип отстъпка": 1,
      "Статус на спор": false,
 "Дали е бензиностанция": false,
 "Идентификатор на автопарка": "YG67OUM",
 "Код на входящия продукт": 23,
 "Дата на публикуване": "20210802",
      "Време на публикуване": "14:15:22",
 "Код на продукта": 30,
 "ProductName": "Безоловен бензин – със среден октанов номер",
 "ProductGroupId": 22,
 "IncomingCurrencyCode": "GBP",
 "IncomingSiteDescription": "Shell Broadway Ring",
 "Location": "Shell Broadway Ring",
      "Име на обекта": "Shell Broadway Ring",
 "Код на обекта": 32,
 "Номер на обекта": 15,
 "Код на валутата на фактурата": "GBP",
 "Дата на фактурата": "20210802",
      "Номер на фактурата": 3201016193,
 "Гориво": true,
      "VATApplicable": "Y",
 "PayerName": "Colours Services Ltd",
 "PayerNumber": "GB12121212",
 "ParentCustomerNumber": "GB12121212",
 "PayerGroup": "H312066",
 "Име на групата на платеца": "12162566 - УСЛУГА ЗА ГОРИВНИ КАРТИ",
 "Контролна цифра": 6,
 "Индикатор за нетна фактура": "Y",
 "Код на Delco": 5,
      "NetworkCode": 3,
 "PurchasedInCountry": "Обединено кралство",
 "SiteCountry": "Обединено кралство",
 "VATCountry": "Обединено кралство",
 "DelcoName": "Shell U.K. Oil Products Limited",
      "Мрежа": "Shell",
 "Въведен пробег": 0,
 "Идентификатор на оригиналната продажба": "Null",
 "Описание на идентификатора на автопарка": "YG67OUM",
 "ParentCustomerId": 6494,
 "PINIndicator": "Y, N",
 "ProductGroupName": "Такси",
      "PurchasedInCountryCode": "GB",
 "Quantity": 43,28,
 "RebateRate": 0,0022,
 "ReceiptNumber": 6803,
 "RefundFlag": "Y",
      "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "Latitude": 53.83606,
      "Дължина": -1,61854,
 "Обменен курс на доставчика": 0,851858,
 "Сума на отстъпката в евро": -0,258259,
      "NetEuroAmount": 56,01,
 "EuroVATAmount": 11,2,
 "ParentCustomerName": "FUEL CARD SERVICES LTD",
 "IsInvoiced": false,
      "Код на валутата на транзакцията": "GBP",
 "Код на кредитно-дебитното плащане": "D или C",
 "Дата на транзакцията": "20210801",
 "Час на транзакцията": "12:16:58",
 „TransactionItemId“: „H305908971030“,
 „TrnIdentifier“: "H305908971030",
 "Type": "SALE",
 "TransactionLine": 1,
 "TransactionType": "Purchase",
 "UTCOffset": "Europe/London",
 "VATCategory": "Стандартна ставка на ДДС в Обединеното кралство",
 "VATRate": 0,2,
 "VehicleRegistration": "YG67OUM",
 "IsCancelled": "Y",
 "ColCoGrossAmount": 57,25,
 "ColCoNetAmount": 47,71,
 "ColCoVATAmount": 9,54,
      "OriginalCurrencySymbol": "$",
 "OriginalCurrencyCode": "$",
      "OriginalVATAmount": 0,
 "EmbossText": "PARKLANE PROPERTIES LTD",
 "OriginalExchangeRate": 0,
 "OriginalTransactionItemInvoiceDate": "20220202",
      "Идентификатор на типа такса": 1,
 "Описание на позицията": true,
 "Описание на правилото за такса": "Обикновена такса",
 "Честота": 1,
      "Идентификатор на правилото за такса": 1,
 "Дата на въвеждане в системата": "20210828",
 "Час на въвеждане в системата": "20:21:08",
 "Ръчно въвеждане": "Y",
 "Идентификатор на оригиналната транзакция": "Y",
 "OriginalTransactionItemInvoiceNumber": 6750802,
 "OriginalTransactionItemInvoiceId": 234,
 "PayerShortName": "FUEL CARD SERVICES LTD",
 "ReverseCharge": "Y",
 "OriginalGrossAmount": 57,25,
 "OriginalNetAmount": 57,25,
 "UnitOfMeasure": "L",
      "RoadType": "Национален път",
 "CustomerCountryIsoCode": "DE",
      "EVOperator": "Shell Recharge",
 "EVSerialId": "GBALLEGO0002452",
 "EVChargePointSerial": "GBALLEGO0002452",
      "Тип на конектора на зарядната станция": 5,
 "Описание на типа на конектора на зарядната станция": "DC 50 kW",
 "Продължителност на зареждането": "PT3205S",
 "EVChargeStartDate": "2021-08-01",
 "EVChargeStartTime": "20:08:01",
 "EVChargeEndDate": "2022-08-01",
 "EVChargeEndTime": "20:08:01",
 "HostingCollectingCompanyNumber": 0,
 "TransactionId": 0,
 "FuelOnly": true,
      "EVPrintedNumber": "ZZ2WJ53ZZ5",
 "IsRFID": true
    }
  ],
  "Page": 3,
  "PageSize": 30,
  "TotalPages": 5
}

Пример 2: Извличане на подробности за транзакция за гориво

Заявка:

POST /transaction-data/v1/pricedtransaction

{
  "Filters": {
    "ColCoCode": 14,
    "InvoiceStatus": "A",
    "PayerId": 12345,
    "PayerNumber": "NL10042616"
  },
  "Page": 1,
  "PageSize": 50
}

Отговор:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Transactions": [
 {
          "Type": "SalesItem /FeeItem",
 "CardId": 0,
 "CardPAN": "7002051006629891000",
 "CardExpiry": "2026-06-16",
          "Дата на транзакцията": "2026-06-16",
 "Време на транзакцията": "string",
 "UTCOffset": "string",
          "FleetIdInput": "XYZ1234",
 "OdometerInput": 12345,
 "DriverName": "ANDREW GILBERRY",
          "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "$",
 "TransactionCurrencyCode": "GBP",
 "TransactionCurrencySymbol": "$",
 "Нетна сума на транзакцията": 0,
 "Данък върху транзакцията": 0,
 "Брутна сума на транзакцията": 0,
 "Нетна сума на фактурата": 0,
          "ДДС по фактура": 0,
 "Брутна сума по фактура": 0,
 "Страна на покупка": "Германия",
 "Идентификационен номер на сметката": 29484,
 "AccountNumber": "GB99215176",
 "AccountName": "MATTHEW ALGIE & COMPANY LIMITED",
 "AccountShortName": "string",
 "Quantity": 0,
 "FuelProduct": true,
          "Единична цена във валутата на транзакцията": 0,
 "Единична цена във валутата на фактурата": 0,
 "Единична отстъпка във валутата на транзакцията": 0,
 "Единична отстъпка във валутата на фактурата": 0,
          "IsInvoiced": true,
 "InvoiceNumber": "S04500493",
 "InvoiceDate": "string",
 "SiteCode": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Име на обекта": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Страна на обекта": "Германия",
          "Местоположение": {
 "Ширина": "37.4224764",
            "Дължина": "122.0842499"
 },
 "Име на група карти": "006240 FIRE BRIGHT SOLUTIONS",
 "Номер на разписка": "1234",
 "ProductCode": "10 - TMF такси",
 "ProductName": "Безоловен - с високо октаново число",
 "ProductGroupId": 1,
 "ProductGroupName": "Родителска продуктова група",
          "DelCoExchangeRate": 0,
 "ColCoExchangeRate": 0,
 "IsShellSite": true,
 "Network": "100013\tSTEINDORFER",
 "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "PostingDate": "string",
 "IssuerCode": "7002",
          "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
 "CustomerCountry": "Нидерландия",
 "ReleaseCode": "8",
 "CardGroupId": "string",
          "CardSequenceNumber": "2",
 "CheckDigit": "string",
 "FleetIDDescription": "string",
 "VATRate": "0,20 за 20%",
 "VATCategory": "1-Без ДДС“,
 „ДДС върху нетната сума“: 0,
 „Страна на ДДС“: „Нидерландия",
 "EffectiveDiscountInTrxCurrency": 0,
 "TransactionType": "Покупка при представяне на картата, в противен случай – празно",
 "PINIndicator": "„Използван ПИН“",
 "VATApplicable": "Y",
          "Индикатор за нетна фактура": "Y",
 "Код на валутата на клиента": "GBP",
 "Символ на валутата на клиента": "£",
 "Ефективна отстъпка на единица във валутата на клиента": 0,
 "Ефективна отстъпка във валутата на клиента": 0,
          "ДДС върху нетната сума във валутата на клиента": 0,
 "Тип отстъпка": "2 пенса на единица",
 "Статус на транзакцията": "U",
 "Идентификатор на артикула": 18315958002,
 "Група на платеца": "string",
 "PayerGroupName": "12119008 - SHELL GROUP OF COMPANIES",
 "RefundFlag": "string",
 "OriginalSalesItemId": "string",
          "Име на дистрибутора": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "Код на дистрибутора": "14",
 "PayerNumber": "NL10042616",
 "PayerName": "V.M. LE COMTE",
 "CardExpiryPeriod": "1901",
 "AuthorisationCode": "1011256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
 "AllowClearing": "Y",
          "CRMNumber": "string",
 "DisputeStatus": "Без спор",
 "RebateRate": 28,279,
 "DelCoToColCoExchangeRate": 1,
 "NetEuroAmount": 0,
 "EuroVATAmount": 0,
          "ParentCustomerNumber": "string",
 "ParentCustomerName": "string",
 "ParentCustomerId": 0,
 "IncomingSiteNumber": "100021",
 "IncomingSiteDescription": "HN3 INTI_02-82.02",
 "IncomingCurrencyCode": "GBP",
 "IncomingProductCode": "30",
 "CreditDebitCode": "D",
 "CorrectionFlag": "Y",
 "Additional1": "string",
 "Additional2": "string",
 "Additional3": "string",
 "Additional4": "string",
 "RebateonNetAmountInCustomerCurrency": -0,735,
 "Отстъпка върху нетната сума във валутата на транзакцията": "AVEE PTUAZONW CUBFAO COSFS",
 "Идентификатор на транзакцията": "string",
 "Тип на картата": "string",
          "DelcoListPriceUnitNet": 30,5,
 "DelcoRetailPriceUnitNet": 1,921,
          "DelcoRetailPriceUnitGross": 0,
 "DelcoRetailValueTotalNet": 0,
 "DelcoRetailValueTotalGross": 0,
          "CustomerRetailPriceUnitGross": 0,
 "CustomerRetailValueTotalNet": 0,
 "EVPrintedNumber": "3792",
 "IsRFID": true,
 "TokenTypeDescription": "string"
 }
 ]
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 15
}

Пример 3: Извличане на обобщение на транзакциите с цена

Заявка:

POST /transaction-data/v1/pricedtransactionssummary

{
    "Filters": {
 "ColCoCode": 9,
 "PayerId": 12,
 "InvoiceStatus": "A",
 "FromDate": "2024-03-20",
        "ToDate": "2024-09-17",
 "PurchasedInCountryCode": "AT"
    }
}

Отговор:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "ProductId": 1234,
 "ProductCode": "10",
 "ProductName": "Дизел AGO",
 "ProductGroupId": 1,
 "ProductGroupName": "Горива",
      "TotalFuelQuantity": 1250,75,
 "TotalNetAmount": 5420,50,
      "TotalGrossAmount": 6504,60,
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£",
 "CustomerRetailValueTotalNet": 5420,50,
 "Обща брутна стойност за клиента": 6504,60
    }
  ]
}

Пример 4: Извличане на обобщение на цените

Заявка:

 POST /transaction-data/v1/pricedsummary
    
    {
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "CardId": 275549,
    "FromDate": "20240225",
    "ToDate": "20240225",
    "FuelOnly": false
  }
}

Отговор:

{
    "RequestId": "5f1bded6-416d-4478-ab7f-33905d7b5d4b",
    "Status": "SUCCESS",
    "Data": [
 {
 "CustomerRetailValueTotalGross": 114,13,
 "CustomerRetailValueTotalNet": 95,11,
 "InvoiceCurrencyCode": "EUR",
 "InvoiceCurrencySymbol": "€",
 "ProductCode": "21",
 "ProductGroupId": 3,
 "ProductGroupName": "Бензин за автомобили",
 "ProductId": 21,
 "ProductName": "Без олово – с високо октаново число",
            "Идентификатор на група бензиностанции": 104,
 "Име на група бензиностанции": "Бензиностанции Shell по подразбиране в Австрия",
 "Общо количество гориво": 17,0,
 "Обща брутна сума": 114,13,
 "Обща нетна сума": 95,11
 }
    ]
}

Пример 5: Извличане на транзакции с цени за няколко платеца

Заявка:

POST /transaction-data/v1/multipayerspricedtransactions

{
  "ColCoCode": 86,
  "Accounts": [
    {
      "PayerId": 12345,
 "PayerNumber": "GB987654322"
    },
    {
 "PayerId": 12346,
 "PayerNumber": "GB000000124"
    }
  ],
  "InvoiceStatus": "A",
  "FromDate": "20220101",
  "ToDate": "20220131",
  "PageSize": 50,
  "Page": 1
}

Отговор:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Transactions": [
 {
 "Type": "SalesItem"
 }
      ],
 "CardId": 275549,
 "CardPAN": "7002051006629891000",
 "CardExpiry": "20250812",
 "Дата на транзакцията": "20250812",
 "Време на транзакцията": "14:30:45",
      "UTCOffset": "+01:00:00",
 "FleetIdInput": "XYZ1234",
 "OdometerInput": 12345,
 "DriverName": "ANDREW GILBERRY",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£",
 "TransactionCurrencyCode": "GBP",
 "TransactionCurrencySymbol": "£",
 "Нетна сума на транзакцията": 47,71,
 "Данък върху транзакцията": 9,54,
 "Брутна сума на транзакцията": 57,25,
 "Нетна сума на фактурата": 47,71,
      "ДДС по фактура": 9,54,
 "Брутна сума по фактура": 57,25,
 "Страна на покупка": "Германия",
 "Идентификационен номер на сметката": 29484,
 "Номер на сметката": "GB99215176",
      "AccountName": "MATTHEW ALGIE & COMPANY LIMITED",
 "AccountShortName": "MATTHEW",
 "Quantity": 43,28,
      "FuelProduct": true,
 "UnitPriceInTransactionCurrency": 1,1074,
 "UnitPriceInInvoiceCurrency": 1,1024,
      "Отстъпка за единица във валутата на транзакцията": -0,005,
 "Отстъпка за единица във валутата на фактурата": -0,0051,
      "Фактурирано": true,
 "Номер на фактурата": "S04500493",
 "Дата на фактурата": "20250815 09:30:00",
      "SiteCode": "050001",
 "SiteName": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "SiteCountry": "Germany",
 "Location": {
        "Latitude": "53.83606",
 "Longitude": "-1.61854"
 },
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "ReceiptNumber": "6803",
      "ProductCode": "10",
 "ProductName": "Безоловен - с високо октаново число",
 "ProductGroupId": 2,
 "ProductGroupName": "Всички горива",
 "DelCoExchangeRate": 0.851858,
 "ColCoExchangeRate": 0.851858,
      "IsShellSite": true,
 "Network": "SHELL",
 "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "PostingDate": „20250812 14:30:45“,
 „IssuerCode“: „7002“,
 „PurchasedInCountryCode“: „DE“,
 „CustomerCountryCode“: „NL“,
 „CustomerCountry“: „Нидерландия“,
      "ReleaseCode": "8",
 "CardGroupId": "40000",
 "CardSequenceNumber": "617",
 "CheckDigit": "6",
      "Описание на идентификатора на флота": "YG67OUM",
 "Ставка на ДДС": 0,2,
 "Категория на ДДС": "1-Стандартна ставка",
 "ДДС върху нетната сума": 9,54,
 "Страна на ДДС": "Нидерландия",
 "Действителна отстъпка във валутата на транзакцията": -0,22,
 "Тип на транзакцията": "Покупка",
      "PINIndicator": "Използван ПИН",
 "VATApplicable": "Y",
 "NetInvoiceIndicator": "N",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
 "EffectiveUnitDiscountInCustomerCurrency": -0,0051,
      "Ефективна отстъпка във валутата на клиента": -0,22,
 "ДДС върху нетната сума във валутата на клиента": 9,54,
 "Тип отстъпка": "2 пенса на единица",
 "Статус на транзакцията": "I",
 "Идентификационен номер на артикулаId": 18315958002,
 "PayerGroup": "H312066",
 "PayerGroupName": "12119008 - SHELL GROUP OF COMPANIES",
 "RefundFlag": "N",
 "OriginalSalesItemId": null,
 "DelcoName": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
      "DelcoCode": "014",
 "PayerNumber": "GB987654322",
 "PayerName": "V.M. LE COMTE",
 "CardExpiryPeriod": "2504",
 „AuthorisationCode“: „011256“,
 „TransactionId“: „io9KVXk1UkW57XWKyeaHHg“,
 „TransactionLine“: „1“,
      "Разрешение за клиринг": "Y",
 "CRM номер": null,
 "Статус на спора": "Без спор",
      "Процент на отстъпка": 28,279,
 "Обменен курс от доставчик към получател": 1,
 "Нетна сума в евро": 56,01,
      "EuroVATAmount": 11,2,
 "ParentCustomerNumber": "GB12121212",
      "Име на главния клиент": "FUEL CARD SERVICES LTD",
 "Идентификационен номер на главния клиент": 6494,
 "Номер на входящия обект": "100021",
 "Описание на входящия обект": "HN3 INTI_02-82.02",
 "IncomingCurrencyCode": "GBP",
 "Код на входящия продукт": "30",
 "Код на кредит/дебит": "D",
 "Флаг за корекция": "N",
 "Допълнително1": "GBALLEGO0002452",
      "Допълнителна информация 2": null,
 "Допълнителна информация 3": null,
 "Допълнителна информация 4": null,
 "Отстъпка върху нетната сума във валутата на клиента": -0,735,
 „Отстъпка върху нетната сума във валутата на транзакцията“: -0,735,
 „Идентификатор на транзакцията“: „H305908971030“,
 „Тип карта“: „GB STD FLT NAT SINGLE R9“,
 "DelcoListPriceUnitNet": 30,5,
 "DelcoRetailPriceUnitNet": 1,1074,
 "DelcoRetailPriceUnitGross": 1,32888,
 "DelcoRetailValueTotalNet": 47,93,
 "DelcoRetailValueTotalGross": 57,52,
 "CustomerRetailPriceUnitGross": 1,32888,
 "CustomerRetailValueTotalNet": 47,93,
      "EVPrintedNumber": "3792",
 "IsRFID": true,
 "TokenTypeDescription": "Fleet Card"
    }
  ],
  "Page": 1,
  "PageSize": 20,
  "TotalPages": 15,
  "TotalRecords": 300
}

Пример 6: Извличане на правила за ценообразуване на базата на обем

Заявка:

POST /transaction-data/v1/volumebasedpricing

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "IncludeHistory": true,
  "IncludeCurrentPeriodVolume": true
}

Отговор:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Configuration": [
 {
 "PricingAccountId": 123456,
 "PricingAccountNumber": "GB000000123",
          "PricingAccountShortName": "ABCD1234",
 "PricingAccountFullName": "ABCD1234",
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "FeeRuleDateEffective": "20231223",
 "FeeRuleDateTerminated": "20231223",
          "BonusPaidTo": "1-Pay to Payer",
 "BonusPaidToAccountId": 123456,
          "Номер на сметката, на която е изплатен бонусът": "GB000000123",
 "Кратко име на сметката, на която е изплатен бонусът": "12345",
          "Пълно име на сметката, на която е изплатен бонусът": "GB000000123",
 "Честота": "3-Седмично – понеделник",
 "Дата на следващото изчисление": "20231223",
 ""Предишна дата на изчисление": "20231223",
 "Основа на правилото за такса": "3-Еднократна сума",
 "Код на валутата по правилото за такса": "GBP",
 "Символ на валутата по правилото за такса": "£",
 "FeeRuleAvailableFrom": "20231223",
 "FeeRuleAvailableTo": "20231223",
 "FeeRuleLocations": [
 {
 "DelcoId": 866,
              "Country": "Обединено кралство",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "SiteId": 100007,
              "Име_на_обект": "VALERO ENERGY LTD"
 }
 ],
 "Продукти_по_правила_за_такси": [
 {
 "Идентификатор_на_група_продукти": 3,
              "ProductGroupName": "Бензин за автомобили",
 "ProductCode": "30 за дизел AGO",
 "ProductId": "30 за дизел AGO",
 "ProductName": "Дизел AGO"
 }
 ],
 "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
 "TierMaximum": 1234,
 "Value": 1234.12
 }
 ]
 }
      ],
 "CurrentPeriodConsumption": [
 {
          "Идентификатор на правилото за такса": 12345,
 "Описание на правилото за такса": "NL/GAGO/D018/UP0.0120>1",
 "Идентификатор на правилото за цена": 100005,
 "Описание на правилото за цена": "PL/GAGO/GMOT/UL0.055",
 "TotalVolume": 10000,78,
 "NextFeeCreationDate": "20231223"
 }
      ],
 "History": [
 {
 "FromDate": "20231223",
 "ToDate": "20231223",
 "FeesRuleID": 8081,
 "FeesRuleDescription": "PT/P067/D120/P4.0",
 "TotalVolume": 12356.66
 }
 ],
 "Warnings": [
 {
 "Message": "Системата е изключена за актуализация.",
 "Type": "System Outage"
 }
 ]
    }
  ]
}

Пример 7: Извличане на правила за бонуси на базата на обем

Заявка:

POST /transaction-data/v1/volumebasedbonus

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "IncludeHistory": true,
  "IncludeCurrentPeriodVolume": true
}

Отговор:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Configuration": [
 {
 "PricingAccountId": 123456,
          "PricingAccountNumber": "GB000000123",
 "PricingAccountShortName": "MATTHEW",
 "PricingAccountFullName": "MATTHEW",
 "FeeRuleId": 1,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "FeeRuleDateEffective": "20231223",
 "FeeRuleDateTerminated": "20231223",
 "BonusPaidTo": "1-Плащане към платеца",
 "Идентификатор на сметката, на която се изплаща бонусът": 123456,
 "Номер на сметката, на която се изплаща бонусът": "GB000000123",
 "Кратко име на сметката, на която е изплатен бонусът": "12345",
 "Пълно име на сметката, на която е изплатен бонусът": "GB000000123",
          "Честота": "3-Седмично – понеделник",
 "Следваща дата на изчисление": "20231223",
 "Предишна дата на изчисление": "20231223",
 "Основа на правилото за такса": "3-Еднократна сума",
 "FeeRuleCurrencyCode": "GBP",
 "FeeRuleCurrencySymbol": "£",
 "FeeRuleAvailableFrom": "20231223",
 "FeeRuleAvailableTo": "20231223",
          "Места за прилагане на правилото за такса": [
 {
 "Идентификатор на Delco": 866,
 "Страна": "Обединено кралство",
              "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "SiteId": 100007,
 "SiteName": "VALERO ENERGY LTD"
 }
 ],
 "FeeRuleProducts": [
 {
              "ProductGroupID": 3,
 "ProductGroupName": "Бензин за автомобили",
 "ProductCode": "30 за дизел AGO",
 "ProductId": "30 за дизел AGO",
 "ProductName": "Дизел AGO"
 }
          ],
 "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
 "TierMaximum": 1234,
              "Стойност": 1234,12
 }
 ],
 "Свързани сметки": [
 {
 "Идентификатор на свързана сметка": 12345,
              "AssociatedAccountNumber": "GB000000123",
 "AssociatedAccountShortName": "Кратко име на сметката",
 "AssociatedAccountFullName": "Пълно име на сметката"
 }
 ]
 }
 ],
      "CurrentPeriodConsumption": [
 {
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "Month": 1,
          "Year": 2018,
 "TotalVolume": 10000.78
 }
 ],
 "HistoricalBonusPaid": [
 {
 "PayerId": 12345,
 "PayerNumber": "GB000000123",
 "PayerShortName": "Jorden",
 "PayerFullName": "MATTHEW",
 "AccountId": 123456,
          "AccountNumber": "GB000000123",
 "AccountShortName": "SALT",
 "AccountFullName": "ABCD1234",
 "InvoiceAccountId": 12345,
 "Номер на сметката по фактура": "GB000000123",
 "Кратко име на сметката по фактура": "DFE1234",
 "Пълно име на сметката по фактура": "AZAD PVT LMT",
          "Идентификатор на правило за такса": 12345,
 "Описание на правило за такса": "NL/GAGO/D018/UP0.0120>1",
 "Дата от": "20231223",
          "ToDate": "20231223",
 "BonusPaidTo": "5-Изплащане на свързани клиенти",
 "FeeItemId": 12345,
          "FeeRuleBasis": "2-Процент от надценката",
 "FeeItemCurrencyCode": "GBP",
 "FeeItemCurrencySymbol": "$",
          "ProratedVolume": 123,12,
 "TotalVolume": 123,12,
 "FeeProduct": "1562-Бонус за дизел Shell",
          "Брутна сума по фактура": 123,12,
 "Нетна сума по фактура": 123,12,
          "InvoiceVATAmount": 123,12,
 "IsFeeCancelled": true,
 "FeeItemTierProratedVolume": 123,12,
 "FeeItemTierTotalVolume": 123,12,
          "TierMinimum": 123,
 "TierRate": 123.12
 }
 ]
    }
  ],
  "Warnings": [
    {
 "Message": "Системата е изключена за актуализация.",
 "Type": "System Outage"
    }
  ]
}

Пример 8: Извличане на обобщение на таксите

Заявка:

POST /transaction-data/v1/feessummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "CardId": 275549,
  "InvoiceStatus": "I",
  "FromDate": "20240101",
  "ToDate": "20240131",
  "FeeTypeGroup": "Такси по карта"
}

Отговор:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "FeeTypeGroup": "Такси по карта",
 "FeeTypeId": 1,
 "FeeType": "Годишна такса за карта",
 "ProductId": 1234,
 "ProductCode": "FEE",
 "ProductName": "Такса за карта",
 "TotalFeeAmount": 125.00,
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£"
    }
  ]
}

Пример 9: Извличане на изключения при транзакции

Заявка:

POST /transaction-data/v1/exceptions

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "TransactionsFromDate": "20231223",
  "TransactionsToDate": "20240131",
  "Value": 100,
  "Condition": 5,
  "OutputType": "Transaction"
}

Отговор:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "CardsExceptions": [
        {
 "AccountId": 29484,
 "CardId": 1234,
 "PAN": "ABCD1234",
          "DriverName": "ANDREW GILBERRY",
 "VRN": "34235",
 "PayerId": 123455,
          "PayerNumber": "GB000000123",
 "AccountNumber": "GB99215176",
 "AccountShortName": "MATTHEW",
 "PayerShortName": "MATTHEW",
 "Day": 2,
          "Week": 2,
 "Month": 5,
 "Year": 2017,
 "TotalTransactions": 4,
          "Общо артикули": 4,
 "Общо количество": 261,
 "Обща сума": 100,21,
 "Код на валутата": "GBP",
 "Символ на валутата": "$"
 }
      ],
 „Изключения при транзакциите“: [
 {
 „SalesItemId“: 18315958002,
 „CardId“: 1234,
 „ProductId“: 2,
 „TransactionGUID“: „ABCD1234“,
 „Дата на транзакцията": "20231223",
 "Обща брутна стойност на фактурата на клиента": 123,12,
 "PAN на картата": "7002051006629891000",
          "CardExpiry": "20311223 12:12:12",
 "TransactionTime": "12:12:12",
          "UTCOffset": "+12:12:12",
 "FleetIdInput": "XYZ1234",
 "OdometerInput": 1234,
 "DriverName": "SALT",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "$",
          "Код на валутата на транзакцията": "GBP",
 "Символ на валутата на транзакцията": "£",
          "TransactionNetAmount": 123.12,
 "TransactionTax": 123.12,
 "TransactionGrossAmount": 123.12,
 "Нетна сума по фактура": 123,12,
 "ДДС по фактура": 123,12,
 "Брутна сума по фактура": 123,1,
 „Страна на покупката“: „Франция“,
 „Идентификационен номер на сметката“: 1234,
 „Номер на сметката“: „GB99215176“,
 „Име на сметката“: „MATTHEW ALGIE & COMPANY LIMITED“,
 „AccountShortName“: „MATTHEW ALGIE & COMPANY LIMITED“,
 „Quantity“: 123,12,
 „FuelProduct“: true,
 „UnitPriceInTransactionCurrency“: 123,12,
 „UnitPriceInInvoiceCurrency": 123,12,
 "UnitDiscountTransactionCurrency": 123,12,
 "UnitDiscountInvoiceCurrency": 123,12,
 "IsInvoiced": true,
 "InvoНомер на фактурата": "S04500493",
          "Дата на фактурата": "20231223",
 "Код на обекта": "50001",
 "Име на обекта": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "Страна на обекта": "Germany",
 "Location": {
 "Lat": "37.4224764",
 "Lng": "122.0842499"
 },
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "ReceiptNumber": "1234",
 "ProductCode": "TMF Charges",
 "ProductName": "Безоловен бензин – с високо октаново число",
 "ProductGroupId": 1234,
          "ProductGroupName": "Родителска продуктова група",
 "DelCoExchangeRate": 123.12,
 "ColCoExchangeRate": 123.12,
 "IsShellSite": true,
 "Network": „Shell PH“,
 „SiteGroupId“: 202,
 „SiteGroupName“: „CZ 9100 ECONOMY NETWORK“,
          "PostingDate": "20231223 12:12:12",
 "IssuerCode": "7077 = CRT",
 "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
 „Страна на клиента“: „Нидерландия“,
 „Код на издаване“: „8 за 702188“,
 „Идентификационен номер на групата карти“: „200“,
 „Пореден номер на картата“: „2“,
          "CheckDigit": "GHE1234",
 "FleetIDDescription": "Примерно описание",
 "VATRate": 0,2,
 "VATCategory": "3 – освободено от ДДС",
 "ДДС върху нетната сума": 12,21,
 "Страна на ДДС": "Нидерландия",
 "Действителна отстъпка във валутата на транзакцията": 0,
          "TransactionType": "Покупка при физическо представяне на картата, в противен случай – празно",
 "PINIndicator": "Y",
 "VATApplicable": "Y",
 "NetInvoiceIndicator": "Y",
          "Код на валутата на клиента": "GBP",
 "Символ на валутата на клиента": "£",
 "Ефективна отстъпка на единица във валутата на клиента": 123,12,
 "Ефективна отстъпка във валутата на клиента": 123,12,
 „ДДС върху нетната сума във валутата на клиента“: 123,12,
 „Тип отстъпка“: „3-процентна“,
 „Статус на транзакцията“: „U“,
 „Група на платеца“: „12119008",
 "RefundFlag": "N",
 „Идентификатор на оригиналната продажба“: „1231“,
 „Име на дистрибутора“: „SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV“,
 „Код на дистрибутора“: „NL10042616“,
 „Име на платеца“: "V.M. LE COMTE",
 "CardExpiryPeriod": "1901",
          "Код за оторизация": "11256",
 "Идентификатор на транзакцията": "io9KVXk1UkW57XWKyeaHHg",
 "Ред на транзакцията": "1",
 "Разрешено клиринг": "Y",
          "CRMNumber": "ABCD1234",
 "DisputeStatus": "6\tВъзстановяване на сумата към сайта",
 "RebateRate": 28,279,
 "DelCoToColCoExchangeRate": 1,
          "NetEuroAmount": 37,93,
 "EuroRebateAmount": 0,
 "EuroVATAmount": 7,96,
 "ParentCustomerNumber": "DRG1234"
 }
 ]
    }
  ]
}

Пример 10: Извличане на обобщение за използването на картата

Заявка:

POST /transaction-data/v1/cardusagesummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "AccountId": 1234,
  "AccountNumber": "GB000000123",
  "CardId": 1234,
  "PAN": "7882861007636000020",
  "CardExpiry": "20311223"
}

Отговор:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "UsageSummary": [
 {
 "Date": "20170930",
 "ProductId": 1,
 "ProductCode": "2",
 "ProductName": "Diesel AGO",
 "IsFuelProduct": true,
 "SiteGroupId": 1234,
 "SiteGroupName": "UK 9500 MOTORWAY NETWORK",
          "TotalVolume": 123.12,
 "TotalGross": 123.12,
 "TotalNet": 123.12,
 "CurrencyCode": "GBP",
 "CurrencySymbol": "£",
 "ProductGroupId": 1234,
 "ProductGroupName": "Бензин за автомобили"
 }
 ]
    }
  ]
}

Обработка на грешки

Често срещани кодове за грешки

HTTP статус	Код на грешката	Описание	Решение
200	Н/Д	Статус: УСПЕХ	Н/Д
200	E0001	Грешка при валидиране	Проверете параметрите на заявката
401	E0003	Невъзможно достъп	Проверете дали OAuth токенът е валиден
403	E0003	Забранено	Проверете
404	E0005	Ресурсът не е намерен	Проверете дали URL адресът на крайната точка и ресурсът съществуват
500	E0002	Неизвестна грешка / Вътрешна грешка на сървъра	Свържете се с поддръжката

Най-добри практики

1. Въведете удостоверяване по OAuth 2.0

ВАЖНО: Всички клиенти трябва да преминат към удостоверяване по OAuth 2.0. Въведете подходящо управление на токените:

Съхранявайте токените за достъп в кеш и ги използвайте повторно до изтичане на валидността им
Обновете токените преди да изтече валидността им (препоръчително 60 секунди преди това)
Съхранявайте клиентските идентификационни данни по сигурен начин (използвайте променливи на средата или мениджър на тайни)
Никога не записвайте и не разкривайте токени за достъп в кода от страна на клиента

2. Използвайте идентификатори на заявки

Винаги включвайте уникален RequestId (в GUID формат) за проследяемостот край до край

3. Внедрете пагинация

За големи масиви от данни за транзакции използвайте пагинация, за да избегнете изтичане на времето за изчакване:

Задайте подходящ размер на страницата (PageSize) (препоръчително: 50–100 записи)
Обработвайте страниците последователно или паралелно
Обработвайте TotalPages и TotalRecords в отговорите

4. Използвайте филтрите за дата разумно

При заявки за транзакционни данни:

Ограничавайте диапазоните от дати, за да избегнете големи набори от резултати
Използвайте филтрите „FromDate“ и „ToDate“ последователно
Обмислете да извършвате заявки по месец или седмица за по-добра производителност

5. Тествайте в среда „Sandbox“

Винаги тествайте интеграцията в тестовата среда „Sandbox“, преди да преминете към производствена среда

6. Кеширайте референтните данни

Кеширайте ценообразуването на базата на обем и правилата за бонуси, за да сведете до минимум API заявките:

Тези правила се променят рядко
Освежавайте кеша периодично (например ежедневно)
Използвайте параметъра IncludeHistory само когато е необходимо

SDK и примери за код

Shell предоставя официални SDK и изчерпателни примери за код, за да ускори вашата интеграция с Transaction Data API.

Налични езици за SDK

Python - SDK с пълен набор от функции и поддръжка на OAuth 2.0
TypeScript – SDK с типова безопасност и пълни дефиниции на типовете
Java – SDK от корпоративен клас
C#/.NET - Пълна интеграция с .NET
PHP - Лесна за използване PHP библиотека
Ruby – Ruby gem за безпроблемна интеграция

Вижте официалните SDK и документация

Поддръжка и ресурси

Техническа поддръжка

Поддръжка: Техническа поддръжка на Shell
Миграция към OAuth 2.0: Поддръжка за миграция към OAuth 2.0

Документация

Получаване на помощ

Когато се свързвате с отдела за поддръжка, посочете:

Вашия client_id (никога не споделяйте client_secret или токените за достъп)
RequestId от отговора на API-то
Времева марка на заявката
Среда (Производствена/Тестова)

Последно актуализирано: 1 юли 2026 г.
Версия на документа: 1.0
Версия на API: 2.3.5

Изберете вашия език

API за транзакционни данни на картата Shell B2B Mobility – Ръководство за бързо стартиране

Вижте ощепреглед

Основни функции

Важно съобщение - OAuth 2.0

Удостоверяване

OAuth 2.0 (стандартен метод за удостоверяване)

Процес на OAuth 2.0

Стъпка 1: Получаване на токен за достъп

Стъпка 2: Използване на токена за достъп в заявките към API

Управление на токени

Стратегия за внедряване на OAuth 2.0

Защо да преминете към OAuth 2.0?

Предимства за сигурността:

Оперативни предимства:

Път за миграция

Среди

Бързо стартиране

1. Получете вашите OAuth идентификационни данни

2. Получаване на токен за достъп

Пример с cURL:

Отговор:

3. Изпратете първото си API заявка

Пример с cURL:

Пример за отговор:

Справочник за API крайни точки

Транзакции с цена

Обобщения на транзакциите

Управление на таксите

Правила,ъз основа на обема

Изключения

Често срещани случаи на употреба

Пример за употреба 2: Валидиране и проверка на фактури

Пример за употреба 3: Анализ и отчитане на разхода на гориво

Пример за употреба 4: Управление на множество автопаркове

Пример за употреба 5: Наблюдение на изключения и откриване на измами

Пример за употреба 6: Анализ на такси и комисионни

Пример за употреба 7: Проследяване на разходите по отделни карти

Пример за употреба 8: Проверка на правото на ценообразуване на базата на обем

Пример за употреба 9: Проследяване на бонуси и отстъпки

Примери за употреба

Пример 1: Извличане на транзакции с цена (включително EV)

Заявка:

Отговор:

Пример 2: Извличане на подробности за транзакция за гориво

Заявка:

Отговор:

Пример 3: Извличане на обобщение на транзакциите с цена

Заявка:

Отговор:

Пример 4: Извличане на обобщение на цените

Заявка:

Отговор:

Пример 5: Извличане на транзакции с цени за няколко платеца

Заявка:

Отговор:

Пример 6: Извличане на правила за ценообразуване на базата на обем

Заявка:

Отговор:

Пример 7: Извличане на правила за бонуси на базата на обем

Заявка:

Отговор:

Пример 8: Извличане на обобщение на таксите

Заявка:

Отговор:

Пример 9: Извличане на изключения при транзакции

Заявка:

Отговор:

Пример 10: Извличане на обобщение за използването на картата

Заявка:

Отговор:

Обработка на грешки

Често срещани кодове за грешки

Най-добри практики

1. Въведете удостоверяване по OAuth 2.0

2. Използвайте идентификатори на заявки

3. Внедрете пагинация

4. Използвайте филтрите за дата разумно

5. Тествайте в среда „Sandbox“

6. Кеширайте референтните данни