B2B Mobility Card Transaction Data v2.3.5 | Panduan Permulaan Cepat

API Data Transaksi Kad Mobiliti B2B Shell - Panduan Permulaan CepatVersi API: 2.3.5 | Pengesahan: OAuth 2.0 | Status: PengeluaranKeseluruhanAPI Data Transaksi Kad Shell adalah API berasaskan REST yang membolehkan pembangun mendapatkan dan menganalisis data transaksi daripada kad bahan api Shell secara berperaturan.. API ini menyediakan akses kepada transaksi berharga, yuran, penetapan harga berdasarkan volum, peraturan bonus, pengecualian, dan ringkasan penggunaan kad.Nota: Panduan ini hanya merangkumi titik akhir yang disahkan dengan OAuth 2.0 (lorong pangkalan: /transaction-data/v1). Titik akhir Auth Asas Legasi (/fleetmanagement/v1/transaction) tidak disertakan kerana ia sedang dihentikan secara berperingkat.Ciri Utama

Memperoleh butiran transaksi berharga termasuk transaksi EV

Akses butiran transaksi bahan api dengan item jualan dan yuran

Dapatkan data ringkasan transaksi untuk transaksi Minyak dan NFR

Mencari peraturan penetapan harga berdasarkan volum dan bonus

Muat balik item yuran dan data ringkasan yuran

Akses kad dan pengecualian transaksi

Menganalisis data penggunaan kad dan perbelanjaan

Sokongan untuk pertanyaan transaksi berbayar pelbagaiNotis Penting - OAuth 2.0PENTING: OAuth 2.00 kini merupakan kaedah pengesahan piawai

Integrasi baharu: Gunakan OAuth 2.0 dari awal

Integrasi sedia ada: Rancang migrasi anda ke OAuth 2.0

Kaedah lama: Auth Asas sedang dihentikan secara berperingkatHubungi Shell Technical Support untuk mendapatkan kelayakan OAuth 2.0 anda (client_id dan client_secret).PengesahanOAuth 2.0 (Kaedah Pengesahan Standard)API Data Transaksi Kad Shell menggunakan OAuth 2.0 Aliran Kredensial Klien untuk pengesahan selamat.AMARAN: Semua pelanggan harus merancang untuk mengguna pakai pengesahan OAuth 2.0. Ini adalah yang disyorkan dan masa depan-bukti kaedah pengesahan untuk Shell Card Transaction Data API. Kaedah pengesahan lama sedang diphasekan keluar.Aliran OAuth 2.0Langkah 1: Dapatkan Token AksesMinta token akses daripada hujung titik 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``````eaf5ec1dc7f39ee2114d41121aaf6be38">Token akses mempunyai jangka hayat terhad (biasanya 15 minit)

Laksana pengeksanan token untuk mengelakkan permintaan token yang tidak perlu

Memperbaharui token sebelum tamat tempoh untuk memastikan perkhidmatan tanpa gangguan

Jangan kongsi 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

Tiada butiran pengesahan dihantar dengan setiap permintaan

Sokongan yang lebih baik untuk putaran dan pembatalan tokenManfaat Operasi:

Penambahbaikan kebolehskalaan dan prestasi

Pemantauan yang lebih baik dan keupayaan audit

Pengurusan kelayakan yang dipermudahkan

Integrasi yang kebal terhadap masa depanLajur PemindahanJika anda kini menggunakan kaedah pengesahan lama, ikuti lajur pemindahan ini:

Meminta kelayakan OAuth 2.0 daripada Sokongan Teknikal Shell

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 pembangunanPetua:-id="e0601f22da89cdb1480279bcb2129dde2">Hubungi Meminta kelayakan OAuth 2.0 (client_id dan client_secret)

Semak terma perkhidmatan

2. 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": 3600
}

3. Buat Permintaan API Pertama AndaContoh: Dapatkan Transaksi BerhargaContoh cURL:

curl -X POST https://api-test.shell.com/test/transaction-data/v1/priced \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "Filters": {
 "ColCoCode": "5",
 "PayerNumber": "DE26667080",
 "InvoiceStatus": "A",
 "IncludeFees": true,
        "FromDate": "2024-12-01 00:00:00",
 "ToDate": "2025-01-20 00:00:00"
    },
    "Page": 1,
    "PageSize": 1
}'

Tindak Balas Contoh:

