Selecteer uw taal

Machinaal vertaald (Beta)

B2B Mobility Customer Data 3.0.5

This API allows querying customer account details and card groups. It allows the fetching of account details, card delivery addresses, international and national pricelists and cardtypes.

Krijg statuswijzigingen, onderhoud en versie-updates over dit API.

B2B Mobility Customer Data Quickstart

Inleiding

De B2B Mobility Customer Data API is een RESTful service waarmee u klantgegevens, kaartgroepen en gerelateerde configuraties kunt opvragen en beheren binnen het Shell Cards Platform. Deze API biedt flexibele zoekmogelijkheden, ondersteunt paginering en maakt het mogelijk om accountgegevens, afleveradressen, prijslijsten en kaarttypen op te vragen. De API ondersteunt ook bewerkingen voor het maken en bijwerken van kaartgroepen en het verplaatsen van kaarten tussen groepen.

Benefit Description
Comprehensive Account Management Toegang tot gedetailleerde accountgegevens van klanten, inclusief facturering, kaartsamenvattingen en status
Card Group Operations Creër, update, en kaartgroepen beëindigen met flexibele kaartbewegingsmogelijkheden
Prijslijsttoegang Oproepen van nationale en internationale prijslijsten met klantspecifieke kortingen
Flexibel zoeken Opvragen van gegevens met meerdere zoekcriteria en pagineringondersteuning

Authenticatie

Deze API ondersteunt zowel basisauthenticatie als OAuth 2.0. OAuth 2.0 is de aanbevolen authenticatiemethode voor verbeterde beveiliging.

Migratie Opmerking

De API ondersteunt nu OAuth 2.0 authenticatie. Als u momenteel Basic Authentication gebruikt, raden we u aan over te stappen op OAuth 2.0 voor een betere beveiliging. De basis URL is bijgewerkt en alle eindpunten hebben nu een versie onder het /v1 pad. Raadpleeg de ondersteuning voor OAuth 2.0-migratie voor gedetailleerde migratierichtlijnen.

Authorization flow

  1. Request Client ID and Secret

Neem contact op met het Shell API-team voor een verzoek om toegang tot OAuth-authenticatie. Het Shell API-team zal een client-ID en geheim verstrekken.

  1. Request Bearer token

Als u de referenties eenmaal hebt ontvangen, dient u een verzoek in bij de Shell Authentication API's OAuth token endpoint met uw referenties.

Voorbeeld van een verzoek:

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'

U ontvangt een Bearer token in het antwoord:

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

Opmerking: De vervaltijd van het token wordt weergegeven in seconden.

  1. Authoriseer API-verzoeken

Wanneer u Shell API's aanroept, moet u het volgende opnemen in de header van het verzoek.

Authorization: Bearer access_token

Basis URL's

Omgeving URL
Test https://api-test.shell.com/test
Productie https://api.shell.com

Kernintegratie

1. Haal ingelogde gebruikersgegevens op

Beschrijving: Dit eindpunt haalt de gebruikersgegevens op van de ingelogde gebruiker, inclusief toegankelijke betalers, accounts en rollen. Deze bewerking moet worden aangeroepen na een succesvolle authenticatie om de PayerId te verkrijgen die nodig is voor volgende API-aanroepen.

Path: POST /user-management/v1/loggedinuser

Voorbeeldverzoek
curl --location 'https://api-test.shell.com/test/user-management/v1/loggedinuser' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Autorisatie: Bearer YOUR_ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "IncludePayerGroup": false,
    "IncludeEIDDetails": false,
    "RequestedAPIName": "v1/Card/OrderCard".
  }
}'
Request Parameters
Parameter Type Verplicht Omschrijving
RequestId string Ja Verplicht UUID (RFC 4122) voor het bijhouden van verzoeken
IncludePayerGroup boolean No Includeer payer group information when true (default: false)
IncludeEIDDetails boolean No Include Electronic Invoice Data wanneer true (standaard: false)
Sample Response
{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCES",
  "Gegevens": [
    {
      "UserName": "John123",
      "DisplayName: "John A.",
      "HasAPIAccess": true,
      "Betalers": [
        {
          "IsDefault": true,
          "ColcoId": 1,
          "ColcoCode": 86,
          "PayerId": 1234,
          "PayerNumber": "GB000000123",
          "PayerName": "MATTHEW ALGIE & COMPANY LIMITED".
        }
      ]
    }
  ]
}
Responsevelden
Field Type Description
UserName string Aangelogde gebruikersidentificatie
DisplayName string Naam van de aangemelde gebruiker
HasAPIAccess boolean True als de gebruiker toegang heeft tot de aangevraagde API
PayerId integer Payer Id voor gebruik in volgende verzoeken
PayerNumber string Betaalnummer voor gebruik in volgende verzoeken

2. Klantrekeningen opvragen

Beschrijving: Met dit eindpunt kunt u klantrekeninggegevens van het Shell Cards Platform opvragen met flexibele zoekcriteria en ondersteuning voor paginering. Gebruik de PayerId die is verkregen in de vorige stap.

Path: POST /customer-management/v1/accounts

