Shell B2B Mobility Card Management API - คู่มือเริ่มต้นอย่างรวดเร็ว

เวอร์ชัน API: 3.1.5 | การยืนยันตัวตน: OAuth 2.0 | สถานะ: ใช้งานจริง

ภาพรวม

Shell Card Management API เป็น API ที่ใช้สถาปัตยกรรม REST ซึ่งช่วยให้ผู้พัฒนาสามารถจัดการบัตรเติมน้ำมัน Shell ได้โดยใช้โปรแกรม API นี้รองรับการค้นหาบัตร การสั่งซื้อ การอัปเดตสถานะ การยกเลิก และการดำเนินการจัดการบัตรอื่น ๆ

หมายเหตุ: คู่มือนี้ครอบคลุมเฉพาะจุดสิ้นสุดที่ผ่านการตรวจสอบสิทธิ์ OAuth 2.0 เท่านั้น (เส้นทางฐาน: /card-management/v1). จุดสิ้นสุดการตรวจสอบสิทธิ์พื้นฐานแบบเก่า (/fleetmanagement/v1/card) ไม่รวมอยู่ด้วยเนื่องจากกำลังถูกยกเลิกการใช้งาน

คุณสมบัติเด่น

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

ประกาศสำคัญ - OAuth 2.0

สำคัญ: OAuth 2.0 เป็นวิธีการยืนยันตัวตนมาตรฐานแล้ว

• การผสานรวมใหม่: ใช้ OAuth 2.0 ตั้งแต่เริ่มต้น
• การผสานระบบที่มีอยู่: วางแผนการย้ายไปใช้ OAuth 2.0
• วิธีการแบบเดิม: การยืนยันตัวตนขั้นพื้นฐานและคีย์ API กำลังถูกยกเลิก

ติดต่อ ฝ่ายสนับสนุนทางเทคนิคของ Shell เพื่อขอรับข้อมูลรับรอง OAuth 2.0 ของคุณ (client_id และ client_secret)

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

OAuth 2.0 (วิธีการตรวจสอบสิทธิ์มาตรฐาน)

API การจัดการบัตร Shell Card ใช้ กระบวนการ OAuth 2.0 Client Credentials เพื่อการตรวจสอบสิทธิ์ที่ปลอดภัย

คำเตือน: ลูกค้าทุกท่านควรวางแผนที่จะใช้การยืนยันตัวตนแบบ OAuth 2.0 นี่คือวิธีการยืนยันตัวตนที่แนะนำและรองรับอนาคตสำหรับ API การจัดการ Shell Card วิธีการยืนยันตัวตนแบบเก่าจะถูกยกเลิกการใช้งาน

กระบวนการ OAuth 2.0

ขั้นตอนที่ 1: รับ Access 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

ขั้นตอนที่ 2: ใช้ Access Token ในการร้องขอ API

Authorization: Bearer 
Content-Type: application/json

การจัดการโทเค็น

แนวทางปฏิบัติที่ดีที่สุดในการจัดการโทเค็น:

• โทเค็นการเข้าถึงมีอายุการใช้งานจำกัด (โดยปกติ 15 นาที)
• ใช้การแคชโทเค็นเพื่อหลีกเลี่ยงการร้องขอโทเค็นที่ไม่จำเป็น
• รีเฟรชโทเค็นก่อนหมดอายุเพื่อให้แน่ใจว่าจะไม่เกิดการขัดข้องในการให้บริการ
• อย่าแชร์ client_secret ของคุณหรือฝังไว้ในโค้ดฝั่งไคลเอนต์

กลยุทธ์การนำ OAuth 2.0 มาใช้

ทำไมต้องย้ายไปใช้ OAuth 2.0?

ประโยชน์ด้านความปลอดภัย:

• โปรโตคอลการยืนยันตัวตนมาตรฐานอุตสาหกรรม
• โทเค็นการเข้าถึงแบบจำกัดเวลาช่วยลดความเสี่ยงด้านความปลอดภัย
• ไม่มีการส่งข้อมูลรับรองพร้อมกับแต่ละคำขอ
• รองรับการหมุนเวียนและการเพิกถอนโทเค็นได้ดีขึ้น

ประโยชน์ด้านการดำเนินงาน:

• ปรับปรุงความสามารถในการขยายตัวและประสิทธิภาพ
• ความสามารถในการตรวจสอบและตรวจสอบที่ดีขึ้น
• การจัดการข้อมูลรับรองที่ง่ายขึ้น
• การผสานรวมที่รองรับอนาคต

เส้นทางการย้ายระบบ

หากคุณกำลังใช้วิธีการยืนยันตัวตนแบบเก่าอยู่ ให้ทำตามเส้นทางการย้ายระบบนี้:

