B2B Mobility Customer Data v3.0.5 | Stručný návod na používanie – Údaje o zákazníkoch služby B2B Mobility

Rýchly sprievodca službou B2B Mobility Customer Data

Úvod

Rozhranie API služby B2B Mobility Customer Data je služba typu RESTful, ktorá vám umožňuje vyhľadávať a spravovať údaje o zákazníckych účtoch, skupinách kariet a súvisiacich konfiguráciách v rámci platformy Shell Cards. Toto rozhranie API ponúka flexibilné vyhľadávacie funkcie, podporuje stránkovanie, a umožňuje získavať informácie o účtoch, doručovacích adresách kariet, cenníkoch a typoch kariet. Podporuje tiež operácie na vytváranie a aktualizáciu skupín kariet, ako aj presúvanie kariet medzi skupinami.

Výhody	Popis
Komplexná správa účtov	Prístup k podrobným informáciám o zákazníckych účtoch vrátane fakturácie, prehľadov kariet a stavu
Operácie so skupinami kariet	Vytváranie, aktualizácia a rušenie skupín kariet s flexibilnými možnosťami presunu kariet
Prístup k cenníkom	Načítanie národných a medzinárodných cenníkov so zľavami špecifickými pre jednotlivých zákazníkov
Flexibilné vyhľadávanie	Vyhľadávanie údajov s viacerými vyhľadávacími kritériami a podporou stránkovania

Overovanie

Toto API podporuje základné overovanie aj OAuth 2.0. OAuth 2.0 je odporúčaná metóda overovania pre zvýšenú bezpečnosť.

Poznámka k migrácii

API teraz podporuje overovanie pomocou OAuth 2.0. Ak v súčasnosti používate základné overovanie, odporúčame prejsť na OAuth 2.0 kvôli zvýšenej bezpečnosti. Základná URL adresa bola aktualizovaná a všetky koncové body sú teraz verzie pod cestou /v1. Podrobné pokyny k migrácii nájdete v časti Podpora migrácie na OAuth 2.0.

Postup autorizácie

Žiadosť o ID klienta a tajný kľúč

Obráťte sa na tím Shell API, aby ste požiadali o prístup k overovaniu OAuth. Tím Shell API vám poskytne ID klienta a tajný kľúč.

Žiadosť o token typu „Bearer“

Akonáhle získate prihlasovacie údaje, odošlite žiadosť na koncový bod pre token OAuth v autentifikačnom rozhraní API Shell s vašimi prihlasovacími údajmi.

Príklad požiadavky:

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'

V odpovedi dostanete token typu Bearer:

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

Poznámka: Doba platnosti tokenu typu „Bearer“ je uvedená v sekundách.

Autorizácia požiadaviek API

Pri volaní rozhraní API Shellu zahrňte do hlavičky požiadavky nasledujúce údaje.

Authorization: Bearer access_token

Základné URL adresy

Prostredie	URL
Test	https://api-test.shell.com/test
Produkčné prostredie	https://api.shell.com

Základná integrácia

1. Získanie podrobností o prihlásenom používateľovi

Popis: Tento koncový bod načíta údaje o prihlásenom používateľovi, vrátane dostupných platiteľov, účtov a rolí. Túto operáciu je potrebné vyvolať po úspešnej autentifikácii, aby sa získalo PayerId potrebné pre nasledujúce volania API.

Cesta: POST /user-management/v1/loggedinuser

Ukážková požiadavka

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

Parametre požiadavky

Parameter	Typ	Povinné	Popis
RequestId	reťazec	Áno	Povinné UUID (RFC 4122) na sledovanie požiadavky
IncludePayerGroup	boolean	Nie	Ak je hodnota true, zahrnú sa informácie o skupine platiteľov (predvolené nastavenie: false)
IncludeEIDDetails	boolean	Nie	Ak je hodnota true, zahrnú sa údaje o elektronickej faktúre (predvolené: false)

Vzorová odpoveď

{
  "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"
 }
 ]
    }
  ]
}

Pole odpovede

Pole	Typ	Popis
UserName	reťazec	Identifikátor prihláseného používateľa
DisplayName	reťazec	Meno prihláseného používateľa
HasAPIAccess	boolean	Hodnota True, ak má používateľ prístup k požadovanému API
PayerId	celé číslo	ID platiteľa na použitie v nasledujúcich požiadavkách
PayerNumber	reťazec	Číslo platiteľa na použitie v nasledujúcich požiadavkách

2. Vyhľadávanie zákazníckych účtov

Popis: Tento koncový bod umožňuje vyhľadávať podrobnosti o zákazníckych účtoch z platformy Shell Cards s flexibilnými vyhľadávacími kritériami a podporou stránkovania. Použite identifikátor platiteľa (PayerId) získaný v predchádzajúcom kroku.

Cesta: POST /customer-management/v1/accounts

Ukážková požiadavka

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

Parametre požiadavky

