B2B Mobility Card Management v3.1.5 | Panduan Permulaan Cepat

API Pengurusan Kad Mobiliti B2B Shell - Panduan Permulaan CepatVersi API: 3.1.5 | Autentikasi: OAuth 2.0 | Status: PengeluaranKeseluruhan GambaranAPI Pengurusan Kad Shell adalah API berasaskan REST yang membolehkan pembangun menguruskan kad bahan api Shell secara berperaturan. API ini menyokong carian kad, pesanan, kemas kini status, pembatalan, dan pelbagai operasi pengurusan kad lain.Nota: Panduan ini hanya merangkumi titik akhir yang disahkan OAuth 2.0 (jalur asas: /card-management/v1). Titik akhir Auth Asas lama (/fleetmanagement/v1/card) tidak disertakan kerana ia sedang dihentikan secara berperingkat.Ciri Utama

Blok, buka blokir, dan batalkan kad

Kelola tetapan pembaharuan automatik kad

Pindahkan kad antara kumpulan kad dan akaun

Minta peringatan PINNotis Penting - OAuth 2.0PENTING: OAuth 2.0 kini merupakan kaedah pengesahan piawai

Integrasi sedia ada: Rancang migrasi anda ke OAuth 2.0

Kaedah lama:) Auth Asas dan Kunci API sedang dihentikan secara berperingkatHubungi Sokongan Teknikal Shell untuk mendapatkan kelayakan OAuth 2.0 anda (client_id dan client_secret).PengesahanOAuth 2.0 (Kaedah Pengesahan Standard)API Pengurusan Kad Shell menggunakan aliran Kredensial Klien OAuth 2.0 untuk pengesahan selamat.AMARAN: Semua pelanggan harus merancang untuk menggunakan pengesahan OAuth 2.0. Ini adalah kaedah pengesahan yang disyorkan dan terbukti tahan masa depan untuk Shell Card Management API. Kaedah pengesahan lama sedang dihentikan secara berperingkat.Aliran OAuth 2.0Langkah 1: Dapatkan Token AksesMinta token akses daripada titik akhir token OAuth:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret

Langkah 2: Menggunakan Token Akses dalam Permintaan APIAuthorization: Bearer
Content-Type: application/jsonPengurusan TokenAmalan terbaik pengurusan token:

Token capaian mempunyai jangka hayat terhad (biasanya 15 minit)

Jangan sekali-kali berkongsi client_secret anda atau memasukkannya dalam kod sisi klienStrategi Penerapan OAuth 2.0Mengapa Beralih ke OAuth 2.0?Manfaat Keselamatan:

Protokol pengesahan piawaian industri

Token akses terhad masa mengurangkan risiko keselamatan

Sokongan yang lebih baik untuk putaran dan pembatalan tokenManfaat Operasi:

Keterskalaan dan prestasi yang dipertingkatkan

Keupayaan pemantauan dan audit yang lebih baik

Pengurusan kelayakan yang dipermudahkan

Integrasi yang tahan masa depanLaluan MigrasiJika anda kini menggunakan kaedah pengesahan lama, ikuti laluan migrasi ini:

Minta kelayakan OAuth 2.0 daripada https://developer.shell.com/support?filter=all">Sokongan Teknikal Shell" style="font-size: 12px;">

Melaksana pengurusan token OAuth dalam aplikasi anda

Uji dengan teliti dalam persekitaran Uji/Sandbox

Jalankan pengesahan selari (OAuth + warisan) semasa peralihan

Memantau dan mengesahkan integrasi OAuth

Beralih kepada OAuth sahaja setelah disahkan

Menamatkan pengesahan warisan selepas migrasi berjayaPersekitaranAPI tersedia dalam dua persekitaran:

PersekitaranURL AsasTujuanPengeluaranhttps://api.shell.comPersekitaran pengeluaran langsungUji (Sandbox)https://api-test.shell.com/testPersekitaran ujian dan pembangunan