{
  "RequestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "Status": "BERJAYA",
  "Data": [
    {
      "NamaAkaun": "Blue Colour Ltd",
 "IDAkaun": 29484,
 "NomborAkaun": "DE26667080",
 "NamaRingkasAkaun": "Mathew",
      "Additional1": "GBALLEGO0002452",
      "Additional2": "GBALLEGO0002452",
 "Additional3": "GBALLEGO0002452",
 "Additional4": "GBALLEGO0002452",
 "AllowClearing": "Null",
 "AuthorisationCode": 300796,
 "TransactionStatus": "Y",
 "DriverName": "SATTY BHAMRA",
 "CardExpiryPeriod": 2204,
 "CardExpiry": "20220101",
 "CardGroupId": 40000,
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "IssuerCode": 7002,
 "CardPAN": "7002053465789891000",
 "ReleaseCode": 9,
      "CardSequenceNumber": 617,
 "CardType": "GB STD FLT NAT SINGLE R9",
 "ColCoCode": "014",
 "UnitDiscountInvoiceCurrency": -0.0051,
 "ColCoExchangeRate": 0.851858,
 "InvoiceCurrencySymbol": "GBP",
 "CorrectionFlag": true,
 "CRMNumber": 10,
 "CustomerCountry": "United Kingdom",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
      "RebateonNetAmountInCustomerCurrency": 0,
 "DiskaunBerkuatkuasaDalamMataWangPelanggan": -0.22,
 "DiskaunUnitBerkuatkuasaDalamMataWangPelanggan": -0.0051,
 "HargaUnitDalamMataWangInvois": 1.1024,
      "InvoiceTax": 0,
 "InvoiceGrossAmount": 57.25,
 "InvoiceNetAmount": 47.71,
 "VATonNetAmountInCustomerCurrency": 9.54,
      "CustomerRetailPriceUnitGross": 0,
 "CustomerRetailValueTotalGross": 57.52,
 "CustomerRetailValueTotalNet": 47.93,
 "TransactionTypeDescription": 9.59,
 "RebateonNetAmountInTransactionCurrency": -0.22,
      "EffectiveDiscountInTrxCurrency": -0.22,
 "DelCoToColCoExchangeRate": 0,
 "Cards": [
 275549
 ],
 "UnitDiscountTransactionCurrency": -0.005,
 "TransactionGrossAmount": 57.25,
 "TransactionNetAmount": 47.71,
 "TransactionTax": 9.54,
 "VATonNetAmount": 9.54,
 "DelcoListPriceUnitNet": 0,
 "DelcoRetailPriceUnitGross": 1.32888,
      "UnitPriceInTransactionCurrency": 1.1074,
 "DelcoRetailPriceUnitNet": 1.1074,
 "DelcoRetailValueTotalGross": 57.52,
      "DelcoRetailValueTotalNet": 47.93,
 "TransactionCurrencySymbol": "$",
      "DiscountType": 1,
 "DisputeStatus": false,
 "IsShellSite": false,
 "FleetIdInput": "YG67OUM",
 "IncomingProductCode": 23,
 "PostingDate": "20210802",
 "PostingTime": "14:15:22",
      "ProductCode": 30,
 "ProductName": "Petirol tanpa plumbum - Oktan sederhana",
 "ProductGroupId": 22,
 "IncomingCurrencyCode": "GBP",
 "IncomingSiteDescription": "Shell Broadway Ring",
 "Location": "Shell Broadway Ring",
 "SiteName": "Shell Broadway Ring",
 "SiteCode": 32,
 "IncomingSiteNumber": 15,
      "KodMataWangInvois": "GBP",
 "TarikhInvois": "20210802",
 "NomborInvois": 3201016193,
 "ProdukBahanApi": true,
 "VATTerpakai": "Y",
 "NamaPembayar": "Colours Services Ltd",
 "NomborPembayar": "GB12121212",
 "NomborPelangganInduk": "GB12121212",
      "PayerGroup": "H312066",
 "PayerGroupName": "12162566 - FUEL CARD SERVICE",
 "CheckDigit": 6,
 "NetInvoiceIndicator": "Y",
 "DelcoCode": 5,
 "NetworkCode": 3,
 "NegaraPembelian": "United Kingdom",
 "NegaraLokasi": "United Kingdom",
 "NegaraVAT": "United Kingdom",
 "DelcoName": "Shell U.K. Oil Products Limited",
 "Network": "Shell",
      "OdometerInput": 0,
 "OriginalSalesItemId": "Null",
 "FleetIDDescription": "YG67OUM",
 "ParentCustomerId": 6494,
 "PINIndicator": "Y, N",
 "ProductGroupName": "Yuran",
 "PurchasedInCountryCode": "GB",
 "Quantity": 43.28,
 "RebateRate": 0.0022,
 "ReceiptNumber": 6803,
      "RefundFlag": "Y",
 "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "Latitude": 53.83606,
      "Bujur": -1.61854,
 "KadarPertukaranDelCo": 0.851858,
 "EuroRebateAmount": -0.258259,
 "NetEuroAmount": 56.01,
 "EuroVATAmount": 11.2,
 "ParentCustomerName": "FUEL CARD SERVICES LTD",
 "IsInvoiced": false,
 "TransactionCurrencyCode": "GBP",
 "CreditDebitCode": "D or C",
 "TransactionDate": "20210801",
 "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
 "TrnIdentifier": "H305908971030",
 "Type": "SALE",
      "TransactionLine": 1,
 "TransactionType": "Pembelian",
 "UTCOffset": "Europe/London",
 "VATCategory": "Kadar VAT Standard United Kingdom",
 "VATRate": 0.2,
 "PendaftaranKenderaan": "YG67OUM",
 "AdakahDibatalkan": "Y",
 "JumlahKasutCukai": 57.25,
 "JumlahKasutBersih": 47.71,
      "ColCoVATAmount": 9.54,
 "OriginalCurrencySymbol": "$",
 "OriginalCurrencyCode": "$",
 "OriginalVATAmount": 0,
      "EmbossText": "PARKLANE PROPERTIES LTD",
 "OriginalExchangeRate": 0,
 "OriginalTransactionItemInvoiceDate": "20220202",
 "FeeTypeId": 1,
      "LineItemDescription": true,
 "FeeRuleDescription": "Caj Mudah",
 "Frequency": 1,
 "FeeRuleId": 1,
 "SystemEntryDate": "20210828",
 "SystemEntryTime": "20:21:08",
 "IsManual": "Y",
 "OriginalTransactionItemId": "Y",
 "OriginalTransactionItemInvoiceNumber": 6750802,
      "OriginalTransactionItemInvoiceId": 234,
 "PayerShortName": "FUEL CARD SERVICES LTD",
 "ReverseCharge": "Y",
 "JumlahKasauAsal": 57.25,
 "JumlahNettoAsal": 57.25,
      "UnitOfMeasure": "L",
 "RoadType": "Jalan Kebangsaan",
      "CustomerCountryIsoCode": "DE",
 "EVOperator": "Shell Recharge",
 "EVSerialId": "GBALLEGO0002452",
 "EVChargePointSerial": "GBALLEGO0002452",
 "EVChargePointConnectorType": 5,
 "EVChargePointConnectorTypeDescription": "DC 50 kW",
 "EVChargeDuration": "PT3205S",
 "EVChargeStartDate": "2021-08-01",
 "EVChargeStartTime": "20:08:01",
 "EVChargeEndDate": "2022-08-01",
      "EVChargeEndTime": "20:08:01",
 "HostingCollectingCompanyNumber": 0,
 "TransactionId": 0,
 "FuelOnly": true,
 "EVPrintedNumber": "ZZ2WJ53ZZ5",
 "IsRFID": true
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 5
}

Rujukan Titik Akhir APITransaksi Berharga

Titik AkhirKaedahDeskripsi

Rujukan Titik Akhir APITransaksi Berharga

Titik AkhirKaedahDeskripsi/transaction-data/v1/pricedtransactionPOSTDapatkan butiran transaksi bahan api dengan item jualan dan yuran (OAuth 2.0)/transaction-data/v1/pricedPOSTDapatkan butiran transaksi berharga termasuk transaksi EV (OAuth 2.0)/transaction-data/v1/pricedtransactionPOSTDapatkan butiran transaksi bahan api dengan item jualan dan yuran (OAuth 2.0)/transaction-data/v1/multipayerspricedtransactionsPOSTDapatkan butiran transaksi berharga untuk pelbagai pembayar (OAuth 2.0)Kes Penggunaan Biasa:

Mendapatkan transaksi mengikut julat tarikh

Tapis mengikut status Invois (Telah diinvois, Belum diinvois, dan lain-lain.)

Cari mengikut PAN kad atau pendaftaran kenderaan

Dapatkan transaksi pengecasan EV

Carian transaksi merentas pelbagai pembayarRingkasan Transaksi

Titik hujungKaedahDeskripsi/transaction-data/v1/pricedtransactionssummaryPOSTDapatkan data ringkasan transaksi berharga untuk Bahan Api dan NFR dengan item jualan dan yuran (OAuth 2.0)/transaction-data/v1/cardusagesummaryPOSTDapatkan analisis perbelanjaan dan ringkasan penggunaan untuk kad (OAuth 2.0)

Kembalian:

Jumlah volum dan amaun
Perincian mengikut jenis produk dan kategori
Analisis perbelanjaan pada peringkat kadPengurusan Yuran
Titik hujungKaedahKeterangan/transaction-data/v1/feessummaryPOSTDapatkan yuran data ringkasan item untuk pembayar yang diberikan (OAuth 2.0)

Maklumat Yuran:
Memperoleh item yuran yang dikenakan pada transaksi
Ringkasan semua yuran mengikut tempoh
Perincian yuran mengikut jenis dan kategori
Analisis yuran mengikut tahap pembayarPeraturan Berasaskan Jumlah Urus Niaga
Titik hujung /transaction-data/v1/volumebasedpricingPOSTDapatkan tetapan peraturan yuran tertunggak untuk pembayar yang diberikan (OAuth 2.0)

MethodDescription

/transaction-data/v1/volumebasedbonus POST Dapatkan tetapan peraturan bonus dan bonus perkaitan untuk pembayar yang diberikan (OAuth 2.0)

Berdasarkan volum-Ciri Berasaskan Jumlah:

Akses peraturan penetapan harga berasaskan jumlah

Muat balik peraturan pengiraan bonus

Dapatkan konfigurasi bonus persatuan

Pengecualian

Titik hujungKaedahKeterangan/transaction-data/v1/PengecualianPOSTDapatkan pengecualian berkaitan kad atau transaksi (OAuth 2.0)

Jenis Pengecualian:

Kegagalan pengesahan transaksi

Anomali penggunaan kad

Pengecualian kebenaranKes Penggunaan UmumBahagian ini memetakan senario perniagaan biasa kepada hujung API yang sesuai untuk membantu anda mengenal pasti dengan cepat API mana yang hendak digunakan untuk keperluan khusus anda.Kes Penggunaan 1: Penyelarasan Transaksi HarianSenario: Anda perlu menyelaraskannya semua transaksi daripada kad armada anda setiap hari untuk tujuan perakaunan. gunakan untuk keperluan khusus anda.Kes Penggunaan 1: Penyelarasan Transaksi HarianSenario: Anda perlu menyelararas semua transaksi daripada kad armada anda setiap hari untuk tujuan perakaunan.API yang disyorkan: /transaction-data/v1/pricedMengapa API ini: Titik akhir ini menyediakan butiran transaksi yang komprehensif termasuk transaksi pengecasan EV, menyokong penapisan tarikh yang fleksibel, dan merangkumi kedua-dua transaksi yang telah ditagih dan belum ditagih. Sesuai untuk penyelarasan harian dengan sokongan paginasi untuk set data yang besar.Parameter Utama:

PostingDateFrom dan PostingDateTo - Tetapkan kepada tarikh semalam

InvoiceStatus - Gunakan "A" untuk semua transaksi

PageSize - Tetapkan kepada 100 untuk mendapatkan data dengan cekapKes Penggunaan 2: Pengesahan dan Pemeriksaan InvoisSenario: Anda telah menerima sebuah invois dan perlu memeriksa semua butiran transaksi, termasuk yuran dan caj.Disyorkan API: /transaction-data/v1/pricedtransactionMengapa API ini: Direka khas untuk menyediakan maklumat terperinci mengenai transaksi bahan api termasuk item jualan dan semua yuran berkaitan. Sesuai untuk pengesahan invois kerana ia sepadan dengan struktur invois.Parameter Utama:

NomborInvois - Invois khusus untuk disahkan

TarikhInvois - Tarikh invois daripada pengebilan anda

IncludeFees - Tetapkan kepada true untuk melihat semua item yuranKes Penggunaan 3: Analisis dan Pelaporan Penggunaan Bahan ApiSenario: Anda perlu menganalisis corak penggunaan bahan api seluruh armada anda untuk bulan lepas bagi mengoptimumkan laluan dan mengurangkan kos.API yang disyorkan:

/transaction-data/v1/pricedtransactionssummary - Untuk data terkumpulMengapa API ini: Titik akhir ringkasan menyediakan data terkumpul mengikut produk, kumpulan tapak, dan tempoh masa, menjadikannya sempurna untuk analisis trend tanpa memproses jumlah urus niaga yang banyak.Parameter Utama:

PostingDateFrom dan PostingDateTo - Tetapkan kepada 30 hari terakhir

ProductCode - Tapis mengikut jenis bahan api tertentu

ProductGroupName - Kumpulan mengikut kategori bahan api

Kes Penggunaan 4: Pengurusan Pelbagai ArmadaSenario: Anda menguruskan beberapa sub-akaun atau pembayar dan perlu mendapatkan data transaksi bagi kesemuanya untuk pelaporan terkumpul.API yang Disyorkan: /transaction-data/v1/multipayerspricedtransactionsMengapa API ini: Direka khas untuk pertanyaan transaksi merentas pelbagai pembayar dalam satu panggilan API, sekali gus mengurangkan bilangan permintaan dan meningkatkan prestasi untuk senario pelbagai-armada.Parameter Utama:

Akaun - Susunan ID dan nombor pembayar (maksimum 10 pembayar)

InvoiceStatus - ""A" untuk semua transaksi

PostingDateFrom dan PostingDateTo - Tempoh pelaporanKes Penggunaan 5: Pemantauan Pengecualian dan Pengesanan PenipuanSenario: Anda ingin mengenal pasti corak transaksi luar biasa seperti transaksi bernilai tinggi, jumlah bahan api yang berlebihan, atau kad dengan penggunaan tidak normal untuk mencegah penipuan atau penyalahgunaan.API yang Disyorkan: /transaction-data/v1/exceptionsMengapa API ini: Direka khas untuk mengenal pasti transaksi yang melebihi ambang yang ditetapkan, menjadikannya sesuai untuk memantau pengecualian dan potensi penipuan.Parameter Utama:

Syarat - Tetapkan jenis ambang (NilaiLebihBesarDaripada, JumlahLebihBesarDaripada, dan lain-lain)

Nilai - Tetapkan nilai ambang

OutputType - "Transaksi" untuk pengecualian transaksi

TransactionsFromDate dan TransactionsToDate - Tempoh pemantauanKes Penggunaan 6: Analisis Yuran dan Caj Senario: Anda perlu memahami semua yuran dan caj yang dikenakan pada akaun anda untuk mengenal pasti peluang penjimatan kos atau mengesahkan pengebilan. API yang Disyorkan: /transaction-data/v1/feessummaryMengapa API ini: Memberi maklumat yuran terkumpul mengikut jenis yuran, kumpulan produk, dan kumpulan yuran, memudahkan analisis struktur yuran dan mengenal pasti kawasan berkos tinggi.Parameter Utama:

InvoiceStatus - "I" untuk yuran yang ditagih sahaja

FeeTypeGroup - Tapis mengikut "Caj Kad", "Caj Akaun", dan lain-lain.

PostingDateFrom dan PostingDateTo - Tempoh analisisKes Penggunaan 7: Penjejakan Perbelanjaan Kad IndividuSenario: Seorang pemandu meminta sejarah transaksi mereka untuk 6 bulan lepas, atau anda perlu menganalisis corak perbelanjaan untuk kad tertentu.API Disyorkan: /transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-data/v1/cardusagesummary" style="">/transaction-p>Parameter Utama: CardId atau PAN - Spesifik kad untuk dianalisis CardExpiry - Untuk pengesahan tambahan AccountId - Penapis akaun pilihanKes Penggunaan 8: Semakan Kelayakan Harga Berasaskan JumlahSenario: Anda ingin memeriksa sama ada akaun anda layak untuk peringkat penetapan harga berdasarkan volum dan memahami tahap penggunaan semasa anda berbanding ambang yang ditetapkan.API yang disyorkan: /transaction-data/v1/volumebasedpricingMengapa API ini: Menunjukkan peraturan yuran tertunggak anda, konfigurasi peringkat, dan penggunaan volum semasa, membantu anda memahami struktur harga dan merancang untuk mencapai peringkat yang lebih baik.Parameter UtamaParameter: NomborPembayar - Akaun pembayar anda IncludeHistory - Tetapkan kepada true untuk melihat pengiraan sejarah IncludeCurrentPeriodVolume - Tetapkan kepada true untuk pecahan bulan demi bulanKes Penggunaan 9: Penjejakan Bonus dan Pengembalian TunaiSenario: Anda mempunyai perjanjian bonus berdasarkan volum dan ingin menjejaki kemajuan anda ke arah ambang bonus serta melihat bonus yang telah diperoleh sebelum ini.API yang Disyorkan: /transaction-data/v1/volumebasedbonusMengapa API ini: Memberi butiran lengkap mengenai peraturan bonus, penggunaan tempoh semasa, dan pengiraan bonus sejarah, membolehkan anda mengoptimumkan pembelian untuk memaksimumkan bonus.Parameter Utama: PayerNumber - Akaun pembayar anda IncludeHistory - Tetapkan kepada true untuk melihat pembayaran bonus lepas IncludeCurrentPeriodVolume - Tetapkan kepada true untuk menjejaki kemajuan tempoh semasa

Contoh PenggunaanContoh 1: Dapatkan Transaksi Berharga (Termasuk EV)Permintaan:

POST /transaction-data/v1/priced

{
  "PageSize": 1,
  "Page": 1,
  "Filters": {
    "ColCoCode": "5",
    "ColCoId": 5,
    "InvoiceStatus": "A",
    "PayerNumber": "DE26685263",
    "AccountId": 29484,
    "AccountNumber": "DE26667080",
    "CardPAN": "7002051006629890645",
    "FromDate": "2022-01-01 00:00:00",
    "ToDate": "2022-01-31 00:00:00",
    "IncludeFees": true
  }
}

Respon:

{
  "RequestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "Status": "BERJAYA",
  "Data": [
    {
 "NamaAkaun": "Blue Colour Ltd",
 "IDAkaun": 29484,
 "NomborAkaun": "DE26667080",
 "NamaAkaunSingkat": "Mathew",
 "Tambahan1": "GBALLEGO0002452",
 "Additional2": "GBALLEGO0002452",
 "Additional3": "GBALLEGO0002452",
 "Additional4": "GBALLEGO0002452",
 "AllowClearing": "Null",
 "AuthorisationCode": 300796,
 "TransactionStatus": "Y",
 "DriverName": "SATTY BHAMRA",
 "CardExpiryPeriod": 2204,
 "CardExpiry": "20220101",
 "CardGroupId": 40000,
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "IssuerCode": 7002,
      "CardPAN": "7002053465789891000",
 "ReleaseCode": 9,
      "CardSequenceNumber": 617,
 "CardType": "GB STD FLT NAT SINGLE R9",
      "ColCoCode": "014",
 "UnitDiscountInvoiceCurrency": -0.0051,
 "ColCoExchangeRate": 0.851858,
 "InvoiceCurrencySymbol": "GBP",
      "CorrectionFlag": true,
 "CRMNumber": 10,
 "CustomerCountry": "United Kingdom",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
      "RebateonNetAmountInCustomerCurrency": 0,
 "EffectiveDiscountInCustomerCurrency": -0.22,
 "EffectiveUnitDiscountInCustomerCurrency": -0.0051,
 "UnitPriceInInvoiceCurrency": 1.1024,
 "InvoiceTax": 0,
 "InvoiceGrossAmount": 57.25,
      "JumlahBersihInvois": 47.71,
 "CukaiBaranganDanPerkhidmatanBerasaskanNett": 9.54,
 "HargaRuncitUnitBersihPelanggan": 0,
      "CustomerRetailValueTotalGross": 57.52,
 "CustomerRetailValueTotalNet": 47.93,
 "TransactionTypeDescription": 9.59,
      "RebateonNetAmountInTransactionCurrency": -0.22,
 "EffectiveDiscountInTrxCurrency": -0.22,
      "DelCoToColCoExchangeRate": 0,
 "Kad": [
 275549
      ],
 "UnitDiscountTransactionCurrency": -0.005,
 "TransactionGrossAmount": 57.25,
 "TransactionNetAmount": 47.71,
 "CukaiTransaksi": 9.54,
 "VATatasJumlahBersih": 9.54,
 "HargaSenaraiDelcoUnitBersih": 0,
 "HargaRuncitDelcoUnitKasar": 1.32888,
      "UnitPriceInTransactionCurrency": 1.1074,
 "DelcoRetailPriceUnitNet": 1.1074,
 "DelcoRetailValueTotalGross": 57.52,
      "DelcoRetailValueTotalNet": 47.93,
 "TransactionCurrencySymbol": "$",
 "DiscountType": 1,
 "DisputeStatus": false,
      "IsShellSite": false,
 "FleetIdInput": "YG67OUM",
 "IncomingProductCode": 23,
      "PostingDate": "20210802",
 "PostingTime": "14:15:22",
 "ProductCode": 30,
 "ProductName": "Petrol tanpa plumbum - oktan sederhana",
 "ProductGroupId": 22,
      "IncomingCurrencyCode": "GBP",
 "IncomingSiteDescription": "Shell Broadway Ring",
 "Location": "Shell Broadway Ring",
 "SiteName": "Shell Broadway Ring",
 "SiteCode": 32,
      "IncomingSiteNumber": 15,
 "InvoiceCurrencyCode": "GBP",
 "InvoiceDate": "20210802",
      "NomborInvois": 3201016193,
 "ProdukMinyak": true,
 "VATTerpakai": "Y",
      "Nama Pembayar": "Colours Services Ltd",
 "Nombor Pembayar": "GB12121212",
      "NomborPelangganInduk": "GB12121212",
 "KumpulanPembayar": "H312066",
 "NamaKumpulanPembayar": "12162566 - Perkhidmatan Kad Bahan Api",
 "DigitSemak": 6,
      "NetInvoiceIndicator": "Y",
      "DelcoCode": 5,
 "NetworkCode": 3,
 "NegaraPembelian": "United Kingdom",
 "NegaraLokasi": "United Kingdom",
 "NegaraVAT": "United Kingdom",
      "DelcoName": "Shell U.K. Oil Products Limited",
 "Network": "Shell",
 "OdometerInput": 0,
 "OriginalSalesItemId": "Null",
 "FleetIDDescription": "YG67OUM",
 "ParentCustomerId": 6494,
 "PINIndicator": "Y, N",
 "ProductGroupName": "Fees",
 "PurchasedInCountryCode": "GB",
 "Quantity": 43.28,
 "RebateRate": 0.0022,
      "Nombor Resit": 6803,
 "Bendera Pampasan": "Y",
      "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "Latitude": 53.83606,
 "Longitude": -1.61854,
 "DelCoExchangeRate": 0.851858,
 "EuroRebateAmount": -0.258259,
 "NetEuroAmount": 56.01,
 "EuroVATAmount": 11.2,
 "ParentCustomerName": "FUEL CARD SERVICES LTD",
 "IsInvoiced": false,
 "TransactionCurrencyCode": "GBP",
 "KodKreditDebit": "D atau C",
 "TarikhTransaksi": "20210801",
 "MasaTransaksi": "12:16:58",
 "TransactionItemId": "H305908971030",
 "TrnIdentifier": "H305908971030",
 "Type": "JUALAN",
 "TransactionLine": 1,
      "JenisTransaksi": "Pembelian",
 "OfsetUTC": "Eropah/London",
 "KategoriVAT": "Kadar VAT Standard United Kingdom",
 "VATRate": 0.2,
 "PendaftaranKenderaan": "YG67OUM",
 "IsCancelled": "Y",
 "JumlahKasarColCo": 57.25,
      "ColCoNetAmount": 47.71,
 "ColCoVATAmount": 9.54,
 "OriginalCurrencySymbol": "$",
 "OriginalCurrencyCode": "$",
 "OriginalVATAmount": 0,
      "EmbossText": "PARKLANE PROPERTIES LTD",
 "OriginalExchangeRate": 0,
      "OriginalTransactionItemInvoiceDate": "20220202",
 "FeeTypeId": 1,
 "LineItemDescription": true,
 "FeeRuleDescription": "Yuran Ringkas",
      "Frequency": 1,
 "FeeRuleId": 1,
 "SystemEntryDate": "20210828",
 "SystemEntryTime": "20:21:08",
 "IsManual": "Y",
 "OriginalTransactionItemId": "Y",
 "OriginalTransactionItemInvoiceNumber": 6750802,
 "OriginalTransactionItemInvoiceId": 234,
      "PayerShortName": "FUEL CARD SERVICES LTD",
 "ReverseCharge": "Y",
 "OriginalGrossAmount": 57.25,
 "OriginalNetAmount": 57.25,
 "UnitOfMeasure": "L",
      "Jenis Jalan": "Jalan Kebangsaan",
 "Kod ISO Negara Pelanggan": "DE",
 "Pengendali EV": "Shell Recharge",
 "ID Siri EV": "GBALLEGO0002452",
 "Siri Titik Pengecas EV": "GBALLEGO0002452",
 "EVChargePointConnectorType": 5,
      "EVChargePointConnectorTypeDescription": "DC 50 kW",
 "EVChargeDuration": "PT3205S",
 "EVChargeStartDate": "2021-08-01",
 "EVChargeStartTime": "20:08:01",
 "EVChargeEndDate": "2022-08-01",
 "EVChargeEndTime": "20:08:01",
 "HostingCollectingCompanyNumber": 0,
      "TransactionId": 0,
 "FuelOnly": true,
 "EVPrintedNumber": "ZZ2WJ53ZZ5",
 "IsRFID": true
    }
  ],
  "Page": 3,
  "PageSize": 30,
  "TotalPages": 5
}

Contoh 2: Dapatkan Butiran Transaksi Bahan ApiPermintaan:

POST /transaction-data/v1/pricedtransaction

{
  "Filters": {
    "ColCoCode": 14,
    "InvoiceStatus": "A",
    "PayerId": 12345,
    "PayerNumber": "NL10042616"
  },
  "Page": 1,
  "PageSize": 50
}

Respon:
{
"RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
"Status": "SUCCESS",
"Data": [
{
"Transaksi": [
{
"Jenis": "SalesItem /FeeItem",
"CardId": 0,
"CardPAN": "7002051006629891000",
"TarikhKad Luput": "2026-06-16",
"TarikhTransaksi": "2026-06-16",
"MasaTransaksi": "string",
"UTCOffset": "string",
"FleetIdInput": "XYZ1234",
"OdometerInput": 12345,
"DriverName": "ANDREW GILBERRY",
"VehicleRegistration": "MV65YLH",
"KodMataWangInvois": "GBP",
"SimbolMataWangInvois": "$",
"KodMataWangTransaksi": "GBP",
"TransactionCurrencySymbol": "$",
"TransactionNetAmount": 0,
"TransactionTax": 0,
"TransactionGrossAmount": 0,
"InvoiceNetAmount": 0,
"InvoiceTax": 0,
"InvoiceGrossAmount": 0,
"PurchasedInCountry": "Germany",
"AccountId": 29484,
"AccountNumber": "GB99215176",
"AccountName": "MATTHEW ALGIE & COMPANY LIMITED",
"AccountShortName": "string",
"Quantity": 0,
"FuelProduct": true,
"UnitPriceInTransactionCurrency": 0,
"UnitPriceInInvoiceCurrency": 0,
"UnitDiscountTransactionCurrency": 0,
"UnitDiscountInvoiceCurrency": 0,
"IsInvoiced": true,
"InvoiceNumber": "S04500493",
"InvoiceDate": "string",
"SiteCode": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
"SiteName": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
"SiteCountry": "Germany",
"Lokasi": {
"Lintang": "37.4224764",
"Bujur": "122.0842499"
},
"CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
"ReceiptNumber": "1234",
"ProductCode": "10 - TMF Charges",
"ProductName": "Tanpa plumbum - Oktan tinggi",
"ProductGroupId": 1,
"ProductGroupName": "Kumpulan Produk Induk",
"DelCoExchangeRate": 0,
"ColCoExchangeRate": 0,
"IsShellSite": true,
"Network": "100013\tSTEINDORFER",
"SiteGroupId": 202,
"SiteGroupName": "CZ 9100 ECONOMY NETWORK",
"PostingDate": "string",
"IssuerCode": "7002",
"PurchasedInCountryCode": "NL",
"CustomerCountryCode": "NL",
"CustomerCountry": "Netherlands",
"ReleaseCode": "8",
"CardGroupId": "string",
"CardSequenceNumber": "2",
"CheckDigit": "string",
"FleetIDDescription": "string",
"VATRate": "0.20 for 20%",
"KategoriCukaiNilaiTambah": "1-Kadar Sifar",
"CukaiNilaiTambahatasJumlahBersih": 0,
"NegaraCukaiNilaiTambah": "Belanda",
"EffectiveDiscountInTrxCurrency": 0,
"TransactionType": "Pembelian apabila Kad Dihadirkan, jika tidak Kosong",
"PINIndicator": ""PIN Digunakan"",
"VATApplicable": "Y",
"NetInvoiceIndicator": "Y",
"CustomerCurrencyCode": "GBP",
"CustomerCurrencySymbol": "£",
"EffectiveUnitDiscountInCustomerCurrency": 0,
"EffectiveDiscountInCustomerCurrency": 0,
"VATonNetAmountInCustomerCurrency": 0,
"DiscountType": "2-Pence per unit",
"TransactionStatus": "U",
"SalesItemId": 18315958002,
"PayerGroup": "string",
"PayerGroupName": "12119008 - KELOMPOK SYARIKAT SHELL",
"RefundFlag": "string",
"OriginalSalesItemId": "string",
"DelcoName": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
"DelcoCode": "14",
"PayerNumber": "NL10042616",
"PayerName": "V.M. LE COMTE",
"CardExpiryPeriod": "1901",
"AuthorisationCode": "1011256",
"TransactionId": "io9KVXk1UkW57XWKyeaHHg",
"TransactionLine": "1",
"AllowClearing": "Y",
"CRMNumber": "string",
"StatusPertikaian": "Tiada Pertikaian",
"KadarRebat": 28.279,
"KadarPertukaranDelCoToColCo": 1,
"JumlahEuroBersih": 0,
"EuroVATAmount": 0,
"ParentCustomerNumber": "string",
"ParentCustomerName": "string",
"ParentCustomerId": 0,
"IncomingSiteNumber": "100021",
"IncomingSiteDescription": "HN3 INTI_02-82.02",
"IncomingCurrencyCode": "GBP",
"IncomingProductCode": "30",
"CreditDebitCode": "D",
"CorrectionFlag": "Y",
"Additional1": "string",
"Additional2": "string",
"Additional3": "string",
"Additional4": "string",
"RebateonNetAmountInCustomerCurrency": -0.735,
"RebateonNetAmountInTransactionCurrency": "AVEE PTUAZONW CUBFAO COSFS",
"TrnIdentifier": "string",
"CardType": "string",
"DelcoListPriceUnitNet": 30.5,
"DelcoRetailPriceUnitNet": 1.921,
"DelcoRetailPriceUnitGross": 0,
"DelcoRetailValueTotalNet": 0,
"DelcoRetailValueTotalGross": 0,
"CustomerRetailPriceUnitGross": 0,
"CustomerRetailValueTotalNet": 0,
"EVPrintedNumber": "3792",
"IsRFID": true,
"TokenTypeDescription": "string"
}
]
}
],
"Page": 1,
"PageSize": 1,
"TotalPages": 15
}

Contoh 3: Dapatkan Ringkasan Transaksi BerhargaPermintaan:

POST /transaction-data/v1/pricedtransactionssummary

{
    "Penapis": {
 "ColCoCode": 9,
 "PayerId": 12,
 "InvoiceStatus": "A",
 "FromDate": "2024-03-20",
 "ToDate": "2024-09-17",
 "PurchasedInCountryCode": "AT"
    }
}

Tindak balas:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "ProductId": 1234,
 "ProductCode": "10",
 "ProductName": "Diesel AGO",
 "ProductGroupId": 1,
      "ProductGroupName": "Bahan Api",
 "TotalFuelQuantity": 1250.75,
 "TotalNetAmount": 5420.50,
 "TotalGrossAmount": 6504.60,
      "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£",
 "CustomerRetailValueTotalNet": 5420.50,
 "CustomerRetailValueTotalGross": 6504.60
    }
  ]
}

