B2B Mobility Customer Data v3.0.5 | Vodnik za hiter začetek: Podatki o strankah storitve B2B Mobility

Hitri začetek za podatke o strankah v storitvi B2B Mobility

Uvod

API za podatke o strankah v storitvi B2B Mobility je storitev RESTful, ki omogoča poizvedovanje in upravljanje podatkov o računih strank, skupinah kartic ter s tem povezanih nastavitev znotraj platforme Shell Cards. Ta API ponuja prilagodljive možnosti iskanja, podpira stranjenje, ter omogoča pridobivanje podatkov o računih, naslovih za dostavo kartic, cenikih in vrstah kartic. Podpira tudi operacije za ustvarjanje in posodabljanje skupin kartic ter premikanje kartic med skupinami.

Prednosti	Opis
Celovito upravljanje računov	Dostop do podrobnih podatkov o računih strank, vključno z zaračunavanjem, povzetki kartic, in stanja
Operacije s skupinami kartic	Ustvarjanje, posodabljanje in ukinjanje skupin kartic s prilagodljivimi možnostmi premikanja kartic
Dostop do cenikov	Pridobivanje nacionalnih in mednarodnih cenikov s popusti,
Prilagodljivo iskanje	Iskanje podatkov z več iskalnimi merili in podporo za razvrščanje po straneh

Preverjanje pristnosti

Ta API podpira tako osnovno preverjanje pristnosti kot OAuth 2.0. OAuth 2.0 je priporočena metoda avtentifikacije za večjo varnost.

Opomba o migraciji

API zdaj podpira avtentifikacijo OAuth 2.0. Če trenutno uporabljate osnovno avtentifikacijo, priporočamo prehod na OAuth 2.0 zaradi večje varnosti. Osnovni URL je bil posodobljen, vsi končni točki pa so zdaj razvrščeni po različicah pod potjo /v1. Za podrobna navodila o migraciji si oglejte Podporo za migracijo na OAuth 2.0.

Potek avtorizacije

Zahteva za ID stranke in skrivni ključ

Obrnite se na ekipo Shell API, da zahtevate dostop do avtentifikacije OAuth. Ekipa Shell API vam bo posredovala ID stranke in skrivni ključ.

Zahtevajte token Bearer

Ko prejmete poverilnice, s svojimi poverilnicami pošljite zahtevo na končno točko za OAuth-token API-ja za avtentifikacijo Shell.

Primer zahtevka:

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 odgovoru boste prejeli žeton Bearer:

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

Opomba: Čas poteka veljavnosti žetona Bearer je naveden v sekundah.

Avtorizacija zahtevkov API

Pri klicu API-jev Shell v glavo zahtevka vključite naslednje.

Authorization: Bearer access_token

Osnovni URL-ji

Okolje	URL
Test	https://api-test.shell.com/test
Proizvodno okolje	https://api.shell.com

Osnovna integracija

1. Pridobivanje podatkov o prijavljenem uporabniku

Opis: Ta končna točka pridobi podatke o prijavljenem uporabniku, vključno z dostopnimi plačniki, računi in vlogami. To operacijo je treba izvesti po uspešni avtentifikaciji, da se pridobi PayerId, potreben za nadaljnje API-klicanje.

Pot: POST /user-management/v1/loggedinuser

Primer zahtevka

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

Parametri zahtevka

Parameter	Tip	Obvezno	Opis
RequestId	niz	Da	Obvezno UUID (RFC 4122) za sledenje zahtevka
IncludePayerGroup	boolean	Ne	Vključi podatke o skupini plačnikov, če je vrednost true (privzeto: false)
IncludeEIDDetails	boolean	Ne	Vključi podatke o elektronskem računu, če je vrednost true (privzeto: false)

Primer odgovora

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

Polja odgovora

Polje	Tip	Opis
UserName	niz	Identifikator prijavljenega uporabnika
DisplayName	niz	Ime prijavljenega uporabnika
HasAPIAccess	boolean	True, če ima uporabnik dostop do zahtevanega API-ja
PayerId	celo število	ID plačnika za uporabo v nadaljnjih zahtevkih
PayerNumber	niz	Številka plačnika za uporabo v nadaljnjih zahtevkih

2. Poizvedba o računih strank

Opis: Ta končna točka omogoča poizvedovanje podrobnosti o računih strank iz platforme Shell Cards s prilagodljivimi iskalnimi merili in podporo za stranjenje. Uporabite ID plačnika, pridobljen v prejšnjem koraku.

Pot: POST /customer-management/v1/accounts

Primer zahtevka

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

Parametri zahtevka

