B2B Mobility Customer Data v3.0.5 | Stručný návod k použití – Údaje o zákaznících služby B2B Mobility

Rychlý start pro API zákaznických dat B2B Mobility

Úvod

API zákaznických dat B2B Mobility je služba typu RESTful, která umožňuje vyhledávat a spravovat údaje o zákaznických účtech, skupinami karet a souvisejícími konfiguracemi v rámci platformy Shell Cards. Toto API nabízí flexibilní vyhledávací funkce, podporuje stránkování a umožňuje načítat informace o účtech, doručovací adresy karet, ceníky a typy karet. Podporuje také operace pro vytváření a aktualizaci skupin karet, stejně jako přesun karet mezi skupinami.

Výhody	Popis
Komplexní správa účtů	Přístup k podrobným informacím o zákaznických účtech, včetně fakturace, přehledů karet, a stavu
Operace se skupinami karet	Vytváření, aktualizace a rušení skupin karet s flexibilními možnostmi přesunu karet
Přístup k ceníkům	Načítání národních a mezinárodních ceníků se slevami specifickými pro jednotlivé zákazníky
Flexibilní vyhledávání	Vyhledávání dat s využitím více vyhledávacích kritérií a podporou stránkování

Ověřování

Toto API podporuje jak základní ověřování (Basic Authentication), tak OAuth 2.0. OAuth 2.0 je doporučená metoda ověřování pro zvýšenou bezpečnost.

Poznámka k migraci

API nyní podporuje ověřování OAuth 2.0. Pokud v současné době používáte základní ověřování, doporučujeme přejít na OAuth 2.0 z důvodu zvýšení bezpečnosti. Základní URL adresa byla aktualizována a všechny koncové body jsou nyní verzovány pod cestou /v1. Podrobné pokyny k migraci naleznete v dokumentaci Podpora migrace na OAuth 2.0.

Průběh autorizace

Vyžádejte si ID klienta a tajný klíč

Obraťte se na tým Shell API a požádejte o přístup k ověřování OAuth. Tým Shell API vám poskytne ID klienta a tajný klíč.

Žádost o token typu „Bearer“

Jakmile získáte přihlašovací údaje, odešlete požadavek na koncový bod pro OAuth token v API ověřování Shellu s vašimi přihlašovacími údaji.

Příklad požadavku:

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 odpovědi obdržíte token typu „Bearer“:

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

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

Autorizace požadavků na API

Při volání rozhraní API Shellu uveďte v hlavičce požadavku následující údaje.

Authorization: Bearer access_token

Základní URL

Prostředí	URL
Test	https://api-test.shell.com/test
Produkční prostředí	https://api.shell.com

Základní integrace

1. Získání podrobností o přihlášeném uživateli

Popis: Tento koncový bod načte uživatelská data přihlášeného uživatele, včetně přístupných plátců, účtů a rolí. Tuto operaci je třeba vyvolat po úspěšném ověření, aby bylo možné získat identifikátor PayerId potřebný pro následné volání API.

Cesta: POST /user-management/v1/loggedinuser

Ukázkový požadavek

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

Parametry požadavku

Parametr	Typ	Povinné	Popis
RequestId	řetězec	Ano	Povinný UUID (RFC 4122) pro sledování požadavku
IncludePayerGroup	boolean	Ne	Pokud je hodnota true, zahrnou se informace o skupině plátců (výchozí: false)
IncludeEIDDetails	boolean	Ne	Pokud je hodnota true, zahrnou se údaje o elektronické faktuře (výchozí: false)

Příklad odpovědi