Contoh 4: Dapatkan Ringkasan HargaPermintaan:

 POST /transaction-data/v1/pricedsummary
 
 {
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "CardId": 275549,
    "FromDate": "20240225",
    "ToDate": "20240225",
    "FuelOnly": false
  }
}

Respons:

{
    "RequestId": "5f1bded6-416d-4478-ab7f-33905d7b5d4b",
    "Status": "BERJAYA",
    "Data": [
 {
 "CustomerRetailValueTotalGross": 114.13,
 "CustomerRetailValueTotalNet": 95.11,
            "InvoiceCurrencyCode": "EUR",
 "InvoiceCurrencySymbol": "€",
 "ProductCode": "21",
 "ProductGroupId": 3,
 "ProductGroupName": "Petrol",
 "ProductId": 21,
 "ProductName": "Tanpa plumbum - Oktan tinggi",
 "SiteGroupId": 104,
 "SiteGroupName": "Stesen Shell Austria Lalai",
 "TotalFuelQuantity": 17.0,
 "TotalGrossAmount": 114.13,
 "TotalNetAmount": 95.11
        }
    ]
}

Contoh 5: Dapatkan Transaksi Bermah Payer PelbagaiPermintaan:

POST /transaction-data/v1/multipayerspricedtransactions

{
  "ColCoCode": 86,
  "Akaun": [
    {
      "PayerId": 12345,
 "PayerNumber": "GB987654322"
    },
    {
 "PayerId": 12346,
      "PayerNumber": "GB000000124"
    }
  ],
  "InvoiceStatus": "A",
  "FromDate": "20220101",
  "ToDate": "20220131",
  "PageSize": 50,
  "Page": 1
}