Petua:) Sentiasa uji integrasi anda dalam persekitaran Uji sebelum beralih ke pengeluaran. 2. Dapatkan Kredensial OAuth Anda 3. Dapatkan Akses Akses adalah kunci kepada segala-galanya. Tanpa akses, tiada apa yang boleh dilakukan. 4. Buat Aplikasi Buat aplikasi anda sendiri dan pasang pada peranti anda. 5. Buat Aplikasi Web Web adalah tempat semua aksi berlaku. Buat aplikasi web anda sendiri dan pasang pada peranti anda. 6. Buat Aplikasi Mudah Alih Aplikasi mudah alih adalah masa depan. Buat aplikasi mudah alik anda sendiri dan pasang pada per thing. 7. Buat Aplikasi Perdagangan Aplikasi perdagangan adalah kunci kepada segala-galanya. Tanpa aplikasi perdagangan, tiada apa yang boleh dilakukan. 8. Buat Aplikasi Perdagangan Elektronik Aplikasi e-dagang adalah kunci kepada segala-galanya. Tanpa aplikasi e-dagang, tiada apa yang boleh dilakukan. 9. Buat Aplikasi Perdagangan Perdagangan adalah kunci kepada segala-galanya. Tanpa perdagangan, tiada apa yang-list-item-id="e71e0f6a585074733d81ad2b3b302ea91">Hubungi Shell Technical SupportNota: Sentiasa uji integrasi anda dalam Persekitaran Ujian sebelum beralih ke persekitaran pengeluaran.Permulaan Cepat1. Dapatkan Kredensial OAuth Anda

Hubungi Meminta kredensial OAuth 2.0 (client_id dan client_secret)

Shell Technical SupportNota: Sentiasa uji integrasi anda dalam Persekitaran Ujian sebelum beralih ke persekitaran pengeluaran.Permulaan Cepat1. Dapatkan Kredensial OAuth Anda

Hubungi Meminta kredensial OAuth 2.0 (client_id dan client_secret)

Shell Technical SupportNota: Sentiasa uji integrasi anda">Minta kelayakan OAuth 2.0 (client_id dan client_secret)

Semak terma perkhidmatan2. Dapatkan Token AksesPertama, dapatkan token akses OAuth anda:Contoh cURL:

curl -X POST https://api-test.shell.com/v2/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret"

Respon:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899
}

3. Buat Permintaan API Pertama AndaContoh: Cari Kad AktifContoh cURL:

curl -X POST https://api-test.shell.com/test/card-management/v1/search \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "Filters": {
 "PayerNumber": "CZ00000927",
 "AccountNumber": "CZ00000927",
 "ColCoCode": 32,
 "CardStatus": [
 "Aktif"
 ]
 
 },
    "Page": 1,
    "PageSize": 1
}'

Tindak Balas Contoh:

