B2B Mobility Customer Data Quickstart

Wprowadzenie

B2B Mobility Customer Data API to usługa RESTful, która umożliwia wyszukiwanie i zarządzanie szczegółami konta klienta, grupami kart i powiązanymi konfiguracjami w ramach platformy Shell Cards. Ten interfejs API zapewnia elastyczne możliwości wyszukiwania, obsługuje paginację i umożliwia pobieranie informacji o koncie, adresów dostawy kart, cenników i typów kart. Obsługuje również operacje tworzenia i aktualizowania grup kart, a także przenoszenia kart między grupami.

Korzyści	Opis
Kompleksowe zarządzanie kontem	Dostęp do szczegółowych informacji o koncie klienta, w tym rozliczeń, podsumowań kart i statusu
Operacje grup kart	Tworzenie, aktualizacja, i usuwanie grup kart z elastycznymi możliwościami przenoszenia kart
Dostęp do cennika	Pobieranie krajowych i międzynarodowych cenników z rabatami specyficznymi dla klienta
Elastyczne wyszukiwanie	Pytanie o dane z wieloma kryteriami wyszukiwania i obsługą paginacji

Uwierzytelnianie

Ten interfejs API obsługuje zarówno uwierzytelnianie podstawowe, jak i OAuth 2.0. OAuth 2.0 jest zalecaną metodą uwierzytelniania w celu zwiększenia bezpieczeństwa.

Uwaga dotycząca migracji

API obsługuje teraz uwierzytelnianie OAuth 2.0. Jeśli obecnie korzystasz z uwierzytelniania podstawowego, zalecamy migrację do OAuth 2.0 w celu zwiększenia bezpieczeństwa. Podstawowy adres URL został zaktualizowany, a wszystkie punkty końcowe są teraz wersjonowane pod ścieżką /v1. Szczegółowe wskazówki dotyczące migracji znajdują się w OAuth 2.0 Migration Support.

Przebieg autoryzacji

Request Client ID and Secret

Skontaktuj się z zespołem Shell API, aby poprosić o dostęp do uwierzytelniania OAuth. Zespół Shell API dostarczy Client ID i Secret.

Request Bearer token

Po otrzymaniu poświadczeń, wykonaj żądanie do punkt końcowy tokenu OAuth interfejsu API uwierzytelniania powłoki z poświadczeniami.

Przykładowe żądanie:

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'

Otrzymasz token Bearer w odpowiedzi:

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

Uwaga: Czas wygaśnięcia tokenu okaziciela jest podawany w sekundach.

Autoryzacja żądań API

W przypadku wywoływania interfejsów API Shell należy uwzględnić następujące informacje w nagłówku żądania.

Autoryzacja: Bearer access_token

Podstawowe adresy URL

Środowisko	URL
Test	https://api-test.shell.com/test
Production	https://api.shell.com

Core Integration

1. Get Logged-In User Details

Opis: Ten punkt końcowy pobiera dane zalogowanego użytkownika, w tym dostępnych płatników, konta i role. Operacja ta powinna zostać wywołana po pomyślnym uwierzytelnieniu w celu uzyskania PayerId potrzebnego do kolejnych wywołań API.

Ścieżka: POST /user-management/v1/loggedinuser

Przykładowe żądanie

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 żądania

Parameter	Type	Required	Description
RequestId	string	Yes	Mandatory UUID (RFC 4122) do śledzenia żądań
IncludePayerGroup	boolean	No	Include payer group information when true (default: false)
IncludeEIDDetails	boolean	No	Include Electronic Invoice Data when true (default: false)

Przykładowa odpowiedź

{
  "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": "GB0000123",
          "PayerName": "MATTHEW ALGIE & COMPANY LIMITED"
        }
      ]
    }
  ]
}

Pola odpowiedzi

Pole	Typ	Opis
UserName	string	Identyfikator zalogowanego użytkownika
DisplayName	string	Nazwa zalogowanego zalogowanego użytkownika
HasAPIAccess	boolean	True, jeśli użytkownik ma dostęp do żądanego API
PayerId	integer	Payer Id Id do wykorzystania w kolejnych żądaniach
PayerNumber	string	Numer płatnika do wykorzystania w kolejnych żądaniach

2. Query Customer Accounts

Opis: Ten punkt końcowy umożliwia wyszukiwanie szczegółów konta klienta z platformy Shell Cards z elastycznymi kryteriami wyszukiwania i obsługą paginacji. Użyj PayerId uzyskanego w poprzednim kroku.

Ścieżka: POST /customer-management/v1/accounts

Przykładowe żądanie

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": "GB0000123",
    "Status": "ACTIVE",
    "IncludeCardSummary": true
  },
  "Page": 1,
  "PageSize": 50
}'

Parametry żądania

