B2B Mobility Customer Data v3.0.5 | Gyors útmutató a B2B Mobility ügyféladatokhoz

B2B Mobility ügyféladatok – Gyors útmutató

Bevezetés

A B2B Mobility ügyféladatok API egy RESTful szolgáltatás, amely lehetővé teszi az ügyfélfiókok adatainak lekérdezését és kezelését, kártyacsoportok és a kapcsolódó beállítások lekérdezését és kezelését a Shell Cards Platformon belül. Ez az API rugalmas keresési lehetőségeket biztosít, támogatja az oldalozást, és lehetővé teszi a fiókadatok, a kártyák kézbesítési címeinek, az árlisták és a kártyatípusok lekérését. Támogatja továbbá a kártyacsoportok létrehozását és frissítését, valamint a kártyák csoportok közötti áthelyezését is.

Előny	Leírás
Átfogó fiókkezelés	Részletes ügyfélfiók-adatok elérése, beleértve a számlázást, kártyaösszefoglalók és az állapot
Kártyacsoport-műveletek	Kártyacsoportok létrehozása, frissítése és megszüntetése rugalmas kártyaáthelyezési lehetőségekkel
Árlisták elérése	Országos és nemzetközi árlisták lekérése ügyfélspecifikus kedvezményekkel
Rugalmas keresés	Adatlekérdezés több keresési feltétellel és oldalszámozás támogatással

Hitelesítés

Ez az API támogatja mind az alapvető hitelesítést, mind az OAuth 2.0-t. Az OAuth 2.0 a fokozott biztonság érdekében ajánlott hitelesítési módszer.

Áttérési megjegyzés

Az API mostantól támogatja az OAuth 2.0 hitelesítést. Ha jelenleg az alapvető hitelesítést használja, a fokozott biztonság érdekében javasoljuk az OAuth 2.0-ra való áttérést. Az alap-URL frissült, és az összes végpont mostantól a /v1 útvonal alatt verziószámmal szerepel. A részletes áttérési útmutatásért kérjük, olvassa el az OAuth 2.0 áttérési támogatást.

Engedélyezési folyamat

Ügyfél-azonosító és titkos kulcs igénylése

Vegye fel a kapcsolatot a Shell API-csapattal az OAuth-hitelesítéshez való hozzáférés igényléséhez. A Shell API-csapat megadja az ügyfél-azonosítót és a titkos kulcsot.

Bearer token igénylése

Miután megkapta a hitelesítő adatokat, küldjön kérést a Shell Authentication API OAuth-token végpontjára a hitelesítő adataival.

Példa kérésre:

curl --location --request POST 'https://api-test.shell.com/v2/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=**************' \
--data-urlencode 'client_secret=**************' \
--data-urlencode 'grant_type=client_credentials'

A válaszban egy Bearer tokent fog kapni:

{
   "access_token": "**************",
   "expires_in": "899",
   "token_type": "Bearer"
}

Megjegyzés: A Bearer token lejárati ideje másodpercben van megadva.

API-kérelmek engedélyezése

A Shell API-k meghívásakor a kérelem fejlécében szerepeltesse az alábbiakat.

Authorization: Bearer access_token

Alap-URL-ek

Környezet	URL
Teszt	https://api-test.shell.com/test
Termelés	https://api.shell.com

Alapvető integráció

1. A bejelentkezett felhasználó adatainak lekérése

Leírás: Ez a végpont lekérdezi a bejelentkezett felhasználó adatait, beleértve az elérhető fizetőket, fiókokat és szerepköröket. Ezt a műveletet a sikeres hitelesítés után kell meghívni a későbbi API-hívásokhoz szükséges PayerId lekéréséhez.

Útvonal: POST /user-management/v1/loggedinuser

Minta kérés

curl --location 'https://api-test.shell.com/test/user-management/v1/loggedinuser' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "IncludePayerGroup": false,
    "IncludeEIDDetails": false,
    "RequestedAPIName": "v1/Card/OrderCard"
  }
}'

Kérésparaméterek