{
    "Page": 1,
    "TotalRecords": 7994,
    "TotalPages": 7994,
    "PageSize": 1,
    "Data": [
 {
 "AccountId": 1227,
            "NamaAkaun": "Dominica1_C_1",
 "NomborAkaun": "CZ00000927",
 "NamaRingkasAkaun": "Dominica1_1",
            "BundleId": null,
 "CardBlockSchedules": null,
 "CardGroupId": null,
 "CardGroupName": null,
 "CardId": 491623,
            "CardTypeCode": "7027329",
 "CardTypeId": 11120,
 "CardTypeName": "CZ SFA NAT SIN - CHIP",
 "ColCoCountryCode": "CZ",
            "CreationDate": "20220810 23:53:25",
 "DriverName": "SHELL973169581",
            "TarikhBerkuatkuasa": "20220810",
 "TarikhTamat": "20260831",
            "FleetIdInput": true,
 "IsCRT": false,
 "IsFleet": true,
 "IsInternational": false,
 "IsNational": true,
 "IsPartnerSitesIncluded": false,
            "IsShellSitesOnly": true,
 "IssueDate": "20220812",
 "IsSuperseded": false,
 "IsVirtualCard": false,
            "LastModifiedDate": "20230614 00:05:16",
 "LastUsedDate": null,
 "LocalCurrencyCode": "CZK",
 "LocalCurrencySymbol": "Kč",
            "OdometerInput": true,
 "PAN": "7027329200001461736",
 "MaskedPAN": "7027329******461736",
            "PANID": 17268839,
 "KodKategoriPembelian": "2",
 "IDKategoriPembelian": 102,
 "NamaKategoriPembelian": "2 - Semua Produk Minyak, Barangan berkaitan Kereta dan TMF",
            "Reason": "Dirancang untuk membuka sekatan",
 "ReissueSetting": "Benar",
 "StatusDescription": "Aktif",
 "StatusId": 1,
            "TokenTypeID": 503742,
 "TokenTypeName": "CZ SFA NAT SIN – CHIP",
 "VRN": "VRN347886994",
 "ClientReferenceId": null,
            "IsEMVContact": true,
 "IsEMVContactless": false,
 "IsRFID": false,
 "RFIDUID": null,
 "EMAID": null,
 "EVPrintedNumber": null,
            "CardMediaCode": "100999",
 "MediumTypeID": 1,
 "MediumType": "Kad Minyak"
 }
    ],
    "RequestId": "5a474d3e-70f4-4f7d-9416-5d5475b33e4f",
    "Status": "SUCCESS"
}

Rujukan Titik Akhir APICarian & Pengambilan Kad

Titik AkhirKaedahDeskripsi

Rujukan Titik Akhir APICarian & Pengambilan Kad

Titik Akhir/card-management/v1/detailsPOSTDapatkan butiran satu kad bahan api (OAuth 2.0)

Kes Penggunaan Umum:td>

Kes Penggunaan Umum:

Cari mengikut status kad (AKTIF, DIKEPUNG, TAMAT TEMPOH, dan lain-lain)

Tapis mengikut nama pemandu atau pendaftaran kenderaan

Cari mengikut PAN (4 digit terakhir)

Cari kad yang tamat dalam X hariRingkasan Kad

Titik hujungKaedahDeskripsi/card-management/v1/summaryPOSTDapatkan ringkasan peringkat tinggi kad bahan api (OAuth 2.0)

Kembalikan:

Ringkasan statistik mengikut jenis kad

Perincian aktif vs tidak aktifPembelian Kad

Titik hujungKaedahDeskripsi/card-management/v1/ordercardPOSTTempah satu atau lebih kad bahan api (OAuth 2.0)/card-management/v1/ordercardenquiryPOSTSemak status pesanan kad (OAuth 2.0)

Maklumat Diperlukan untuk Memesan Kad:

ColCoCode (Mengumpul Kod Syarikat)

Nombor Pembayar atau Id Pembayar

Nombor Akaun

Jenis dan konfigurasi kad

Butiran alamat penghantaranPengurusan Status Kad

Titik hujungKaedahKeterangan/card-management/v1/updatestatusPOSTBlok, buka blokir, atau batalkan kad (OAuth 2.0)

Tindakan Status:

tbody>/table>Tindakan Status:

KEKANG - Menghalang kad secara sementara

BUKA PENGHAHANGANTindakan Status:

BLOCK2 - Mengaktifkan semula kad yang dihalang

UNBLOCK - Buka penghalanganTindakan Status:

BLOCK2 - Mengaktifkan semula kad yang dihalang

UNBLOCK - Buka penghalanganTindakan Status:

ROSAK - Laporkan kad sebagai rosak dan minta penggantian

BLOK_SEMENTARA_PELANGGAN - Sekatan sementara yang diinisiasi oleh pelanggan

TEMP_BLOCK_SHELL - Sekatan sementara yang diinisiasi oleh ShellPERINGATAN: Pembatalan kad adalah kekal dan tidak dapat dipulihkan.Titik hujung tambahan