Respon:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "BERJAYA",
  "Data": [
    {
 "Transaksi": [
 {
 "Jenis": "SalesItem"
 }
 ],
 "ID Kad": 275549,
      "CardPAN": "7002051006629891000",
 "CardExpiry": "20250812",
 "TransactionDate": "20250812",
 "TransactionTime": "14:30:45",
 "UTCOffset": "+01:00:00",
 "FleetIdInput": "XYZ1234",
 "OdometerInput": 12345,
 "DriverName": "ANDREW GILBERRY",
 "PendaftaranKenderaan": "MV65YLH",
 "KodMataWangInvois": "GBP",
 "SimbolMataWangInvois": "£",
 "KodMataWangTransaksi": "GBP",
 "SimbolMataWangTransaksi": "£",
 "JumlahBersihTransaksi": 47.71,
 "CukaiTransaksi": 9.54,
 "JumlahKasarTransaksi": 57.25,
      "JumlahBersihInvois": 47.71,
 "CukaiInvois": 9.54,
 "JumlahKasarInvois": 57.25,
 "NegaraPembelian": "Jerman",
      "AccountId": 29484,
 "AccountNumber": "GB99215176",
 "AccountName": "MATTHEW ALGIE & COMPANY LIMITED",
      "NamaAkaunSingkat": "MATTHEW",
 "Kuantiti": 43.28,
      "FuelProduct": true,
 "UnitPriceInTransactionCurrency": 1.1074,
 "UnitPriceInInvoiceCurrency": 1.1024,
      "UnitDiscountTransactionCurrency": -0.005,
 "UnitDiscountInvoiceCurrency": -0.0051,
      "IsInvoiced": true,
 "InvoiceNumber": "S04500493",
 "InvoiceDate": "20250815 09:30:00",
 "SiteCode": "050001",
 "SiteName": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "SiteCountry": "Germany",
 "Location": {
        "Latitude": "53.83606",
 "Longitude": "-1.61854"
 },
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
      "Nombor Resit": "6803",
 "Kod Produk": "10",
 "Nama Produk": "Tanpa Plumbum - Oktan Tinggi",
      "ProductGroupId": 2,
 "ProductGroupName": "Semua Bahan Api",
 "DelCoExchangeRate": 0.851858,
 "ColCoExchangeRate": 0.851858,
 "IsShellSite": true,
 "Network": "SHELL",
 "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "PostingDate": "20250812 14:30:45",
 "IssuerCode": "7002",
 "PurchasedInCountryCode": "DE",
 "CustomerCountryCode": "NL",
      "NegaraPelanggan": "Belanda",
 "KodPelepasan": "8",
 "IDKumpulanKad": "40000",
 "NomborSusunanKad": "617",
 "DigitSemak": "6",
 "DeskripsiIDKumpulan Armada": "YG67OUM",
 "KadarCukaiNilaiTambah": 0.2,
 "KategoriCukaiNilaiTambah": "1-Kadar Standard",
 "CukaiNilaiTambahatasJumlahBersih": 9.54,
 "NegaraCukaiNilaiTambah": "Belanda",
      "EffectiveDiscountInTrxCurrency": -0.22,
 "TransactionType": "Purchase",
      "PINIndicator": "PIN Digunakan",
 "VATApplicable": "Y",
 "NetInvoiceIndicator": "N",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
      "EffectiveUnitDiscountInCustomerCurrency": -0.0051,
 "EffectiveDiscountInCustomerCurrency": -0.22,
 "VATonNetAmountInCustomerCurrency": 9.54,
 "JenamaDiskaun": "2-Pence setiap unit",
      "TransactionStatus": "I",
 "SalesItemId": 18315958002,
 "PayerGroup": "H312066",
      "PayerGroupName": "12119008 - SHELL GROUP OF COMPANIES",
 "RefundFlag": "N",
 "OriginalSalesItemId": null,
 "DelcoName": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "DelcoCode": "014",
 "NomborPembayar": "GB987654322",
      "PayerName": "V.M. LE COMTE",
 "CardExpiryPeriod": "2504",
 "AuthorisationCode": "011256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
      "AllowClearing": "Y",
 "CRMNumber": null,
 "DisputeStatus": "Tiada Pertikaian",
 "RebateRate": 28.279,
 "DelCoToColCoExchangeRate": 1,
      "NetEuroAmount": 56.01,
      "EuroVATAmount": 11.2,
 "ParentCustomerNumber": "GB12121212",
 "ParentCustomerName": "FUEL CARD SERVICES LTD",
      "ParentCustomerId": 6494,
 "IncomingSiteNumber": "100021",
 "IncomingSiteDescription": "HN3 INTI_02-82.02",
 "IncomingCurrencyCode": "GBP",
 "IncomingProductCode": "30",
 "CreditDebitCode": "D",
 "CorrectionFlag": "N",
 "Additional1": "GBALLEGO0002452",
 "Additional2": null,
      "Additional3": null,
 "Additional4": null,
 "RebateonNetAmountInCustomerCurrency": -0.735,
 "RebateonNetAmountInTransactionCurrency": -0.735,
      "TrnIdentifier": "H305908971030",
 "CardType": "GB STD FLT NAT SINGLE R9",
      "DelcoListPriceUnitNet": 30.5,
 "DelcoRetailPriceUnitNet": 1.1074,
 "DelcoRetailPriceUnitGross": 1.32888,
 "DelcoRetailValueTotalNet": 47.93,
 "DelcoRetailValueTotalGross": 57.52,
 "CustomerRetailPriceUnitGross": 1.32888,
 "CustomerRetailValueTotalNet": 47.93,
      "EVPrintedNumber": "3792",
 "IsRFID": true,
 "TokenTypeDescription": "Kad Armada"
    }
  ],
  "Page": 1,
  "PageSize": 20,
  "TotalPages": 15,
  "TotalRecords": 300
}