Parameter	Type	Required	Description
ColCoCode	integer	Yes	Collecting Kod firmy (Shell Code)
PayerNumber	string	Yes	Numer płatnika klienta
Status	string	No	Filtr statusu konta (ACTIVE, ZABLOKOWANE, ANULOWANE itd.)
IncludeCardSummary	boolean	No	Include card summary details (default: true)
Page	integer	No	Page number (default: 1)
PageSize	integer	No	Records per page (default: 50)

Sample Response

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

Pola odpowiedzi

Field	Type	Description
AccountId	integer	Account identyfikator
AccountNumber	string	Numer konta
AccountFullName	string	Pełna nazwa konta
AccountFullName	string konta
Status	string	Aktualny status konta
CurrencyCode	string	Kod waluty ISO
TotalCards	integer	Łączna liczba kart w ramach konta
TotalCards	integer	Total liczba kart na koncie
TotalActiveCards	integer	Liczba aktywnych kart

3. Query Card Groups

Opis: Ten punkt końcowy pobiera szczegóły grupy kart z Shell Cards Platform z elastycznymi kryteriami wyszukiwania i paginacją. Grupy kart pomagają organizować karty w ramach konta.

Ścieżka: POST /customer-management/v1/cardgroups

Przykładowe żądanie

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": "GB0000123",
    "Status": "ACTIVE"
  },
  "Page": 1,
  "PageSize": 50
}'

Parametry żądania

Parameter	Type	Required	Description
ColCoCode	integer	Yes	Collecting Kod firmy
PayerNumber	string	Yes	Numer płatnika klienta
Status	string	Yes	Status grupy kart (ACTIVE, TERMINATED, ALL)
CardGroupName	string	No	Filter by card group name (min 2 characters)

Przykładowa odpowiedź

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

Pola odpowiedzi

Field	Type	Description
CardGroupId	integer	Identyfikator grupy kart
CardGroupName	string	Name of the card group
Status	string	Status grupy kart
TotalCards	integer	Całkowita liczba kart w grupie
ActiveCards	integer	Liczba aktywnych kart w grupie

4. Create Card Group

Opis: Ten punkt końcowy tworzy nową grupę kart w Shell Cards Platform i opcjonalnie przenosi do 500 kart do nowo utworzonej grupy. Żądania przeniesienia kart są kolejkowane po walidacji.

Ścieżka: POST /customer-management/v1/createcardgroup

Przykładowe żądanie

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": "GB0000123",
  "AccountNumber": "GB0000124",
  "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
  "PrintOnCard": true,
  "Cards": [
    {
      "AccountNumber": "GB99215176",
      "PAN": "7002051006629890645"
    }
  ]
}'

Parametry żądania

Parameter	Type	Required	Description
ColCoCode	integer	Yes	Collecting Company Code
PayerNumber	string	Yes	Numer płatnika klienta
AccountNumber	string	Yes	Numer konta klienta
Account Numer klienta
CardGroupName	string	Yes	Nazwa nowej grupy kart (1-40 znaków)
PrintOnCard	boolean	Yes	Czy wytłoczyć nazwę grupy kart na kartach
Cards	array	No	Lista kart do przeniesienia (max 500)

Przykładowa odpowiedź

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

Pola odpowiedzi

Field	Type	Description
MainReference	integer	Reference do śledzenia całego żądania
NewCardGroupReference	integer	Numer referencyjny dla utworzenia grupy kart
SuccessfulRequests	array	Lista pomyślnych żądań przeniesienia kart w kolejce
ErrorCards	array	Lista kart, które nie przeszły walidacji

Error Handling

API używa standardowych kodów statusu HTTP. W przypadku wystąpienia błędu, dodatkowe szczegóły zostaną podane w treści odpowiedzi.

Kod błędu	Opis	Rozwiązanie
E0001	Błąd walidacji	Sprawdź parametry żądania pod kątem brakujących lub nieprawidłowych wartości
E0003	Nieautoryzowane	Weryfikuj poświadczenia i upewnij się, że użytkownik ma dostęp do operacji
E0005	Resource Not Found	Potwierdź, że żądany zasób istnieje i jest dostępny
9015	Duplicate Card Group Name	Użyj unikalnej nazwy grupy kart dla klienta

Wybierz język

B2B Mobility Customer Data 3.0.5

B2B Mobility Customer Data Quickstart

Wprowadzenie

Uwierzytelnianie

Uwaga dotycząca migracji

Przebieg autoryzacji

Podstawowe adresy URL

Core Integration

1. Get Logged-In User Details

Przykładowe żądanie

Parametry żądania

Przykładowa odpowiedź

Pola odpowiedzi

2. Query Customer Accounts

Przykładowe żądanie

Parametry żądania

Sample Response

Pola odpowiedzi

3. Query Card Groups

Przykładowe żądanie

Parametry żądania

Przykładowa odpowiedź

Pola odpowiedzi

4. Create Card Group

Przykładowe żądanie

Parametry żądania

Przykładowa odpowiedź

Pola odpowiedzi

Error Handling

O nas

Kontakt

Zaloguj się do swojego konta