Parameter	Tip	Obvezno	Opis
ColCoCode	celo število	Da	Koda podjetja za zbiranje (koda Shell)
PayerNumber	niz	Da	Številka plačnika stranke
Status	niz	Ne	Filter stanja računa (AKTIVEN, BLOKIRAN, PREKLICAN itd.)
IncludeCardSummary	logična vrednost	Ne	Vključi podrobnosti povzetka kartice (privzeto: true)
Page	celo število	Ne	Številka strani (privzeto: 1)
PageSize	celo število	Ne	Število zapisov na stran (privzeto: 50)

Primer odgovora

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

Polja odgovora

Polje	Tip	Opis
AccountId	celo število	Identifikator računa
AccountNumber	niz	Številka računa
AccountFullName	niz	Polno ime računa
Status	niz	Trenutno stanje računa
CurrencyCode	niz	ISO-koda valute
TotalCards	celo število	Skupno število kartic na računu
TotalActiveCards	celo število	Število aktivnih kartic

3. Poizvedba po skupinah kartic

Opis: Ta končna točka pridobi podrobnosti o skupinah kartic iz platforme Shell Cards s prilagodljivimi iskalnimi merili in razvrščanjem po straneh. Skupine kartic pomagajo pri organizaciji kartic znotraj računa.

Pot: POST /customer-management/v1/cardgroups

Primer zahtevka

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

Parametri zahtevka

Parameter	Tip	Obvezno	Opis
ColCoCode	celo število	Da	Koda podjetja za zbiranje
PayerNumber	niz	Da	Številka plačnika stranke
Status	niz	Da	Status skupine kartic (AKTIVNO, PREKINJENO, VSE)
CardGroupName	niz	Št.	Filtriranje po imenu skupine kartic (najmanj 2 znaka)

Primer odgovora

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

Polja odgovora

Polje	Tip	Opis
CardGroupId	celo število	Identifikator skupine kartic
CardGroupName	niz	Ime skupine kartic
Status	niz	Stanje skupine kartic
TotalCards	celo število	Skupno število kartic v skupini
ActiveCards	celo število	Število aktivnih kartic v skupini

4. Ustvarjanje skupine kartic

Opis: Ta končna točka ustvari novo skupino kartic v platformi Shell Cards in po želji prenese do 500 kartic v novo ustvarjeno skupino. Zahtevki za premestitev kartic se po preverjanju uvrstijo v čakalno vrsto.

Pot: POST /customer-management/v1/createcardgroup

Primer zahtevka

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

Parametri zahtevka

Parameter	Tip	Obvezno	Opis
ColCoCode	celo število	Da	Koda zbirnega podjetja
PayerNumber	niz	Da	Številka plačnika stranke
AccountNumber	niz	Da	Številka računa stranke
CardGroupName	niz	Da	Ime nove skupine kartic (1–40 znakov)
PrintOnCard	logična vrednost	Da	Ali naj se ime skupine kartic vtisne na kartice
Cards	array	Ne	Seznam kartic, ki jih je treba prenesti (največ 500)

Vzorec odgovora

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

Polja odgovora

Polje	Tip	Opis
MainReference	celo število	Referenčna številka za sledenje celotne zahteve
NewCardGroupReference	celo število	Referenčna številka za ustvarjanje skupine kartic
SuccessfulRequests	niz	Seznam uspešno v vrsto postavljenih zahtevkov za premik kartic
ErrorCards	niz	Seznam kartic, ki niso prestale preverjanja veljavnosti

Obravnava napak

API uporablja standardne HTTP-statusne kode. V primeru napake bodo dodatni podatki navedeni v telesu odgovora.

Koda napake	Opis	Rešitev
E0001	Napaka pri preverjanju veljavnosti	Preverite, ali v parametrih zahtevka manjkajo vrednosti ali so te neveljavne
E0003	Neavtorizirano	Preverite poverilnice in se prepričajte, da ima uporabnik dostop do operacije
E0005	Vire ni mogoče najti	Preverite, ali zahtevani vir obstaja in je dostopen
9015	Podvojeno ime skupine kartic	Uporabite edinstveno ime skupine kartic za stranko

Izberite svoj jezik

B2B Mobility Customer Data 3.0.5

Hitri začetek za podatke o strankah v storitvi B2B Mobility

Uvod

Preverjanje pristnosti

Opomba o migraciji

Potek avtorizacije

Osnovni URL-ji

Osnovna integracija

1. Pridobivanje podatkov o prijavljenem uporabniku

Primer zahtevka

Parametri zahtevka

Primer odgovora

Polja odgovora

2. Poizvedba o računih strank

Primer zahtevka

Parametri zahtevka

Primer odgovora

Polja odgovora

3. Poizvedba po skupinah kartic

Primer zahtevka

Parametri zahtevka

Primer odgovora

Polja odgovora

4. Ustvarjanje skupine kartic

Primer zahtevka

Parametri zahtevka

Vzorec odgovora

Polja odgovora

Obravnava napak

O nas

Pišite na

Prijava v račun