B2B Mobility Customer Data 3.0.5

Panduan Cepat Data Pelanggan B2B MobilityPendahuluanAPI Data Pelanggan B2B Mobility adalah perkhidmatan RESTful yang membolehkan anda menyoal dan mengurus butiran akaun pelanggan, kumpulan kad, dan konfigurasi berkaitan dalam Platform Kad Shell. API ini menyediakan keupayaan carian yang fleksibel, menyokong paginasi, dan membolehkan anda mendapatkan maklumat akaun, alamat penghantaran kad, senarai harga, dan jenis kad. Ia juga menyokong operasi untuk mencipta dan mengemas kini kumpulan kad, serta memindahkan kad antara kumpulan.

ManfaatKeteranganPengurusan Akaun KomprehensifAkses maklumat akaun pelanggan terperinci termasuk pengebilan, ringkasan kad, dan statusOperasi Kumpulan KadMewujudkan, mengemas kini, dan menamatkan kumpulan kad dengan keupayaan pergerakan kad yang fleksibel. Akses Senarai HargaMendapatkan senarai harga kebangsaan dan antarabangsa dengan diskaun khusus pelanggan. Carian FleksibelMencari data dengan pelbagai kriteria carian dan sokongan pemhalaman (pagination)

PengesahanAPI ini menyokong kedua-dua Pengesahan Asas dan OAuth 2.0. OAuth 2.0 adalah kaedah pengesahan yang disyorkan untuk keselamatan yang dipertingkatkan.Nota PemindahanAPI kini menyokong pengesahan OAuth 2.0. Jika anda kini menggunakan Pengesahan Asas, kami mengesyorkan beralih ke OAuth 2.0 untuk keselamatan yang dipertingkatkan. URL Asas telah dikemas kini, dan semua titik akhir kini mempunyai versi di bawah laluan /v1. Sila rujuk OAuth 2.0 Migration Support untuk panduan migrasi terperinci.Aliran kebenaran

Meminta ID Klien dan RahsiaHubungi Pasukan API Shell untuk memohon akses kepada pengesahan OAuth. Pasukan API Shell akan menyediakan ID Klien dan Rahsia.

2. Meminta token Bearer

Setelah anda mendapatkan kelayakan, buat permintaan ke titik akhir token OAuth Shell Authentication API dengan kelayakan anda. Contoh permintaan: 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'Anda akan menerima token Bearer dalam respons:

