B2B Mobility Customer Data Quickstart

บทนำ

B2B Mobility Customer Data API เป็นบริการ RESTful ที่ช่วยให้คุณสามารถค้นหาและจัดการรายละเอียดบัญชีลูกค้า กลุ่มบัตร และการกำหนดค่าที่เกี่ยวข้องภายในแพลตฟอร์ม Shell Cards ได้ API นี้มีความสามารถในการค้นหาที่ยืดหยุ่น รองรับการแบ่งหน้า และอนุญาตให้คุณดึงข้อมูลบัญชี ที่อยู่การจัดส่งบัตร รายการราคา และประเภทบัตร

นอกจากนี้ยังรองรับการดำเนินการสร้างและอัปเดตกลุ่มบัตร รวมถึงการย้ายบัตรระหว่างกลุ่ม

tr>

ประโยชน์	คำอธิบาย
การจัดการบัญชีแบบครบวงจร	เข้าถึงข้อมูลบัญชีลูกค้าโดยละเอียด รวมถึงการเรียกเก็บเงินสรุปบัตร, สถานะ
การดำเนินการกลุ่มบัตร	สร้าง, อัปเดต, และยกเลิกกลุ่มบัตรพร้อมความสามารถในการย้ายบัตรที่ยืดหยุ่น
การเข้าถึงรายการราคา	ดึงรายการราคาทั้งในประเทศและต่างประเทศพร้อมส่วนลดเฉพาะลูกค้า
การค้นหาที่ยืดหยุ่น	ค้นหาข้อมูลด้วยเกณฑ์การค้นหาหลายรายการพร้อมการรองรับการแบ่งหน้า

การตรวจสอบสิทธิ์

API นี้รองรับการตรวจสอบสิทธิ์ทั้งแบบ Basic Authentication และ OAuth 2.0 โดย OAuth 2.0 เป็นวิธีการตรวจสอบสิทธิ์ที่แนะนำเพื่อเพิ่มความปลอดภัย

หมายเหตุการย้ายข้อมูล

ขณะนี้ API รองรับการยืนยันตัวตนด้วย OAuth 2.0 แล้ว หากคุณกำลังใช้การยืนยันตัวตนแบบ Basic Authentication อยู่ในปัจจุบัน เราขอแนะนำให้ย้ายไปใช้ OAuth 2.0 เพื่อเพิ่มความปลอดภัย URL ฐานได้รับการอัปเดตแล้ว และทุกเอนด์พอยต์จะถูกจัดเวอร์ชันภายใต้เส้นทาง /v1 กรุณาดูคำแนะนำการย้ายข้อมูลโดยละเอียดได้ที่ OAuth 2.0 Migration Support

ขั้นตอนการอนุญาต

1. ขอรหัสไคลเอนต์และรหัสลับ

ติดต่อทีม API ของ Shell เพื่อขอสิทธิ์เข้าถึงการยืนยันตัวตน OAuth ทีม API ของ Shell จะให้รหัสไคลเอนต์และรหัสลับ

2. ขอโทเค็นผู้ถือ

เมื่อคุณได้รับข้อมูลประจำตัวแล้ว ให้ทำการร้องขอไปยัง จุดสิ้นสุดโทเค็น OAuth ของ API การตรวจสอบสิทธิ์ของ Shell โดยใช้ข้อมูลประจำตัวของคุณ

ตัวอย่างคำขอ:

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'

คุณจะได้รับ Bearer token ในการตอบกลับ:

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

หมายเหตุ: เวลาหมดอายุของโทเค็น Bearer จะแสดงเป็นวินาที

3. อนุญาตคำขอ API

เมื่อเรียกใช้ API ของ Shell ให้รวมข้อมูลต่อไปนี้ในหัวข้อของคำขอ

Authorization: Bearer access_token

Base URLs

Environment	URL
Test	https://api-test.shell.com/test
Production	https://api.shell.com

การรวมแกนกลาง

1. รับรายละเอียดผู้ใช้ที่เข้าสู่ระบบ

คำอธิบาย: จุดสิ้นสุดนี้จะดึงข้อมูลผู้ใช้ของผู้ใช้ที่เข้าสู่ระบบ รวมถึงผู้ชำระเงินที่สามารถเข้าถึงได้ บัญชี และบทบาท

การดำเนินการนี้ควรเรียกใช้หลังจากผ่านการตรวจสอบสิทธิ์สำเร็จแล้ว เพื่อรับค่า PayerId ที่จำเป็นสำหรับการเรียก API ในขั้นตอนถัดไป

เส้นทาง: POST /user-management/v1/loggedinuser

ตัวอย่างคำขอ

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

พารามิเตอร์คำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
RequestId	string	Yes	Mandatory UUID (RFC 4122) for request tracking
IncludePayerGroup	boolean	No	Include payer group information when true (default: false)
IncludeEIDDetails	บูลีน	ไม่	รวมข้อมูลใบแจ้งหนี้อิเล็กทรอนิกส์เมื่อเป็นจริง (ค่าเริ่มต้น: เท็จ)