Contoh 6: Dapatkan Peraturan Penentuan Harga Berdasarkan JumlahPermintaan:POST /transaction-data/v1/volumebasedpricing

{
"ColCoId": 1,
"ColCoCode": 86,
"PayerId": 12345,
"PayerNumber": "GB000000123",
"IncludeHistory": true,
"IncludeCurrentPeriodVolume": true
}Tindak balas:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
      "Configuration": [
 {
 "PricingAccountId": 123456,
 "PricingAccountNumber": "GB000000123",
 "PricingAccountShortName": "ABCD1234",
 "PricingAccountFullName": "ABCD1234",
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "FeeRuleDateEffective": "20231223",
          "FeeRuleDateTerminated": "20231223",
 "BonusPaidTo": "1-Bayar kepada Pembayar",
 "BonusPaidToAccountId": 123456,
 "NomborAkaunYangDibayarBonus": "GB000000123",
 "NamaRingkasAkaunYangDibayarBonus": "12345",
 "BonusPaidToAccountFullName": "GB000000123",
 "Frequency": "3-Weekly – Monday",
          "NextCalculationDate": "20231223",
 "PreviousCalculatedDate": "20231223",
          "FeeRuleBasis": "3-Bayaran Satu-Satu",
 "FeeRuleCurrencyCode": "GBP",
 "FeeRuleCurrencySymbol": "£",
 "FeeRuleAvailableFrom": "20231223",
 "FeeRuleAvailableTo": "20231223",
          "FeeRuleLocations": [
 {
 "DelcoId": 866,
 "Negara": "United Kingdom",
 "KodNegara": "UK",
 "IdRangkaianBahanApi": 100007,
              "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
              "SiteCode": 999493,
 "SiteId": 100007,
 "SiteName": "VALERO ENERGY LTD"
 }
 ],
 "FeeRuleProducts": [
 {
 "ProductGroupID": 3,
 "ProductGroupName": "Petrol",
              "KodProduk": "30 untuk Diesel AGO",
 "IDProduk": "30 untuk Diesel AGO",
 "NamaProduk": "Diesel AGO"
            }
 ],
 "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
 "TierMaximum": 1234,
 "Value": 1234.12
            }
 ]
 }
 ],
 "PenggunaanTempohKini": [
 {
          "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "PriceRuleID": 100005,
 "PriceRuleDescription": "PL/GAGO/GMOT/UL0.055",
 "TotalVolume": 10000.78,
          "NextFeeCreationDate": "20231223"
 }
 ],
 "History": [
 {
          "FromDate": "20231223",
 "ToDate": "20231223",
 "FeesRuleID": 8081,
 "FeesRuleDescription": "PT/P067/D120/P4.0",
 "JumlahJumlah": 12356.66
 }
      ],
 "Amaran": [
 {
 "Mesej": "Sistem sedang ditutup untuk naik taraf.",
 "Jenis": "Kegagalan Sistem"
 }
      ]
    }
  ]
}

