การยืนยันตัวตน

EasySlip API ใช้ HMAC-SHA256 Signature Authentication เพื่อความปลอดภัยในการเข้าถึง API

HMAC Authentication

API v2 ใช้ HMAC-SHA256 Signature Authentication เพื่อความปลอดภัยที่สูงขึ้น ใช้ Header X-API-Key เดียวสำหรับทุก endpoint — รูปแบบของ key จะกำหนด flow การยืนยันตัวตน:

ประเภท Key	รูปแบบ	ใช้สำหรับ
Branch UUID	UUID v4 (เช่น a1b2c3d4-e5f6-...)	/verify/bank, /verify/truewallet, /info
B2B Client Key	hex 64 ตัวอักษร	/b2b/* endpoint จัดการ

Headers ที่จำเป็น

Header	คำอธิบาย
X-API-Key	Branch UUID หรือ B2B Client hex key
X-Timestamp	Unix Timestamp (วินาที)
X-Nonce	UUID v4 ไม่ซ้ำต่อ Request
X-Signature	HMAC-SHA256 Signature

วิธีการทำงาน

• สำหรับ endpoint ตรวจสอบสลิป/ข้อมูล: ใช้ Branch UUID เป็น X-API-Key เซิร์ฟเวอร์จะค้นหาสาขา หา B2B client ที่เชื่อมโยง และตรวจสอบ HMAC signature ด้วย secret key ของ B2B client
• สำหรับ endpoint จัดการ B2B: ใช้ key hex 64 ตัวอักษรเป็น X-API-Key เซิร์ฟเวอร์จะค้นหา B2B client โดยตรง

ทั้งสองกรณีใช้ secret key เดียวกันจาก B2B client ในการลงนาม request

สำหรับรายละเอียดการ Implement, ตัวอย่างโค้ด, และการสร้าง Signature ดู คู่มือ Authentication

แนวทางปฏิบัติด้านความปลอดภัย

1. อย่าเปิดเผย Key ในโค้ด Client-side

// ❌ ไม่ควรทำ
const API_KEY = 'your-api-key-here';

// ✅ ควรทำ - ใช้ Environment Variables
const API_KEY = process.env.EASYSLIP_API_KEY;

2. ใช้ Environment Variables

.env

EASYSLIP_API_KEY=your-api-key-here

Node.js

import 'dotenv/config';

const apiKey = process.env.EASYSLIP_API_KEY;

PHP

$apiKey = getenv('EASYSLIP_API_KEY');
// หรือ
$apiKey = $_ENV['EASYSLIP_API_KEY'];

Python

import os

api_key = os.environ.get('EASYSLIP_API_KEY')

3. ทำ Request จาก Server เท่านั้น

ทำ API Request จากฝั่ง Server เสมอ ไม่ใช่จาก Client-side JavaScript:

// ❌ ไม่ควรทำ - Client-side request เปิดเผย API key และ secret
fetch('https://api.easyslip.com/v2/verify/bank', {
  headers: { 'X-API-Key': 'your-branch-uuid', 'X-Signature': '...' }
});

// ✅ ควรทำ - Request ผ่าน Server ของคุณ
fetch('/api/verify-slip', {
  method: 'POST',
  body: JSON.stringify({ image: slipImage })
});

4. IP Whitelisting

ตั้งค่า IP Whitelist ใน Developer Portal เพื่อจำกัดการเข้าถึง API เฉพาะ IP ที่กำหนด:

1. ไปที่ ตั้งค่าแอปพลิเคชัน
2. เพิ่ม IP Address ของ Server ลงใน Whitelist
3. ใช้ * เพื่ออนุญาตทุก IP (ไม่แนะนำสำหรับ Production)

ข้อผิดพลาดการยืนยันตัวตน

ไม่มี API Key (401)

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Authorization header is required"
  }
}

วิธีแก้ไข: ใส่ Header X-API-Key ใน Request

API Key ไม่ถูกต้อง (401)

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

วิธีแก้ไข: ตรวจสอบว่า API Key ถูกต้องและไม่ถูกยกเลิก

IP ไม่อนุญาต (403)

{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Your IP address is not in the allowed list"
  }
}

วิธีแก้ไข: เพิ่ม IP ของ Server ลงใน Whitelist ใน Developer Portal

Branch ถูกปิดใช้งาน (403)

{
  "success": false,
  "error": {
    "code": "BRANCH_INACTIVE",
    "message": "This API branch has been deactivated"
  }
}

วิธีแก้ไข: เปิดใช้งาน Branch ใหม่ใน Developer Portal หรือติดต่อ Support

เกินโควต้า (403)

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Your API quota has been exceeded"
  }
}

วิธีแก้ไข: อัพเกรดแพ็กเกจ หรือรอให้โควต้ารีเซ็ต

รองรับหลาย Branch

EasySlip รองรับหลาย Branch ต่อแอปพลิเคชัน แต่ละ Branch มี API Key แยกกัน:

• Main Branch: API Key หลัก มีโควต้าเต็ม
• Sub-Branches: API Key เพิ่มเติม มีการติดตามโควต้าแยก

ช่วยให้คุณ:

• ติดตามการใช้งานต่อจุดเชื่อมต่อ
• กำหนด IP Restrictions ที่ต่างกันต่อ Branch
• จัดการการจัดสรรโควต้าระหว่างทีม

ขั้นตอนถัดไป

• B2B Authentication - รายละเอียด HMAC Authentication
• API v2 Reference - สำรวจ Endpoints ของ v2
• รหัสข้อผิดพลาด - รายการ Error Code ทั้งหมด