ตัวอย่างการตอบกลับ

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "สถานะ": "สำเร็จ", "ข้อมูล": [ { "ชื่อผู้ใช้": "John123", "ชื่อที่แสดง": "John A.", "มีสิทธิ์เข้าถึง API": true, "ผู้ชำระเงิน": [
        { "IsDefault": true, "ColcoId": 1, "ColcoCode": 86, "PayerId": 1234, "PayerNumber": "GB000000123",
          "ผู้ชำระเงิน": "MATTHEW ALGIE & COMPANY LIMITED" } ] } ] }

ฟิลด์การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
ชื่อผู้ใช้	สตริง	ตัวระบุผู้ใช้ที่เข้าสู่ระบบ
ชื่อที่แสดง	สตริง	ชื่อของผู้ใช้ที่เข้าสู่ระบบ
มีสิทธิ์เข้าถึง API	บูลีน	จริงหากผู้ใช้มีสิทธิ์เข้าถึง API ที่ร้องขอ
PayerId	integer	หมายเลขผู้ชำระเงินสำหรับใช้ในคำขอถัดไป
PayerNumber	string	หมายเลขผู้ชำระเงินสำหรับใช้ในคำขอถัดไป

2.

สอบถามบัญชีลูกค้า

คำอธิบาย: จุดสิ้นสุดนี้อนุญาตให้สอบถามรายละเอียดบัญชีลูกค้าจากแพลตฟอร์ม Shell Cards ด้วยเกณฑ์การค้นหาที่ยืดหยุ่นและการรองรับการแบ่งหน้า ใช้ PayerId ที่ได้รับจากขั้นตอนก่อนหน้า

เส้นทาง: POST /customer-management/v1/accounts

ตัวอย่างคำขอ

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 '{
  "ตัวกรอง": { "ColCoCode": 86, "PayerNumber": "GB000000123", "Status": "ACTIVE", "IncludeCardSummary": true }, "หน้า": 1, "ขนาดหน้า": 50
}'

พารามิเตอร์ของคำขอ

(เปิดใช้งาน, ถูกบล็อก, ยกเลิก, ฯลฯ)

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
ColCoCode	integer	ใช่	รหัสบริษัทที่รวบรวม(Shell Code)
หมายเลขผู้ชำระเงิน	string	ใช่	หมายเลขผู้ชำระเงินของลูกค้า
สถานะ	string	ไม่	ตัวกรองสถานะบัญชี
รวมสรุปบัตร	บูลีน	ไม่	รวมรายละเอียดสรุปบัตร (ค่าเริ่มต้น: จริง)
หน้า	จำนวนเต็ม	ไม่	หมายเลขหน้า (ค่าเริ่มต้น: 1)
PageSize	integer	No	จำนวนรายการต่อหน้า (ค่าเริ่มต้น: 50)

ตัวอย่างการตอบกลับ

{ "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "สถานะ": "สำเร็จ", "ข้อมูล": [ { "รหัสบัญชี": 1, "หมายเลขบัญชี": "GB000000124",
      "AccountFullName": "Acme Corporation", "Status": "Active", "CurrencyCode": "EUR", "TotalCards": 1000, "TotalActiveCards": 500 } ], "Page": 1, "TotalRecords": 100,
  "TotalPages": 2, "PageSize": 50 }

ฟิลด์การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
AccountId	integer	รหัสบัญชี
หมายเลขบัญชี	string	หมายเลขบัญชี
ชื่อบัญชีเต็ม	string	ชื่อบัญชีเต็ม
สถานะ	string	สถานะบัญชีปัจจุบัน
รหัสสกุลเงิน	string	ISO currency code
TotalCards	integer	จำนวนบัตรทั้งหมดภายใต้บัญชี
TotalActiveCards	integer	จำนวนบัตรที่ใช้งานอยู่

3.กลุ่มบัตรสอบถาม

คำอธิบาย: จุดสิ้นสุดนี้ดึงรายละเอียดกลุ่มบัตรจากแพลตฟอร์ม Shell Cards ด้วยเกณฑ์การค้นหาที่ยืดหยุ่นและการจัดหน้า กลุ่มบัตรช่วยจัดระเบียบบัตรภายในบัญชี

เส้นทาง: POST /customer-management/v1/cardgroups

ตัวอย่างคำขอ

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 '{
  "ฟิลเตอร์": { "รหัสสี": 86, "หมายเลขผู้ชำระเงิน": "GB000000123", "สถานะ": "เปิดใช้งาน" },
  "Page": 1, "PageSize": 50 }

พารามิเตอร์คำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
ColCoCode	integer	Yes	รหัสบริษัทที่เก็บรวบรวม
PayerNumber	string	Yes	หมายเลขผู้ชำระเงินของลูกค้า
Status	string	Yes