Contoh 7: Dapatkan Peraturan Bonus Berdasarkan Jumlah IsipaduPermintaan:

POST /transaction-data/v1/volumebasedbonus

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "NomborPembayar": "GB000000123",
  "SertakanSejarah": true,
  "SertakanJumlahTempohKini": true
}

Tindakbalas:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Configuration": [
        {
 "PricingAccountId": 123456,
 "PricingAccountNumber": "GB000000123",
 "PricingAccountShortName": "MATTHEW",
 "PricingAccountFullName": "MATTHEW",
          "FeeRuleId": 1,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "FeeRuleDateEffective": "20231223",
 "FeeRuleDateTerminated": "20231223",
 "BonusPaidTo": "1-Bayar kepada Pembayar",
 "BonusPaidToAccountId": 123456,
 "BonusPaidToAccountNumber": "GB000000123",
 "BonusPaidToAccountShortName": "12345",
 "BonusPaidToAccountFullName": "GB000000123",
 "Frequency": "3-Weekly – Isnin",
 "TarikhPengiraanSeterusnya": "20231223",
 "TarikhPengiraanSebelumnya": "20231223",
 "AsasPeraturanYuran": "3-Bayaran Satu Kali",
 "KodMataWangPeraturanYuran": "GBP",
 "FeeRuleCurrencySymbol": "£",
 "FeeRuleAvailableFrom": "20231223",
 "FeeRuleAvailableTo": "20231223",
          "FeeRuleLocations": [
 {
 "DelcoId": 866,
 "Country": "United Kingdom",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "SiteId": 100007,
 "SiteName": "VALERO ENERGY LTD"
 }
 ],
 "FeeRuleProducts": [
            {
 "ProductGroupID": 3,
 "ProductGroupName": "Petrol",
 "ProductCode": "30 for Diesel AGO",
 "ProductId": "30 for Diesel AGO",
 "ProductName": "Diesel AGO"
            }
 ],
 "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
 "TierMaximum": 1234,
 "Value": 1234.12
            }
 ],
 "Akaun Berkaitan": [
            {
 "AssociatedAccountId": 12345,
 "AssociatedAccountNumber": "GB000000123",
 "AssociatedAccountShortName": "Nama ringkas Akaun",
 "AssociatedAccountFullName": "Nama Penuh Akaun"
            }
 ]
 }
 ],
 "PenggunaanTempohKini": [
 {
 "IdPeraturanYuran": 12345,
 "KeteranganPeraturanYuran": "NL/GAGO/D018/UP0.0120>1",
 "Bulan": 1,
 "Tahun": 2018,
 "JumlahJumlah": 10000.78
 }
      ],
 "HistoricalBonusPaid": [
 {
 "PayerId": 12345,
 "PayerNumber": "GB000000123",
 "PayerShortName": "Jorden",
          "NamaPenuhBayaran": "MATTHEW",
 "IDAkaun": 123456,
 "NomborAkaun": "GB000000123",
 "NamaRingkasAkaun": "SALT",
 "AccountFullName": "ABCD1234",
 "InvoiceAccountId": 12345,
          "InvoiceAccountNumber": "GB000000123",
 "InvoiceAccountShortName": "DFE1234",
 "InvoiceAccountFullName": "AZAD PVT LMT",
 "FeeRuleId": 12345,
 "FeeRuleDescription": "NL/GAGO/D018/UP0.0120>1",
 "FromDate": "20231223",
          "ToDate": "20231223",
 "BonusPaidTo": "5-Bayaran kepada Pelanggan Berkaitan",
 "FeeItemId": 12345,
 "FeeRuleBasis": "2-Peratusan daripada Kenaikan",
          "FeeItemCurrencyCode": "GBP",
 "FeeItemCurrencySymbol": "$",
 "ProratedVolume": 123.12,
 "TotalVolume": 123.12,
          "FeeProduct": "1562-Bonus diesel Shell",
 "InvoiceGrossAmount": 123.12,
 "InvoiceNetAmount": 123.12,
 "JumlahVATInvois": 123.12,
 "AdakahYuranDibatalkan": true,
 "JumlahIsipaduProrataTingkatanBarangYuran": 123.12,
 "JumlahIsipaduTingkatanBarangYuranVolume": 123.12,
 "TierMinimum": 123,
 "TierRate": 123.12
 }
 ]
    }
  ],
  "Warnings": [
    {
 "Message": "Sistem sedang tidak aktif untuk peningkatan.",
 "Type": "Gangguan Sistem"
    }
  ]
}

