LikeSlip API v1 — เอกสาร

Base URL: https://your-domain.com/api/v1

การยืนยันตัวตน (Authentication)

ส่ง API Key ใน header ทุก request:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxx

API Key สร้างได้จากหน้า ตั้งค่า → API & Webhook
Key ที่ถูกเพิกถอน (revoked) จะได้รับ HTTP 401

Idempotency

Endpoint POST /slips/verify ต้องส่ง header Idempotency-Key ทุกครั้ง — ค่านี้จะถูกใช้เป็น request_id ในระบบ

Key เดิม + payload เดิม → ส่งคืนผลเดิม ไม่หักโทเคนซ้ำ
Key เดิม + payload ต่างกัน → HTTP 409 IDEMPOTENCY_MISMATCH

ใช้ UUID v4 หรือ order reference ที่ไม่ซ้ำกันเป็น Idempotency-Key

Endpoints

POST /api/v1/slips/verify

ส่งสลิปเพื่อตรวจสอบ รับได้ 2 รูปแบบ:

Multipart: field image (JPEG/PNG/WebP ≤ 5 MB) หรือ qr
JSON: { "qr": "...", "expected_amount": "100.00" }

Headers ที่ต้องการ:

Authorization: Bearer sk_live_...
Idempotency-Key: <unique-key>

Fields:

Field	ประเภท	คำอธิบาย
image	File	รูปสลิป (multipart เท่านั้น)
qr	string	ข้อมูล QR จากสลิป
expected_amount	string	ยอดที่คาดหวัง (บาท เช่น "100.00")
order_ref	string	เลขอ้างอิงคำสั่งซื้อ
receiver_account_id	string	ID บัญชีรับเงินที่ต้องตรวจ
branch_id	string	ID สาขา

GET /api/v1/slips/:request_id

ดูผลตรวจสอบสลิปตาม request_id (ต้องเป็น key ของร้านเดียวกัน)

GET /api/v1/balance

ดูยอดโทเคน เครดิต แพ็กเกจปัจจุบัน และอัตราการหักโทเคน

รูปแบบ Response

ทุก endpoint ใช้รูปแบบเดียวกัน:

// สำเร็จ
{
  "success": true,
  "data": { ... }
}

// ผิดพลาด
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "คำอธิบาย"
  }
}

ยอดเงินในการตอบกลับเป็น string หน่วยบาท (เช่น "100.50"), โทเคนเป็น string (เช่น "1.000")

Status & Reason Codes

Status	ความหมาย
checking	กำลังตรวจสอบ (ยังไม่เสร็จ)
passed	ผ่านทุกเงื่อนไข
failed	ไม่ผ่านเงื่อนไข (ดู reason)
unverifiable	ตรวจไม่ได้ (ข้อมูลไม่ครบ)
provider_error	ระบบตรวจสลิปขัดข้อง

Reason Code	ความหมาย
QR_UNREADABLE	อ่าน QR จากสลิปไม่ได้ — คืนโทเคน
TX_NOT_FOUND	ไม่พบรายการในระบบธนาคาร — คืนโทเคน
RECEIVER_MISMATCH	บัญชีผู้รับไม่ตรง — หักโทเคน
AMOUNT_MISMATCH	ยอดเงินไม่ตรง — หักโทเคน
SLIP_TOO_OLD	สลิปเก่าเกินกำหนด — หักโทเคน
BEFORE_ORDER	โอนก่อนสร้างคำสั่งซื้อ — หักโทเคน
DUPLICATE	สลิปนี้ถูกใช้แล้ว — หักโทเคน
PROVIDER_ERROR	ระบบตรวจสลิปขัดข้อง — คืนโทเคน
INSUFFICIENT_TOKEN	โทเคนไม่เพียงพอ — ไม่หัก
PLAN_EXPIRED	แพ็กเกจหมดอายุ — ไม่หัก

กฎการหักโทเคน

หักโทเคน: เมื่อ slip-checker พบรายการ (ไม่ว่าจะผ่านเงื่อนไขหรือไม่)
คืนโทเคน: เมื่ออ่าน QR ไม่ได้ / ไม่พบรายการ / ระบบตรวจสลิปขัดข้อง
ถ้าโทเคนหมดและเปิด Credit Overflow ไว้ จะหักเครดิตแทนในอัตราตามแพ็กเกจ

Webhook

ตั้งค่า Webhook URL ได้จากหน้า ตั้งค่า → Webhook

Headers ที่ส่งมาพร้อม event:

X-Signature: <hmac-hex>
X-Timestamp: <unix-seconds>
X-Event-Id: <uuid>

การตรวจสอบลายเซ็น

// HMAC-SHA256 over "{timestamp}.{raw_body}"
$expected = hash_hmac('sha256', $timestamp . '.' . $raw_body, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}
// ตรวจอายุ (ไม่เกิน 300 วินาที)
if (abs(time() - intval($timestamp)) > 300) {
    http_response_code(401);
    exit;
}

Event Types

Type	เกิดเมื่อ
slip.checked	ตรวจสลิปเสร็จ (ทุก status)

Webhook จะส่งซ้ำสูงสุด 6 ครั้ง (exponential backoff) หากปลายทางตอบ non-2xx

Rate Limits

จำนวน request ต่อนาทีขึ้นกับแพ็กเกจ (ดูได้จาก GET /api/v1/balance → rates.rate_limit_rpm)

เมื่อเกินจะได้รับ HTTP 429 พร้อม code: "RATE_LIMIT_EXCEEDED"