td> สถานะกลุ่มบัตร (ACTIVE, TERMINATED, ALL) CardGroupName string No กรองตามชื่อกลุ่มบัตร (อย่างน้อย 2 ตัวอักษร)

ตัวอย่างการตอบกลับ

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c", "Status": "SUCCESS", "Data": [ { "CardGroupId": 40000, "CardGroupName":"006240 FIRE BRIGHT SOLUTIONS", "สถานะ": "เปิดใช้งาน", "PrintOnCard": true, "ประเภทบัตร": 1234, "จำนวนบัตรทั้งหมด": 1234, "จำนวนบัตรที่ใช้งานอยู่": 999 } ],
  "Page": 1, "TotalRecords": 100, "TotalPages": 2, "PageSize": 50 }

ฟิลด์การตอบกลับ

tr>

ฟิลด์	ประเภท	คำอธิบาย
CardGroupId	integer	รหัสกลุ่มบัตร
CardGroupName	string	ชื่อกลุ่มบัตร
Status	string	สถานะของกลุ่มบัตร
TotalCards	integer	จำนวนบัตรทั้งหมดในกลุ่ม
ActiveCards	integer	จำนวนบัตรที่ใช้งานในกลุ่ม

4. สร้างกลุ่มบัตร

คำอธิบาย: จุดสิ้นสุดนี้จะสร้างกลุ่มการ์ดใหม่ในแพลตฟอร์ม Shell Cards และอาจย้ายการ์ดได้สูงสุด 500 ใบไปยังกลุ่มที่สร้างขึ้นใหม่ คำขอการย้ายการ์ดจะถูกจัดคิวหลังจากผ่านการตรวจสอบแล้ว

เส้นทาง: POST /customer-management/v1/createcardgroup

ตัวอย่างคำขอ

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,
  "หมายเลขผู้ชำระเงิน": "GB000000123", "หมายเลขบัญชี": "GB000000124", "ชื่อกลุ่มบัตร": "006240 FIRE BRIGHT SOLUTIONS", "พิมพ์บนบัตร": true,
  "บัตร": [ { "หมายเลขบัญชี": "GB99215176", "PAN": "7002051006629890645" }
  ] }'

พารามิเตอร์ของคำขอ

(1-40 ตัวอักษร)

(สูงสุด 500)

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
ColCoCode	integer	ใช่	รหัสบริษัทที่รวบรวม
หมายเลขผู้ชำระเงิน	string	ใช่	หมายเลขผู้ชำระเงินของลูกค้า
หมายเลขบัญชี	string	ใช่	หมายเลขบัญชีของลูกค้า
ชื่อกลุ่มบัตร	string	ใช่	ชื่อกลุ่มบัตรใหม่
PrintOnCard	boolean	Yes	ว่าจะทำการปั๊มนูนชื่อกลุ่มบัตรลงบนบัตรหรือไม่
Cards	array	No	รายการบัตรที่จะย้าย

ตัวอย่างคำตอบ

{ "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "สถานะ": "สำเร็จ", "ข้อมูล": [ { "อ้างอิงหลัก": 1234, "อ้างอิงกลุ่มบัตรใหม่": 5672, "คำขอที่สำเร็จ": [ { "PAN": "7002051123456789145",
          "Reference": 12345 } ], "ErrorCards": [] } ] }

ฟิลด์การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
MainReference	integer	หมายเลขอ้างอิงสำหรับการติดตามคำขอทั้งหมด
NewCardGroupReference	integer	หมายเลขอ้างอิงสำหรับการสร้างกลุ่มบัตร
คำขอที่สำเร็จ	array	รายการคำขอการย้ายบัตรที่อยู่ในคิวสำเร็จ
บัตรที่ผิดพลาด	array	รายการบัตรที่ไม่ผ่านการตรวจสอบ

การจัดการข้อผิดพลาด

API ใช้รหัสสถานะ HTTP มาตรฐาน

ในกรณีที่มีข้อผิดพลาด รายละเอียดเพิ่มเติมจะถูกแจ้งในเนื้อหาของคำตอบ

รหัสข้อผิดพลาด	คำอธิบาย	วิธีแก้ไข
E0001	ข้อผิดพลาดในการตรวจสอบความถูกต้อง	ตรวจสอบพารามิเตอร์ของคำขอว่ามีค่าที่หายไปหรือไม่ถูกต้อง
E0003	ไม่ได้รับอนุญาต	ตรวจสอบข้อมูลรับรองและตรวจสอบให้แน่ใจว่าผู้ใช้มีสิทธิ์เข้าถึงการดำเนินการนี้
E0005	ไม่พบทรัพยากร	ยืนยันว่าทรัพยากรที่ร้องขอมีอยู่และสามารถเข้าถึงได้
9015	ชื่อกลุ่มบัตรซ้ำ	ใช้ชื่อกลุ่มบัตรที่ไม่ซ้ำกันสำหรับลูกค้า