Contoh 8: Dapatkan Ringkasan YuranPermintaan:

POST /transaction-data/v1/feessummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "CardId": 275549,
  "InvoiceStatus": "I",
  "FromDate": "20240101",
  "ToDate": "20240131",
  "FeeTypeGroup": "Caj Kad"
}

Respons:

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "FeeTypeGroup": "Caj Kad",
 "FeeTypeId": 1,
 "FeeType": "Caj Tahunan Kad",
 "ProductId": 1234,
 "ProductCode": "FEE",
 "ProductName": "Caj Kad",
      "TotalFeeAmount": 125.00,
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£"
    }
  ]
}

Contoh 9: Dapatkan Pengecualian TransaksiPermintaan:

POST /transaction-data/v1/exceptions

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "TransactionsFromDate": "20231223",
  "TransactionsToDate": "20240131",
  "Value": 100,
  "Condition": 5,
  "OutputType": "Transaction"
}

Respon:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
      "CardsExceptions": [
 {
 "AccountId": 29484,
 "CardId": 1234,
          "PAN": "ABCD1234",
 "DriverName": "ANDREW GILBERRY",
 "VRN": "34235",
          "PayerId": 123455,
 "PayerNumber": "GB000000123",
 "AccountNumber": "GB99215176",
 "AccountShortName": "MATTHEW",
 "NamaSingkatPembayar": "MATTHEW",
 "Hari": 2,
 "Minggu": 2,
 "Bulan": 5,
 "Tahun": 2017,
 "JumlahTransaksi": 4,
 "JumlahBaranganJualan": 4,
 "JumlahKuantiti": 261,
 "JumlahJumlah": 100.21,
          "KodMataWang": "GBP",
 "SimbolMataWang": "$"
 }
 ],
 "PengecualianTransaksi": [
        {
 "SalesItemId": 18315958002,
 "CardId": 1234,
 "ProductId": 2,
 "TransactionGUID": "ABCD1234",
 "TransactionDate": "20231223",
 "CustomerInvoiceValueTotalGross": 123.12,
 "CardPAN": "7002051006629891000",
 "CardExpiry": "20311223 12:12:12",
 "TransactionTime": "12:12:12",
 "UTCOffset": "+12:12:12",
 "FleetIdInput": "XYZ1234",
 "OdometerInput": 1234,
 "DriverName": "SALT",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "$",
 "TransactionCurrencyCode": "GBP",
          "TransactionCurrencySymbol": "£",
 "TransactionNetAmount": 123.12,
 "TransactionTax": 123.12,
 "TransactionGrossAmount": 123.12,
          "JumlahBersihInvois": 123.12,
 "CukaiInvois": 123.12,
 "JumlahKasarInvois": 123.1,
 "NegaraPembelian": "Perancis",
 "IDAkaun": 1234,
 "NomborAkaun": "GB99215176",
 "NamaAkaun": "MATTHEW ALGIE & COMPANY LIMITED",
 "NamaAkaunSingkat": "MATTHEW ALGIE & COMPANY LIMITED",
 "Kuantiti": 123.12,
 "ProdukBahanApi": true,
 "HargaSatuUnitInTransactionCurrency": 123.12,
 "UnitPriceInInvoiceCurrency": 123.12,
 "UnitDiscountTransactionCurrency": 123.12,
 "UnitDiscountInvoiceCurrency": 123.12,
 "IsInvoiced": true,
 "InvoiceNumber": "S04500493",
 "InvoiceDate": "20231223",
 "SiteCode": "50001",
          "SiteName": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "SiteCountry": "Jerman",
 "Location": {
 "Lat": "37.4224764",
            "Lng": "122.0842499"
 },
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "ReceiptNumber": "1234",
          "KodProduk": "TMF Charges",
 "NamaProduk": "Tanpa plumbum - Oktan tinggi",
 "IdKumpulanProduk": 1234,
 "NamaKumpulanProduk": "Kumpulan Produk Induk",
 "KadarPertukaranDelCo": 123.12,
          "ColCoExchangeRate": 123.12,
 "IsShellSite": true,
 "Network": "Shell PH",
 "SiteGroupId": 202,
 "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "PostingDate": "20231223 12:12:12",
          "IssuerCode": "7077 = CRT",
 "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
          "NegaraPelanggan": "Belanda",
 "KodPenerbit": "8 untuk 702188",
 "IDKumpulanKad": "200",
          "NomborSusunanKad": "2",
 "DigitSemak": "GHE1234",
 "KeteranganIDKembara": "Keterangan contoh",
 "KadarCukaiNilaiTambah": 0.2,
 "KategoriCukaiNilaiTambah": "3-Kecuali VAT",
 "VATatasJumlahBersih": 12.21,
 "NegaraVAT": "Belanda",
 "PotonganBerkuatKuasaDalamMataWangTransaksi": 0,
 "JenisTransaksi": "Pembelian apabila Kad Hadir, sebaliknya Kosong",
 "PINIndicator": "Y",
 "VATApplicable": "Y",
 "NetInvoiceIndicator": "Y",
 "CustomerCurrencyCode": "GBP",
          "SimbolMataWangPelanggan": "£",
 "PotonganUnitBerkuatKuasaDalamMataWangPelanggan": 123.12,
 "PotonganBerkuatKuasaDalamMataWangPelanggan": 123.12,
 "CukaiBaranganDanPerkhidmatanBerasaskanJumlahBersihDalamMataWangPelanggan": 123.12,
 "DiscountType": "3-Percentage",
 "TransactionStatus": "U",
 "PayerGroup": "12119008",
 "RefundFlag": "N",
 "OriginalSalesItemId": "1231",
 "DelcoName": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "DelcoCode": "NL10042616",
 "PayerName": "V.M. LE COMTE",
          "CardExpiryPeriod": "1901",
 "AuthorisationCode": "11256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
          "AllowClearing": "Y",
 "CRMNumber": "ABCD1234",
 "DisputeStatus": "6\tCharged Back to Site",
 "RebateRate": 28.279,
 "DelCoToColCoExchangeRate": 1,
 "NetEuroAmount": 37.93,
 "EuroRebateAmount": 0,
 "EuroVATAmount": 7.96,
 "NomborPelangganInduk": "DRG1234"
        }
 ]
    }
  ]
}

