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

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

Общ преглед

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

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

Извличане на данни за транзакции за пътни такси по номер на сметка
Филтриране на транзакциите по период (начална и крайна дата)
Търсене по статус на фактурата и VRN (регистрационен номер на превозното средство)
Разширени възможности за сортиране по няколко полета
Поддръжка на разбиване на страници за големи масиви от данни
Гъвкаво филтриране по полета за оптимизиране на обема на отговора
Подробна информация за пътните такси, включително точки на влизане/излизане
Поддръжка на множество мрежи за пътни такси и оператори

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

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

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

Процес на OAuth 2.0

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

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

POST /oauth/token
Content-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
RequestId: eb621f45-a543-4d9a-a934-2f223b263c42

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

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

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

Среди

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

Среда	Базов URL	Цел
Производствена	https://api.shell.com/toll-data/v1	Производствена среда на живо
Тестване (UAT)	https://api-test.shell.com/toll-data/v1	Среда за тестване и разработка

URL адреси на OAuth токени:

Среда	URL на токена
Производствена среда	https://api.shell.com/v2/oauth/token
Тестова (UAT)	https://api-test.shell.com/v2/oauth/token

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

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

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": "eyJhbGciOi*******5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899
}

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

Пример: Търсене на транзакции за пътни такси

Пример с cURL:

curl -X POST https://api-test.shell.com/toll-data/v1/transactions/search \
  -H "Authorization: Bearer eyJhbGci******NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "RequestId: eb621f45-a543-4d9a-a934-2f223b263c42" \
  -d '{
    "Filters": {
 "ColCoCode": 86,
 "PayerNumber": "NL20016398",
        "AccountNumber": "NL20027701",
 "Filter": "All",
 "FromDate": "2026-01-01",
 "ToDate": "2026-01-31"
    },
    "Page": 1,
    "PageSize": 10
}'

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

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Page": 1,
  "TotalRecords": 150,
  "TotalPages": 15,
  "PageSize": 10,
  "Data": [
    {
 "NetworkDescription": "Societa Autostradali",
 "TollChargerCode": "410|610",
      "DelcoCode": "714",
 "DelcoName": "Shell Fleet Solutions Consorzio",
 "NetworkCode": "TLI",
      "Network": "euroShell Consortio",
 "PurchasedInCountry": "Италия",
 "PurchasedInCountryCode": "IT",
 "CardNumber": "707737*******334272",
      "CardId": 123456789,
      "CardGroupName": "Shell Fleet Solutions Consorzio",
 "VehicleRegistration": "KN 00000",
 "CostCenter": "100",
 "SystemEntryDate": "20260123",
      "Време на въвеждане в системата": "13:14:25",
 "Дата на транзакцията": "20260120",
      "TransactionTime": "10:30:00",
 "PostingDate": "20260123",
 "PostingTime": "00:00:00",
      "PayerNumber": "NL20016398",
 "AccountNumber": "NL20027701",
 "Име_на_сметката": "Име на тестова сметка",
 "Дата_на_началото": "20260120",
 "Час_на_началото": "06:47:41",
 "Дата_на_края": "20260120",
      "EndTime": "07:30:15",
 "TollGateEntry": "ROMA NORD",
 "TollGateExit": "BRENNERO",
 "DistanceDriven": "71.6",
      "Описание на маршрута": "ROMA NORD - BRENNERO",
 "Тип на транзакцията": "Пътен данък",
 "Код на продукта": "14",
 "Описание на продукта": "Пътен данък",
 "Нетна сума на транзакцията": "127,1",
      "Данък по транзакцията": "0,0",
 "Брутна сума на транзакцията": "127,1",
 "Валутен код на транзакцията": "EUR",
 "Статус на транзакцията": "Отчитане",
      "Номер на фактурата": "8600397548",
 "Дата на фактурата": "20260125",
      "Статус на фактурата": "Фактурирана",
 "Начин на плащане": "Плащане след доставка",
 "Сериен номер на ОБУ": "00049000000836932426",
      "EmissionClass": "Euro 6",
 "ContractID": "fb75eb53-46eb-450b-862e-6045002c3fa8",
      "ShellTransactionID": "04176c5c-e7b2-49c8-bcb3-23d07ba583f2",
 "TollOperator": "Toll4Europe",
      "TollDomain": "Toll4Europe",
 "TariffRelevantInformation": "Клас на превозното средство: 2, Брой оси: 2, Категория на пътя: Магистрала",
 "AdditionalTransactionInfo": "Местоположение: 1",
 "TCInvoiceNumber": "12343343",
 "TCInvoiceDate": "20260123"
    }
  ]
}

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

Транзакции за пътни такси

Крайна точка	Метод	Описание
/toll-data/v1/transactions/search	POST	Извличане на данни за транзакции за пътни такси с гъвкаво филтриране и разбиване на страници

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

Извличане на транзакции за пътни такси по диапазон от дати
Филтриране по статус на фактурата (Фактурирани, Нефактурирани, Всички)
Търсене по регистрационен номер на превозното средство (VRN)
Филтриране по група карти
Сортиране на транзакциите по няколко критерия
Изберете конкретни полета, за да оптимизирате размера на отговора

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

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

Сценарий на употреба 1: Ежедневно съгласуване на транзакциите за пътни такси

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