Paraméter	Típus	Kötelező	Leírás
RequestId	string	Igen	Kötelező UUID (RFC 4122) a kérelem nyomon követéséhez
IncludePayerGroup	boolean	Nem	Ha igaz, a fizetőcsoport adatait is tartalmazza (alapértelmezett: hamis)
IncludeEIDDetails	boolean	Nem	Ha igaz, az elektronikus számla adatait is tartalmazza (alapértelmezett: hamis)

Minta válasz

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "UserName": "John123",
 "DisplayName": "John A.",
 "HasAPIAccess": true,
 "Payers": [
 {
 "IsDefault": true,
          "ColcoId": 1,
 "ColcoCode": 86,
 "PayerId": 1234,
          "PayerNumber": "GB000000123",
 "PayerName": "MATTHEW ALGIE & COMPANY LIMITED"
 }
 ]
    }
  ]
}

Válaszmezők

Mező	Típus	Leírás
Felhasználónév	string	A bejelentkezett felhasználó azonosítója
DisplayName	string	A bejelentkezett felhasználó neve
HasAPIAccess	boolean	Igaz, ha a felhasználónak hozzáférése van a kért API-hoz
PayerId	integer	A későbbi kérésekben használható fizető azonosítója
PayerNumber	string	A későbbi kérésekben használható fizető azonosító

2. Ügyfélszámlák lekérdezése

Leírás: Ez a végpont lehetővé teszi az ügyfélszámlák adatainak lekérdezését a Shell Cards Platformról, rugalmas keresési feltételekkel és oldalszámozás támogatással. Használja az előző lépésben kapott PayerId-t.

Útvonal: POST /customer-management/v1/accounts

Minta kérés

curl --location 'https://api-test.shell.com/test/customer-management/v1/accounts' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE",
    "IncludeCardSummary": true
  },
  "Page": 1,
  "PageSize": 50
}'

Kérésparaméterek

Paraméter	Típus	Kötelező	Leírás
ColCoCode	egész szám	Igen	Gyűjtő társaság kódja (Shell-kód)
PayerNumber	karaktersorozat	Igen	Az ügyfél fizetőszáma
Állapot	karaktersorozat	Nem	Számlaállapot-szűrő (AKTÍV, BLOKKOLVA, TÖRLVE stb.)
IncludeCardSummary	boolean	Nem	A kártyaösszefoglaló adatainak felvétele (alapértelmezett: true)
Page	egész szám	Nem	Oldalszám (alapértelmezett: 1)
PageSize	integer	Nem	Oldalonkénti rekordok száma (alapértelmezett: 50)

Minta válasz

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "AccountId": 1,
 "AccountNumber": "GB000000124",
 "AccountFullName": "Acme Corporation",
 "Status": "Active",
 "CurrencyCode": "EUR",
      "TotalCards": 1000,
 "TotalActiveCards": 500
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}

Válaszmezők

Mező	Típus	Leírás
AccountId	egész szám	Számlaazonosító
AccountNumber	string	Számlaszám
AccountFullName	string	A számla teljes neve
Status	string	A számla aktuális állapota
CurrencyCode	string	ISO pénznemkód
TotalCards	egész szám	A fiókhoz tartozó kártyák összesen száma
TotalActiveCards	egész szám	Az aktív kártyák száma

3. Kártyacsoportok lekérdezése

Leírás: Ez a végpont rugalmas keresési feltételek és oldalszámozás segítségével lekérdezi a kártyacsoportok adatait a Shell Cards Platformról. A kártyacsoportok segítenek a kártyák szervezésében egy számlán belül.

Útvonal: POST /customer-management/v1/cardgroups

Minta kérés

curl --location 'https://api-test.shell.com/test/customer-management/v1/cardgroups' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE"
  },
  "Page": 1,
  "PageSize": 50
}'

Kérésparaméterek

Paraméter	Típus	Kötelező	Leírás
ColCoCode	egész szám	Igen	Beszedő társaság kódja
PayerNumber	karaktersorozat	Igen	Az ügyfél fizetőszáma
Állapot	karaktersorozat	Igen	Kártyacsoport állapota (ACTIVE, TERMINATED, ALL)
CardGroupName	karaktersorozat	Nem	Szűrés kártyacsoport-név szerint (min. 2 karakter)

Minta válasz

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "CardGroupId": 40000,
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "Status": "ACTIVE",
      "PrintOnCard": true,
 "CardTypeId": 1234,
 "TotalCards": 1234,
 "ActiveCards": 999
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}