Contoh 10: Dapatkan Ringkasan Penggunaan KadPermintaan:

POST /transaction-data/v1/cardusagesummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "AccountId": 1234,
  "NomborAkaun": "GB000000123",
  "IdKad": 1234,
  "PAN": "7882861007636000020",
  "TarikhLuputKad": "20311223"
}

Respon:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "UsageSummary": [
        {
 "Tarikh": "20170930",
 "ID Produk": 1,
 "Kod Produk": "2",
          "ProductName": "Diesel AGO",
 "IsFuelProduct": true,
 "SiteGroupId": 1234,
 "SiteGroupName": "UK 9500 MOTORWAY NETWORK",
          "TotalVolume": 123.12,
 "TotalGross": 123.12,
 "TotalNet": 123.12,
 "CurrencyCode": "GBP",
 "CurrencySymbol": "£",
 "ProductGroupId": 1234,
 "ProductGroupName": "Petrol"
 }
 ]
    }
  ]
}

Penanganan RalatKod Ralat Umum

Status HTTPKod RalatPeneranganPenyelesaian200Tidak TerpakaiStatus: BERJAYAN/A200E0001Ralat PengesahanSemak parameter permintaan401E0003Tidak dibenarkanSemak kebenaran pengguna404E0005Tidak ditemuiN/A200E0001Ralat PengesahanSemak parameter permintaan401E0003Tidak dibenarkanN/A200E0001Ralat PengesahanSemak parameter permintaan401E0003Tidak dibenarkanN/A200E0001Ralat PengesahanSemak parameter permintaan401E0003Tidak dibenarkanN/A200E0001Ralat PengesahanSemak parameter permintaan401E0003Tidak dibenarkanN/A200E0001izedSemak token OAuth sah403E0003DilarangSemak kebenaran pengguna404E0005

Amalan Terbaik1. Gunakan Autentikasi OAuth 2.0PENTING: Semua pelanggan harus beralih ke autentikasi OAuth 2.0. Laksana pengurusan token yang betul:

Cache tokens akses dan gunakan semula sehingga tamat tempoh

Perbaharui token sebelum ia tamat (disyorkan 60 saat sebelum)

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

Jangan sekali-kali merekod atau mendedahkan token akses dalam kod sisi klien2. Gunakan ID PermintaanSentiasa sertakan RequestId unik (format GUID) untuk penjejakan hujung ke hujung3. Laksana PaginasiUntuk yang besar set PageSize yang sesuai (disyorkan: 50-100 rekod)

Proses halaman secara bersiri atau selari

Handle TotalPages dan TotalRecords dalam respons4. Gunakan Penapis Tarikh dengan BijakApabila membuat pertanyaan data transaksi:

Hadkan julat tarikh untuk mengelakkan set hasil yang besar

Gunakan penapis FromDate dan ToDate secara konsisten

Pertimbangkan untuk membuat pertanyaan mengikut bulan atau minggu untuk prestasi yang lebih baik

5. Uji dalam Persekitaran Sandbox

Sentiasa uji integrasi dalam persekitaran Uji/Sandbox sebelum beralih ke pengeluaran6. Simpan Data Rujukan dalam Penimbal (Cache)Simpan dalam penimbal harga berdasarkan volum dan peraturan bonus untuk meminimumkan panggilan API:

Peraturan ini jarang berubah

Baharui cache secara berkala (contohnya, setiap hari)

Gunakan parameter IncludeHistory hanya apabila diperlukanSDK & Contoh KodShell menyediakan SDK rasmi dan contoh kod menyeluruh untuk mempercepat integrasi anda dengan API Data Transaksi.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 - Pustaka PHP mudah digunakan

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

Sokongan: Sokongan Teknikal Shell

Migrasi OAuth 2.0: Sokongan Pemindahan OAuth 2.0Dokumentasi

Rujukan API

Muat turun Spesifikasi OpenAPIMendapatkan BantuanApabila menghubungi sokongan, berikan:

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

RequestId daripada respons API