API Shell B2B Mobility pentru date privind tranzacțiile de taxare rutieră – Ghid de pornire rapidă

Versiunea API: 1.0.0 | Autentificare: OAuth 2.0 | Stare: Producție

Prezentare generală

API-ul Shell B2B Mobility pentru date privind tranzacțiile de taxare rutieră este un API bazat pe REST care oferă acces complet la înregistrările tranzacțiilor de taxare rutieră și la datele conexe pentru clienții Shell Mobility. Acest API permite dezvoltatorilor să preia, să filtreze, și să analizeze datele privind tranzacțiile de taxare rutieră prin intermediul programelor, în scopul reconcilierii conturilor, verificării facturării, gestionării cheltuielilor și respectării cerințelor de conformitate.

Caracteristici cheie

Preluarea datelor privind tranzacțiile de taxare rutieră după numărul de cont
Filtrarea tranzacțiilor după interval de date (date de început și de sfârșit)
Căutare după starea facturii și VRN (numărul de înmatriculare al vehiculului)
Funcții avansate de sortare pe mai multe câmpuri
Suport pentru paginare în cazul seturilor mari de date
Filtrare flexibilă pe câmpuri pentru optimizarea volumului de date al răspunsului
Detalii complete privind taxele de drum, inclusiv punctele de intrare/ieșire
Suport pentru mai multe rețele și operatori de taxare

Autentificare

OAuth 2.0 (metodă standard de autentificare)

API-ul Shell pentru date privind tranzacțiile de taxare rutieră utilizează fluxul de acreditări ale clientului OAuth 2.0 pentru autentificare securizată.

Fluxul OAuth 2.0

Pasul 1: Obținerea tokenului de acces

Solicitați un token de acces de la punctul final al tokenului OAuth:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your-client-id&client_secret=secretul-tău-de-client

Pasul 2: Utilizează tokenul de acces în solicitările API

Authorization: Bearer 
Content-Type: application/json
RequestId: eb621f45-a543-4d9a-a934-2f223b263c42

Gestionarea tokenurilor

Cele mai bune practici de gestionare a tokenurilor:

Tokenurile de acces au o durată de viață limitată (de obicei 15 minute)
Implementați stocarea în cache a tokenurilor pentru a evita solicitările inutile de tokenuri
Reîmprospătați tokenurile înainte de expirare pentru a asigura un serviciu neîntrerupt
Nu partajați niciodată client_secret-ul și nu îl încorporați în codul de pe partea clientului

Mediile de execuție

API-ul este disponibil în două medii de execuție:

Mediu	URL de bază	Scop
Producție	https://api.shell.com/toll-data/v1	Mediu de producție live
Testare (UAT)	https://api-test.shell.com/toll-data/v1	Mediu de testare și dezvoltare

URL-uri pentru tokenuri OAuth:

Mediu	URL token
Producție	https://api.shell.com/v2/oauth/token
Test (UAT)	https://api-test.shell.com/v2/oauth/token

Sfat: Testați întotdeauna integrarea în mediul de testare înainte de a trece la producție.

Începere rapidă

1. Obțineți datele de autentificare OAuth

Contactați Suportul tehnic Shell
Solicitați datele de autentificare OAuth 2.0 (client_id și client_secret)
Consultați termenii de utilizare

2. Obțineți un token de acces

Mai întâi, obțineți tokenul de acces OAuth:

Exemplu 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=ID-ul-tău-de-client&client_secret=secretul-tău-de-client"

Răspuns:

{
  "access_token": "eyJhbGciOi*******5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899
}

3. Efectuați prima solicitare API

Exemplu: Căutarea tranzacțiilor de taxare

Exemplu 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
}'

Răspuns de exemplu:

{
  "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",
      „Rețea”: „euroShell Consortio”,
 „Țară de achiziție”: „Italia”,
 „Cod țară de achiziție”: „IT”,
 „Număr card”: „707737*******334272”,
 „CardId”: 123456789,
 „CardGroupName”: „Shell Fleet Solutions Consorzio”,
 „VehicleRegistration”: „KN 00000”,
      "Centru de cost": "100",
 "Data introducerii în sistem": "20260123",
 "Ora introducerii în sistem": "13:14:25",
      "Data tranzacției": "20260120",
 "Ora tranzacției": "10:30:00",
 "Data înregistrării": "20260123",
      "Ora înregistrării contabile": "00:00:00",
 "Numărul plătitorului": "NL20016398",
 "Numărul contului": "NL20027701",
      "NumeleContului": "Numele contului de test",
 "DataÎnceperii": "20260120",
 "OraÎnceperii": "06:47:41",
 "DataÎncheierii": "20260120",
      "Ora de încheiere": "07:30:15",
 "Intrare la punctul de taxare": "ROMA NORD",
 "Ieșire la punctul de taxare": "BRENNERO",
      "DistanceDriven": "71,6",
 "RouteDescription": "ROMA NORD - BRENNERO",
 "TransactionType": "Taxă rutieră",
 "ProductCode": "14",
 "ProductDescription": "Taxă rutieră",
      "Suma netă a tranzacției": "127,1",
 "Taxa tranzacției": "0,0",
      "SumaBrutăTranzacție": "127,1",
 "CodMonedăTranzacție": "EUR",
 "StareTranzacție": "Raportare",
 "NumărFactură": "8600397548”,
 „Data facturii”: „20260125”,
 „Starea facturii”: „Facturată”,
 „Metoda de plată”: „Plată ulterioară”,
 „Număr de serie OBU”: "00049000000836932426",
      "EmissionClass": "Euro 6",
 "ContractID": "fb75eb53-46eb-450b-862e-6045002c3fa8",
      "ShellTransactionID": "04176c5c-e7b2-49c8-bcb3-23d07ba583f2",
 "TollOperator": "Toll4Europe",
      "TollDomain": "Toll4Europe",
 "TariffRelevantInformation": "Clasa vehiculului: 2, Număr de axe: 2, Categoria drumului: Autostradă",
 "AdditionalTransactionInfo": "Locație: 1",
      "TCInvoiceNumber": "12343343",
 "TCInvoiceDate": "20260123"
    }
  ]
}

Referință puncte finale API

Tranzacții de taxare

Punct final	Metodă	Descriere
/toll-data/v1/transactions/search	POST	Recuperează datele tranzacțiilor de taxare cu filtrare și paginare flexibile

Cazuri de utilizare comune:

Recuperarea tranzacțiilor de taxare pe interval de date
Filtrare după starea facturii (Facturate, Nefacturate, Toate)
Căutare după numărul de înmatriculare al vehiculului (VRN)
Filtrare după grupul de carduri
Sortare tranzacții după mai multe criterii
Selectați câmpuri specifice pentru a optimiza dimensiunea răspunsului

Cazuri de utilizare frecvente

Această secțiune corelează scenarii de afaceri frecvente cu modele de utilizare a API-ului, pentru a vă ajuta să identificați rapid modul în care puteți utiliza API-ul în funcție de nevoile dvs. specifice.

Caz de utilizare 1: Reconcilierea zilnică a tranzacțiilor de taxare rutieră

Scenariu: Trebuie să reconciliați zilnic toate tranzacțiile de taxare ale flotei dvs. în scopuri contabile.