Válaszmezők

Mező	Típus	Leírás
CardGroupId	egész szám	Kártyacsoport-azonosító
CardGroupName	karaktersorozat	A kártyacsoport neve
Status	karaktersorozat	A kártyacsoport állapota
TotalCards	egész szám	A csoportban található kártyák összesen száma
ActiveCards	egész szám	A csoportban található aktív kártyák száma

4. Kártyacsoport létrehozása

Leírás: Ez a végpont új kártyacsoportot hoz létre a Shell Cards Platformon, és opcionálisan legfeljebb 500 kártyát áthelyez az újonnan létrehozott csoportba. A kártyaáthelyezési kérelmek az érvényesítés után sorba kerülnek.

Útvonal: POST /customer-management/v1/createcardgroup

Minta kérelem

curl --location 'https://api-test.shell.com/test/customer-management/v1/createcardgroup' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "ColCoCode": 86,
  "PayerNumber": "GB000000123",
  "AccountNumber": "GB000000124",
  "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
  "PrintOnCard": true,
  "Cards": [
    {
 "AccountNumber": "GB99215176",
 "PAN": "7002051006629890645"
    }
  ]
}'

Kérés paraméterei

Paraméter	Típus	Kötelező	Leírás
ColCoCode	egész szám	Igen	Beszedő cég kódja
PayerNumber	karaktersorozat	Igen	Az ügyfél fizetőszáma
AccountNumber	karaktersorozat	Igen	Az ügyfél számlaszáma
CardGroupName	karaktersorozat	Igen	Az új kártyacsoport neve (1–40 karakter)
PrintOnCard	boolean	Igen	A kártyacsoport nevének dombornyomása a kártyákra
Cards	tömb	Nem	Áthelyezendő kártyák listája (max. 500)

Minta válasz

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "MainReference": 1234,
 "NewCardGroupReference": 5672,
 "SuccessfulRequests": [
 {
 "PAN": "7002051123456789145",
          "Reference": 12345
 }
 ],
 "ErrorCards": []
    }
  ]
}

Válaszmezők

Mező	Típus	Leírás
MainReference	egész szám	A teljes kérelem nyomon követéséhez szükséges hivatkozási szám
NewCardGroupReference	egész szám	A kártyacsoport létrehozásának hivatkozási száma
SuccessfulRequests	tömb	A sikeresen sorba állított kártyaáthelyezési kérelmek listája
Hibás kártyák	tömb	Az érvényesítés során sikertelen kártyák listája

Hibakezelés

Az API szabványos HTTP-állapotkódokat használ. Hiba esetén a válasz szövegében további részletek kerülnek megadásra.

Hibakód	Leírás	Megoldás
E0001	Érvényesítési hiba	Ellenőrizze, hogy a kérés paraméterei között nincsenek-e hiányzó vagy érvénytelen értékek
E0003	Jogosulatlan	Ellenőrizze a hitelesítő adatokat, és győződjön meg arról, hogy a felhasználónak van hozzáférése a művelethez
E0005	Erőforrás nem található	Ellenőrizze, hogy a kért erőforrás létezik-e és elérhető-e
9015	Duplikált kártyacsoport-név	Használjon egyedi kártyacsoport-nevet az ügyfél számára

Válassza ki a nyelvet

B2B Mobility Customer Data 3.0.5

B2B Mobility ügyféladatok – Gyors útmutató

Bevezetés

Hitelesítés

Áttérési megjegyzés

Engedélyezési folyamat

Alap-URL-ek

Alapvető integráció

1. A bejelentkezett felhasználó adatainak lekérése

Minta kérés

Kérésparaméterek

Minta válasz

Válaszmezők

2. Ügyfélszámlák lekérdezése

Minta kérés

Kérésparaméterek

Minta válasz

Válaszmezők

3. Kártyacsoportok lekérdezése

Minta kérés

Kérésparaméterek

Minta válasz

Válaszmezők

4. Kártyacsoport létrehozása

Minta kérelem

Kérés paraméterei

Minta válasz

Válaszmezők

Hibakezelés

Rólunk

Kapcsolat

Bejelentkezés a fiókjába