1. ขอข้อมูลรับรอง OAuth 2.0 จาก ฝ่ายสนับสนุนด้านเทคนิคของ Shell
2. ดำเนินการจัดการโทเค็น OAuth ในแอปพลิเคชันของคุณ
3. ทดสอบอย่างละเอียด ใน Test/สภาพแวดล้อมแซนด์บ็อกซ์
4. ดำเนินการตรวจสอบสิทธิ์แบบขนาน (OAuth + แบบเดิม) ระหว่างการเปลี่ยนผ่าน
5. ตรวจสอบและยืนยัน การผสานรวม OAuth
6. เปลี่ยนไปใช้ OAuth เท่านั้น เมื่อได้รับการยืนยันแล้ว
7. ยกเลิกการใช้งานการยืนยันตัวตนแบบเดิม หลังจากการย้ายข้อมูลสำเร็จ

สภาพแวดล้อม

API มีให้บริการในสองสภาพแวดล้อม:

เคล็ดลับ: ควรทดสอบการผสานระบบของคุณใน สภาพแวดล้อมทดสอบ ก่อนที่จะนำไปใช้งานจริงเสมอ

เริ่มต้นอย่างรวดเร็ว

1. รับข้อมูลประจำตัว OAuth ของคุณ

• ติดต่อ ฝ่ายสนับสนุนทางเทคนิคของ Shell
• ขอข้อมูลรับรอง OAuth 2.0 (client_id และ client_secret)
• รีวิว ข้อกำหนดในการให้บริการ

2. รับโทเค็นการเข้าถึง

ขั้นแรก รับโทเค็นการเข้าถึง OAuth ของคุณ:

ตัวอย่าง cURL:

curl -X POST https://api-test.shell.com/test/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"

Response:

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

3. สร้างคำขอ API ครั้งแรกของคุณ

ตัวอย่าง: ค้นหาบัตรที่ใช้งานอยู่

ตัวอย่าง 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": {
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"CardStatus": ["ACTIVE"]
},
"หน้า": "1",
"ขนาดหน้า": "50"
}'

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

{
"RequestId": "233e4567-e89b-12d3-a456-426614174000",
"สถานะ": "สำเร็จ",
"ข้อมูล": [
{
"หมายเลขบัตร": 125,
"PAN": "7002861007636000020",
"MaskedPAN": "7002861**000020",
"ชื่อคนขับ": "โรเบิร์ต สมิธ",
"หมายเลขทะเบียนรถ": "MV65YLH",
"คำอธิบายสถานะ": "ใช้งานอยู่",
"ExpiryDate": "20250531",
"CardTypeCode": "7077861",
"CardTypeName": "Shell Card"
}
],
"Page": 1,
"PageSize": 50,
"TotalPages": 1,
"TotalRecords": 1
}

API Endpoints Reference

Card Search & Retrieval

กรณีการใช้งานทั่วไป:

• ค้นหาตามสถานะบัตร (ใช้งานได้, ถูกระงับ, หมดอายุ, ฯลฯ)
• กรองตามชื่อผู้ขับขี่หรือหมายเลขทะเบียนรถ
• ค้นหาด้วยหมายเลขประจำตัวประชาชน
(4 หลักสุดท้าย)
• ค้นหาบัตรที่หมดอายุใน X วัน

สรุปบัตร

ผลลัพธ์:

• จำนวนบัตรทั้งหมดตามสถานะ
• สถิติสรุปตามประเภทบัตร
• การแยกประเภทบัตรที่ใช้งานกับไม่ได้ใช้งาน

การจัดลำดับบัตร

ข้อมูลที่จำเป็นสำหรับการสั่งทำบัตร:

• ColCoCode (รหัสบริษัทที่รวบรวม)
• หมายเลขผู้จ่ายเงินหรือ PayerId
• หมายเลขบัญชี
• ประเภทและการกำหนดค่าบัตร
• รายละเอียดที่อยู่จัดส่ง

การจัดการสถานะบัตร

ตัวอย่างการใช้งาน

ตัวอย่างที่ 1:

POST /card-management/v1/search

{
"Filters": {
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"สถานะบัตร": ["ใช้งานอยู่"],
"วันหมดอายุในอีก": 30
},
"หน้า": "1",
"PageSize": "100"
}

POST /card-management/v1/updatestatus

{
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"Cards": [
{
"CardId": 125,
"Action": "TEMP_BLOCK_CUSTOMER",
"Reason": "บัตรถูกวางผิดที่ชั่วคราว"
}
]
}

POST /card-management/v1/cancel

{
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"บัตร": [
{
"หมายเลขบัตร": 125,
"วันหมดอายุบัตร": "20231231"
}
],
"ข้อความเหตุผล": "สูญหาย",
"RequestId": "1" }