{
  "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 odpovědi

Pole	Typ	Popis
UserName	řetězec	Identifikátor přihlášeného uživatele
DisplayName	řetězec	Jméno přihlášeného uživatele
HasAPIAccess	logická hodnota	Hodnota „True“, pokud má uživatel přístup k požadovanému API
PayerId	celé číslo	ID plátce pro použití v následujících požadavcích
PayerNumber	řetězec	Číslo plátce pro použití v následujících požadavcích

2. Dotaz na účty zákazníků

Popis: Tento koncový bod umožňuje dotazovat se na podrobnosti účtů zákazníků z platformy Shell Cards s flexibilními vyhledávacími kritérii a podporou stránkování. Použijte identifikátor PayerId získaný v předchozím kroku.

Cesta: POST /customer-management/v1/accounts

Příklad požadavku

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

Parametry požadavku

Parametr	Typ	Povinné	Popis
ColCoCode	celé číslo	Ano	Kód inkasní společnosti (kód Shell)
PayerNumber	řetězec	Ano	Číslo plátce zákazníka
Status	řetězec	Ne	Filtr stavu účtu (AKTIVNÍ, BLOCKED, CANCELLED atd.)
IncludeCardSummary	logická hodnota	Ne	Zahrnout podrobnosti o souhrnu karty (výchozí: true)
Page	celé číslo	Ne	Číslo stránky (výchozí: 1)
PageSize	celé číslo	Ne	Počet záznamů na stránce (výchozí: 50)

Ukázková odpověď

{
  "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 odpovědi

Pole	Typ	Popis
AccountId	celé číslo	Identifikátor účtu
AccountNumber	řetězec	Číslo účtu
AccountFullName	řetězec	Celé jméno účtu
Status	řetězec	Aktuální stav účtu
CurrencyCode	řetězec	Kód měny podle ISO
TotalCards	celé číslo	Celkový počet karet k danému účtu
TotalActiveCards	celé číslo	Počet aktivních karet

3. Dotaz na skupiny karet

Popis: Tento koncový bod načítá podrobnosti o skupinách karet z platformy Shell Cards s flexibilními vyhledávacími kritérii a stránkováním. Skupiny karet pomáhají organizovat karty v rámci účtu.

Cesta: POST /customer-management/v1/cardgroups

Ukázkový požadavek

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

Parametry požadavku

Parametr	Typ	Povinné	Popis
ColCoCode	celé číslo	Ano	Kód inkasní společnosti
PayerNumber	řetězec	Ano	Číslo plátce zákazníka
Stav	řetězec	Ano	Stav skupiny karet (AKTIVNÍ, UKONČENO, VŠE)
CardGroupName	řetězec	Číslo	Filtrování podle názvu skupiny karet (min. 2 znaky)

Ukázková odpověď

{
  "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 odpovědi

Pole	Typ	Popis
CardGroupId	celé číslo	Identifikátor skupiny karet
CardGroupName	řetězec	Název skupiny karet
Status	řetězec	Stav skupiny karet
TotalCards	celé číslo	Celkový počet karet ve skupině
ActiveCards	celé číslo	Počet aktivních karet ve skupině

4. Vytvoření skupiny karet

Popis: Tento koncový bod vytvoří novou skupinu karet v platformě Shell Cards a volitelně přesune až 500 karet do nově vytvořené skupiny. Žádosti o přesun karet jsou po ověření zařazeny do fronty.

Cesta: POST /customer-management/v1/createcardgroup

Ukázkový požadavek

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

Parametry požadavku

Parametr	Typ	Povinné	Popis
ColCoCode	celé číslo	Ano	Kód inkasní společnosti
PayerNumber	řetězec	Ano	Číslo plátce zákazníka
AccountNumber	řetězec	Ano	Číslo účtu zákazníka
CardGroupName	řetězec	Ano	Název nové skupiny karet (1–40 znaků)
PrintOnCard	boolean	Ano	Zda má být název skupiny karet vyražen na kartách
Cards	pole	Ne	Seznam karet k přesunu (max. 500)

Ukázková odpověď

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

Pole odpovědi

Pole	Typ	Popis
MainReference	celé číslo	Referenční číslo pro sledování celkové žádosti
NewCardGroupReference	celé číslo	Referenční číslo pro vytvoření skupiny karet
SuccessfulRequests	pole	Seznam úspěšně zařazených požadavků na přesun karet
ErrorCards	pole	Seznam karet, u nichž selhala validace

Zpracování chyb

API používá standardní stavové kódy HTTP. V případě chyby budou v těle odpovědi uvedeny další podrobnosti.

Chybový kód	Popis	Řešení
E0001	Chyba ověření	Zkontrolujte parametry požadavku, zda neobsahují chybějící nebo neplatné hodnoty
E0003	Neoprávněný přístup	Ověřte přihlašovací údaje a ujistěte se, že má uživatel přístup k dané operaci
E0005	Zdroj nenalezen	Ověřte, zda požadovaný zdroj existuje a je přístupný
9015	Duplicitní název skupiny karet	Použijte pro zákazníka jedinečný název skupiny karet

Vyberte jazyk

B2B Mobility Customer Data 3.0.5

Rychlý start pro API zákaznických dat B2B Mobility

Úvod

Ověřování

Poznámka k migraci

Průběh autorizace

Základní URL

Základní integrace

1. Získání podrobností o přihlášeném uživateli

Ukázkový požadavek

Parametry požadavku

Příklad odpovědi

Pole odpovědi

2. Dotaz na účty zákazníků

Příklad požadavku

Parametry požadavku

Ukázková odpověď

Pole odpovědi

3. Dotaz na skupiny karet

Ukázkový požadavek

Parametry požadavku

Ukázková odpověď

Pole odpovědi

4. Vytvoření skupiny karet

Ukázkový požadavek

Parametry požadavku

Ukázková odpověď

Pole odpovědi

Zpracování chyb

O nás

Kontakt

Přihlášení k účtu