{
   "access_token": "**************",
   "expires_in": "899",
   "token_type": "Bearer"
}
```
Perlu diingat: Masa luput token pemegang disediakan dalam saat.Benarkan permintaan APIApabila memanggil API Shell, sertakan perkara berikut dalam pengepala permintaan.Authorization: Bearer access_tokenURL AsasPersekitaranURLUjihttps://api-test.shell.com/testPengeluaranhttps://api.shell.comIntegrasi Teras1. Dapatkan Butiran Pengguna yang Log MasukDeskripsi: Titik akhir ini mendapatkan data pengguna yang log masuk, termasuk pembayar, akaun, dan peranan yang boleh diakses. Operasi ini hendaklah dipanggil selepas pengesahan berjaya untuk mendapatkan PayerId yang diperlukan bagi panggilan API seterusnya.Laluan: POST /user-management/v1/loggedinuserPermintaan Contohcurl --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"
  }
}'  Parameter Permintaan

ParameterJenisDiperlukanKeterangan
RequestIdstringYaUUID Wajib (RFC 4122) untuk penjejakan permintaanIncludePayerGroupbooleanTidakSertakan maklumat kumpulan pembayar apabila benar (lalai: false)IncludeEIDDetailsbooleanTidakSertakan Data Invois Elektronik apabila benar (lalai: false)
/table>/section>/body>/html>
Tindak Balas Contoh
{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "UserName": "John123",
 "DisplayName": "John A.",
 "HasAPIAccess": true,
      "Pembayar": [
 {
 "IsDefault": true,
 "ColcoId": 1,
 "ColcoCode": 86,
 "PayerId": 1234,
          "NomborBayaran": "GB000000123",
 "NamaBayaran": "MATTHEW ALGIE & COMPANY LIMITED"
 ]
    }
  ]
}






Field
Type
Description






Field

Type

Description




UserNamestringPengecam pengguna yang log masukDisplayNamestringNama pengguna yang log masukHasAPIAccessbooleanBenar jika pengguna mempunyai akses ke API yang dimintaPayerIdintegerId Pembayar untuk digunakan dalam permintaan seterusnyaPayerNumberstringNombor Pembayar untuk digunakan dalam permintaan seterusnya2. Permintaan Akaun Pelanggan  **Deskripsi:** Titik akhir ini membolehkan pertanyaan butiran akaun pelanggan daripada Platform Kad Shell dengan kriteria carian yang fleksibel dan sokongan paginasi. Gunakan PayerId yang diperoleh daripada langkah sebelumnya.Laluan: POST /customer-management/v1/accounts
Permintaan Contoh
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": "AKTIF",
    "IncludeCardSummary": true
  },
  "Page": 1,
  "PageSize": 50
}'

5. Parameter Permintaan

ParameterJenisDiperlukanKeteranganColCoCodenombor bulatYaKod Syarikat Pengutip (Kod Shell)PayerNumberstringYaNombor Pembayar pelangganStatusstringTidakPenapis status akaun (AKTIF, DIKUNCI, DIBATALKAN, dan lain-lain.)SertakanRingkasanKadbooleanTidakSertakan butiran ringkasan kad (lalai: true)HalamanintegerNoNombor halaman (lalai: 1)PageSizeintegerNoRekod setiap halaman (lalai: 50)/tbody>/table>

Tindak Balas Contoh

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "JAYALAH",
  "Data": [
    {
 "ID Akaun": 1,
 "Nombor Akaun": "GB000000124",
 "Nama Penuh Akaun": "Acme Corporation",
      "Status": "Aktif",
 "KodMataWang": "EUR",
 "JumlahKad": 1000,
 "JumlahKadAktif": 500
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}                                                                AccountNumberstringNombor akaunAccountFullNamestringNama penuh akaunStatusstringStatus akaun semasaCurrencyCodestringKod mata wang ISOTotalCardsintegerJumlah keseluruhan kad di bawah akaunTotalActiveCardsintegerBilangan kad aktif3. Mengumpul Kumpulan KadKeterangan: Titik akhir ini mendapatkan butiran kumpulan kad daripada Platform Kad Shell dengan kriteria carian yang fleksibel dan paginasi. Kumpulan kad membantu menyusun kad dalam akaun.Laluan: POST /customer-management/v1/cardgroupsPermintaan Contohcurl --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": "AKTIF"
  },
  "Page": 1,
  "PageSize": 50
}'

kod

Parameter Permintaan

ParameterJenisDiperlukanKeteranganColCoCodenombor bulatYaKod Syarikat PengutipPayerNumberstringYaNombor Pembayar pelangganStatusstringYaStatus kumpulan kad (AKTIF, TERMINASI, SEMUA)CardGroupNamestringNoTapis mengikut nama kumpulan kad (min 2 aksara)Tindak Balas Contoh{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "CardGroupId": 40000,
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "Status": "AKTIF",
 "PrintOnCard": true,
      "CardTypeId": 1234,
 "TotalKad": 1234,
 "KadAktif": 999
    }
  ],
  "Halaman": 1,
  "JumlahRekod": 100,
  "TotalPages": 2,
  "PageSize": 50
}

Lapangan Respons




Field
Jenis
Keterangan

thead>CardGroupIdintegerPengecam kumpulan kadCardGroupNamestringNama kumpulan kadStatusstringStatus kumpulan kadTotalCardsintegerJumlah keseluruhan kad dalam kumpulanKad AktifintegerBilangan kad aktif dalam kumpulan4. Buat Kumpulan KadKeterangan: Titik akhir ini mencipta kumpulan kad baru dalam Platform Kad Shell dan secara pilihan memindahkan sehingga 500 kad ke dalam kumpulan yang baru dibuat. Permintaan pemindahan kad akan diletakkan dalam barisan selepas pengesahan.Laluan: POST /customer-management/v1/createcardgroupPermintaan Contohcurl --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,
  "Kad": [
    {
 "NomborAkaun": "GB99215176",
 "PAN": "7002051006629890645"
    }
  ]
}'

Parameter Permintaan

ParameterJenisDiperlukanKeteranganColCoCodeintegerYesKod Syarikat KutipanPayerNumberstringYesNombor Pembayar pelangganNomborAkaunstringYaNombor Akaun pelangganNamaKumpulanKadstringYaNama kumpulan kad baru (1-40 aksara)PrintOnCardbooleanYaSama ada untuk mencetak nama kumpulan kad pada kadCardsarrayTidakSenarai kad untuk dipindahkan (maksimum 500)  Tindak Balas Contoh   {
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "MainReference": 1234,
 "NewCardGroupReference": 5672,
 "SuccessfulRequests": [
 {
          "PAN": "7002051123456789145",
 "Rujukan": 12345
 ],
 "Kad Ralat": []
    ]
}
}
















MainReferenceintegerNombor rujukan untuk menjejaki keseluruhan permintaanNewCardGroupReferenceintegerNombor rujukan untuk penciptaan kumpulan kadSuccessfulRequestsarraySenarai permintaan pemindahan kad yang berjaya dibariskanErrorCardsarraySenarai kad yang gagal pengesahanPengendalian RalatAPI ini menggunakan kod status HTTP piawai. Sekiranya berlaku ralat, butiran tambahan akan disediakan dalam badan respons.Kod RalatPeneranganPenyelesaianE0001Ralat PengesahanSemak parameter permintaan untuk nilai yang hilang atau tidak sahE0003Tidak DiizinkanSemak kelayakan dan pastikan pengguna mempunyai akses kepada operasi tersebutE0005Sumber Tidak DitemuiPastikan sumber yang diminta wujud dan boleh diakses