Parameter	Typ	Povinné	Popis
ColCoCode	celé číslo	Áno	Kód inkasnej spoločnosti (kód Shell)
PayerNumber	reťazec	Áno	Číslo platiteľa zákazníka
Status	reťazec	Nie	Filter stavu účtu (AKTÍVNY, BLOCKED, CANCELLED atď.)
IncludeCardSummary	boolean	Nie	Zahrnúť podrobnosti o súhrne karty (predvolené: true)
Page	celé číslo	Nie	Číslo strany (predvolené: 1)
PageSize	celé číslo	Nie	Počet záznamov na strane (predvolené: 50)

Vzorová odpoveď

{
  "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
}

Pole odpovede

Pole	Typ	Popis
AccountId	celé číslo	Identifikátor účtu
AccountNumber	reťazec	Číslo účtu
AccountFullName	reťazec	Celé meno účtu
Status	reťazec znakov	Aktuálny stav účtu
CurrencyCode	reťazec znakov	Kód meny podľa ISO
TotalCards	celé číslo	Celkový počet kariet priradených k účtu
TotalActiveCards	celé číslo	Počet aktívnych kariet

3. Dotaz na skupiny kariet

Popis: Tento koncový bod načíta podrobnosti o skupinách kariet z platformy Shell Cards s flexibilnými vyhľadávacími kritériami a stránkovaním. Skupiny kariet pomáhajú organizovať karty v rámci účtu.

Cesta: POST /customer-management/v1/cardgroups

Ukážková žiadosť

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

Parametre požiadavky

Parameter	Typ	Povinné	Popis
ColCoCode	celé číslo	Áno	Kód inkasnej spoločnosti
PayerNumber	reťazec znakov	Áno	Číslo platiteľa zákazníka
Stav	reťazec znakov	Áno	Stav skupiny kariet (ACTIVE, TERMINATED, ALL)
CardGroupName	reťazec znakov	Nie	Filtrovanie podľa názvu skupiny kariet (min. 2 znaky)

Ukážková odpoveď

{
  "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
}

Pole odpovede

Pole	Typ	Popis
CardGroupId	celé číslo	Identifikátor skupiny kariet
CardGroupName	reťazec	Názov skupiny kariet
Status	reťazec	Stav skupiny kariet
TotalCards	celé číslo	Celkový počet kariet v skupine
ActiveCards	celé číslo	Počet aktívnych kariet v skupine

4. Vytvorenie skupiny kariet

Popis: Tento koncový bod vytvorí novú skupinu kariet v platforme Shell Cards a voliteľne presunie až 500 kariet do novo vytvorenej skupiny. Žiadosti o presun kariet sa po overení zaradia do fronty.

Cesta: POST /customer-management/v1/createcardgroup

Ukážková požiadavka

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"
    }
  ]
}'

Parametre požiadavky

Parameter	Typ	Povinné	Popis
ColCoCode	celé číslo	Áno	Kód inkasnej spoločnosti
PayerNumber	reťazec znakov	Áno	Číslo platiteľa zákazníka
AccountNumber	reťazec znakov	Áno	Číslo účtu zákazníka
CardGroupName	reťazec znakov	Áno	Názov novej skupiny kariet (1–40 znakov)
PrintOnCard	boolean	Áno	Či sa má názov skupiny kariet vyraziť na karty
Cards	pole	Nie	Zoznam kariet, ktoré sa majú presunúť (max. 500)

Vzorová odpoveď

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

Pole odpovede

Pole	Typ	Popis
MainReference	celé číslo	Referenčné číslo na sledovanie celkovej požiadavky
NewCardGroupReference	celé číslo	Referenčné číslo na vytvorenie skupiny kariet
SuccessfulRequests	pole	Zoznam úspešne zaradených žiadostí o presun kariet do fronty
ErrorCards	pole	Zoznam kariet, ktorých overenie zlyhalo

Spracovanie chýb

API používa štandardné stavové kódy HTTP. V prípade chyby budú v tele odpovede uvedené ďalšie podrobnosti.

Kód chyby	Popis	Riešenie
E0001	Chyba overenia	Skontrolujte, či v parametroch požiadavky nechýbajú hodnoty alebo či nie sú neplatné
E0003	Neoprávnený prístup	Overte prihlasovacie údaje a uistite sa, že používateľ má prístup k danej operácii
E0005	Zdroje neboli nájdené	Potvrďte, že požadovaný zdroj existuje a je dostupný
9015	Duplicitný názov skupiny kariet	Použite pre zákazníka jedinečný názov skupiny kariet

Vyberte svoj jazyk

B2B Mobility Customer Data 3.0.5

Rýchly sprievodca službou B2B Mobility Customer Data

Úvod

Overovanie

Poznámka k migrácii

Postup autorizácie

Základné URL adresy

Základná integrácia

1. Získanie podrobností o prihlásenom používateľovi

Ukážková požiadavka

Parametre požiadavky

Vzorová odpoveď

Pole odpovede

2. Vyhľadávanie zákazníckych účtov

Ukážková požiadavka

Parametre požiadavky

Vzorová odpoveď

Pole odpovede

3. Dotaz na skupiny kariet

Ukážková žiadosť

Parametre požiadavky

Ukážková odpoveď

Pole odpovede

4. Vytvorenie skupiny kariet

Ukážková požiadavka

Parametre požiadavky

Vzorová odpoveď

Pole odpovede

Spracovanie chýb

O nás

Kontakt

Prihláste sa do svojho konta