KategoriTitik hujungKaedahDeskripsiPenamatan/card-management/v1/cancelPOSTMembatalkan satu atau beberapa kadPergerakan Kad/card-management/v1/movePOSTPindahkan kad ke kumpulan kad atau akaun lainPengurusan PIN/card-management/v1/pinreminderPOSTMeminta peringatan PIN untuk kadAlamat Penghantaran/card-management/v1/deliveryaddressupdatePOSTMengemas kini alamat penghantaran kadPerbaharuan Automatik/card-management/v1/autorenewPOSTKemas kini penunjuk penerbitan semula

Contoh PenggunaanContoh 1: Mencari Kad yang Akan Luput Tidak Lama Lagi

POST /card-management/v1/search

{
    "Filters": {
 "PayerNumber": "CZ00000927",
        "NomborAkaun": "CZ00000927",
 "ColCoCode": 32,
 "StatusKad": [
 "Aktif"
 ],
 "TamatDalamHari": 70
       
    },
    "Page": 1,
    "PageSize": 1
}

Contoh 2: Menghalang Kad Secara Sementara

POST /card-management/v1/updatestatus

{

  "Kad": [
    {
 "IDKad": 125,
 "KodColCo": 86,
 "NomborPembayar": "PH50000843",
    },
    "ReasonId": 1236,
    "ReasonText": "Buka Kunci",
    "TargetStatus": "Unblock"

  ]
}

Contoh 3: Membatalkan Kad

POST /card-management/v1/cancel

{
 
 "Cards": [
    {
 "CardId": 125,
      "CardExpiryDate": "20231231",
 "ColCoCode": 86,
 "PayerNumber": "PH50000843",
    }
  ],
  "ReasonText": "Lost",
  "RequestId": "1"
}

Penanganan RalatKod Ralat Umum

Status HTTPKod RalatKeteranganPenyelesaian200N/AStatus: BERJAYAN/A400E0001Ralat PengesahanSemak parameter permintaan401E0003Tidak dibenarkanPastikan token OAuth sah403E0003DilarangSemak kebenaran pengguna404E0005Sumber Tidak DitemuiSemak URL hujung dan sumber wujud

Amalan Terbaik1. Ambil OAuth 2.0 Pengesahan Laksana pengurusan token yang betul:

Simpan token akses dalam cache dan gunakan semula sehingga tamat tempoh

Simpan kelayakan klien dengan selamat (gunakan pembolehubah persekitaran atau pengurus rahsia)

Jangan pernah log atau dedahkan token akses dalam kod sisi klien2. Gunakan ID PermintaanSentiasa sertakan RequestId unik (format GUID) untuk penjejakan hujung ke hujung3. Laksana PaginasiUntuk set data yang besar, gunakan paginasi untuk mengelakkan tamat masa4. Uji dalam Persekitaran SandboxSentiasa uji integrasi dalam persekitaran Uji/Sandbox sebelum beralih ke pengeluaranSDK & Contoh KodShell menyediakan SDK rasmi dan contoh kod menyeluruh untuk mempercepat integrasi anda dengan API Pengurusan Kad.Bahasa SDK yang Tersedia

Python - SDK berperolehan penuh dengan sokongan OAuth 2.0

TypeScript - SDK selamat-jenis dengan definisi jenis penuh

Java - SDK gred perusahaan

C#/.NET - Integrasi .NET lengkap

PHP - Mudah-perpustakaan PHP yang mudah digunakan

Ruby - Gem Ruby untuk integrasi lancarLihat SDK & Dokumentasi RasmiSokongan & SumberSokongan Teknikal

Sokongan: Terma Perkhidmatan

Rujukan APIMendapatkan BantuanApabila menghubungi sokongan, berikan:

Client_id anda (jangan sekali-kali kongsi client_secret atau token akses anda)

RequestId daripada respons API

Cap masa permintaan

Persekitaran (Pengeluaran/Ujian) Kemas Kini Terakhir: 1 Julai 2026 Versyen Dokumen: 1.0 Versyen API: 3.1.5