Voorbeeld van verzoek
curl --location 'https://api-test.shell.com/test/customer-management/v1/accounts' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Autorisatie: Bearer YOUR_ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE",
    "IncludeCardSummary": true
  },
  "Page": 1,
  "PageSize": 50
}'
Request Parameters
Parameter Type Verplicht Omschrijving
ColCoCode integer Ja Verzameling van Bedrijfscode (Shell Code)
PayerNumber string Ja Betalingsnummer van de klant
Status string Nee Rekeningstatus filter (ACTIEF, BLOKKEND, GEANNULEERD, enz.)
IncludeCardSummary boolean No Kaartoverzichtgegevens opnemen (standaard: true) Page integer No Paginanummer (standaard: 1)
PageSize integer No Records per pagina (standaard: 50)
Sample Response
{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCES",
  "Gegevens": [
    {
      "AccountId": 1,
      "AccountNumber": "GB000000124",
      "AccountFullName": "Acme Corporation",
      "Status": "Active",
      "CurrencyCode": "EUR",
      "TotalCards": 1000,
      "TotalActiveCards": 500
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize 50
}
Responsevelden
Veld Type Beschrijving
AccountId integer Account identifier
AccountNumber string Rekeningnummer
AccountFullName string Volledige naam van de account
Status string De huidige accountstatus
CurrencyCode string ISO valutacode
TotalCards integer Totaal aantal kaarten onder de account
TotalActiveCards integer Aantal actieve kaarten

3. Kaartgroepen opvragen

Beschrijving: Dit eindpunt haalt kaartgroepgegevens op uit het Shell Cards Platform met flexibele zoekcriteria en paginering. Kaartgroepen helpen bij het ordenen van kaarten binnen een account.

Path: POST /customer-management/v1/cardgroups

Voorbeeld van verzoek
curl --location 'https://api-test.shell.com/test/customer-management/v1/cardgroups' \_header 'RequestId:'.
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Autorisatie: Bearer YOUR_ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE".
  },
  "Page": 1,
  "PageSize": 50
Request Parameters
Parameter Type Verplicht Omschrijving
ColCoCode integer Ja Verzameling Bedrijfscode
PayerNumber string Ja Betalersnummer van de klant
Status string Ja Status kaartgroep (ACTIEF, TERMINATED, ALL)
CardGroupName string No Filter op kaartgroepnaam (min 2 tekens)
Proefantwoord
{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCES",
  "Gegevens": [
    {
      "CardGroupId": 40000,
      "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
      "status "ACTIVE",
      "PrintOnCard": true,
      "CardTypeId": 1234,
      "TotalCards": 1234,
      "ActiveCards": 999
    }
  ],
  "Pagina": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize 50
}
Responsevelden
Veld Type Beschrijving
CardGroupId integer Kaartgroepidentificator
CardGroupName string Naam van de kaart groep
Status string Status van de kaartgroep
TotalCards integer Totaal aantal kaarten in de groep
ActiveCards integer Aantal actieve kaarten in de groep

4. Creëer kaartgroep

Beschrijving: Dit eindpunt creëert een nieuwe kaartgroep in het Shell Cards Platform en verplaatst optioneel tot 500 kaarten naar de nieuw gecreëerde groep. Verplaatsingsverzoeken voor kaarten worden na validatie in een wachtrij geplaatst.

Path: POST /customer-management/v1/createcardgroup

Voorbeeldverzoek
curl --location 'https://api-test.shell.com/test/customer-management/v1/createcardgroup' \header 'RequestId:' >curl --location 'https://api-test.shell.com/test/customer-management/v1/createcardgroup' \header 'RequestId:'.
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Autorisatie: 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"
    }
  ]
}'
Request Parameters
Parameter Type Verplicht Omschrijving
ColCoCode integer Ja Innende Onderneming Code
PayerNumber string Ja Betalersnummer van de klant
AccountNumber string Ja Rekeningnummer Nummer van de klant
CardGroupName string Ja Naam van de nieuwe kaartgroep (1-40 tekens)
PrintOnCard boolean Ja Wilt u de naam van de kaartgroep in reliëf op de kaarten afdrukken
Cards array No Lijst met kaarten die moeten worden verplaatst (max 500)
Sample Response
{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCES",
  "Data": [
    {
      "MainReference": 1234,
      "NewCardGroupReference": 5672,
      "SuccessfulRequests": [
        {
          "PAN": "7002051123456789145",
          "Referentie": 12345
        }
      ],
      "ErrorCards": []
    }
  ]
}
Responsevelden
Veld Type Beschrijving
MainReference integer Reference nummer voor het volgen van de algemene aanvraag
NewCardGroupReference integer referentienummer voor het maken van de kaartgroep
SuccessfulRequests array Lijst met succesvolle kaartverplaatsingsverzoeken in de wachtrij
ErrorCards array Lijst met kaarten waarvoor validatie mislukte

Foutverwerking

De API gebruikt standaard HTTP-statuscodes. Als er een fout optreedt, worden aanvullende gegevens in de respons vermeld.

Foutcode Beschrijving Oplossing
E0001 Validatiefout Controleer de verzoekparameters op ontbrekende of ongeldige waarden
E0003 Unauthorized Vifieer de referenties en controleer of de gebruiker toegang heeft tot de bewerking
E0005 Resource not Found Bekijk of de aangevraagde bron bestaat en toegankelijk is
9015 Duplicate Card Group Name Gebruik een unieke kaartgroepnaam voor de klant

Over ons

Het Shell Developer Portal ondersteunt partners bij het aan de slag gaan met Shell API’s en het omzetten van ideeën in oplossingen die klaar zijn voor productie.

Shell-logo

Neem contact op met

Neem contact op

Inloggen op je account

Vraag de AI-assistent naar de API’s en API-producten van Shell