Async Verify - Bank
ตรวจสอบสลิปโอนเงินธนาคารไทยแบบ อะซิงโครนัส (asynchronous) ไม่ต้องรอผลใน HTTP Response คุณส่งสลิปเข้าคิวทีละรายการหรือหลายรายการ แล้วรับผลทาง Webhook Callback (หรือใช้ Polling เป็นทางสำรอง)
ระบบนี้ทำงาน คู่ขนาน กับ POST /verify/bank แบบซิงโครนัส ซึ่งยังทำงานเหมือนเดิม เลือกใช้แบบ async เมื่อต้องการ:
- ตรวจสอบ จำนวนมาก (bulk) (ส่งได้สูงสุด 100 สลิปในครั้งเดียว)
- ใช้คิวแยกจังหวะการรับคำขอออกจากการตรวจ (แต่ async ไม่ได้ข้าม rate limit: ตอนส่งอาจได้
429RATE_LIMIT_EXCEEDEDและงานที่รับแล้วอาจต้องรอ capacity ของ worker) - ตรวจสลิปที่ข้อมูลมาช้า (เช่น ธนาคารกรุงเทพ) Job จะ retry อยู่เบื้องหลังตามจำนวนรอบที่ระบุด้านล่าง
Base URL
https://api.easyslip.com/v2การยืนยันตัวตน
ต้องยืนยันตัวตนด้วย API Key ของ Branch เดียวกัน กับที่ใช้ตรวจสอบสลิปแบบซิงโครนัส ดู คู่มือการยืนยันตัวตน
Authorization: Bearer YOUR_API_KEYEndpoints
| Endpoint | Method | คำอธิบาย |
|---|---|---|
/verify/bank/async | POST | ส่ง 1 สลิปเข้าคิว → 202 พร้อม jobId |
/verify/bank/batch | POST | ส่ง หลาย สลิป (สูงสุด 100) → 202 พร้อม batchId + jobs |
/verify/bank/jobs/:jobId | GET | ดึงสถานะ/ผลลัพธ์ของ Job (ทางสำรองหากพลาด Webhook) |
สลิปแต่ละรายการที่เข้าคิวจะได้ Webhook Callback 1 ครั้ง สลิปใน Batch ก็เช่นกัน (1 callback ต่อ 1 สลิป ไม่ใช่ 1 ต่อ batch)
หลักการทำงาน
- ส่งเข้าคิว ด้วย
POST /verify/bank/async(หรือหลายรายการด้วย/batch) ได้jobIdกลับมาทันที (202 Accepted) ตอนนี้สลิปยังไม่ถูกตรวจสอบ - ถ้าทุกธนาคารตอบ
not_foundหรือ BBL ยัง pending ระบบจะ retry สูงสุด 4 ครั้ง เว้นช่วง 30/60/120/240 วินาที (ตรวจรวม 5 ครั้ง) เวลารอตามตารางนี้รวม 7 นาที 30 วินาที ยังไม่นับเวลาประมวลผลและรอคิว ถ้าพบสลิปเมื่อไรก็จบทันที - EasySlip เข้าคิวส่ง Webhook ผลเป็น
success,not_foundหรือfailedกรณีสำเร็จdataจะเหมือนแบบ sync กรณีfailedจะได้data: nullกับerror.code/messageที่ปลอดภัย ถ้าล้มเหลวเพราะ billing จะส่งผลล้มเหลวหลังใช้ retry ของ billing ครบแล้ว - ถ้าพลาด Webhook ให้เรียก
GET /verify/bank/jobs/:jobIdดึงข้อมูล Job มาเอง (เก็บไว้ ~7 วัน)
การระบุ Callback URL
แต่ละคำขอระบุ callbackUrl เองได้ ถ้าไม่ระบุ ระบบจะใช้ Default Webhook URL ที่ตั้งไว้ของ Branch
| กฎ | พฤติกรรม |
|---|---|
ระบุ callbackUrl | ระบบ POST Webhook ผลลัพธ์ไปที่ URL นั้น (ใช้แทน default ของ branch) |
ไม่ระบุ callbackUrl | ใช้ Default Webhook URL ที่ตั้งค่าไว้ของ Branch |
| ไม่ได้ตั้งทั้งคู่ | 400 VALIDATION_ERROR |
ไม่ใช่ https | 400 INVALID_CALLBACK_URL |
| ชี้ไปยัง address ภายใน/private | 400 INVALID_CALLBACK_URL |
HTTPS เท่านั้น
callbackUrl ต้องเป็น URL https:// สาธารณะ ระบบปฏิเสธ URL ที่ไม่ใช่ HTTPS และ URL ที่ชี้ไป private/internal IP range เพื่อความปลอดภัย
Default Webhook URL และ Secret ที่ใช้เซ็นลายเซ็นตั้งได้ในการตั้งค่า Webhook ของ Branch วิธีตรวจลายเซ็นอยู่ที่หน้า Webhook Callback
Quota และรายการซ้ำ
การตรวจสอบแบบ async คิดค่าใช้จ่ายเหมือนแบบ sync:
- Quota: หัก quota เฉพาะการตรวจสอบที่สำเร็จ รายการที่ล้มเหลวหรือซ้ำไม่หัก
- รายการซ้ำ: ส่ง
checkDuplicate: trueเพื่อให้ได้isDuplicateของสลิปที่ Branch เดิม เคยตรวจแล้ว ไม่ว่าทาง sync หรือ async ค่าเริ่มต้นคือfalseซึ่งจะไม่ส่งฟิลด์นี้กลับมา รายการซ้ำใน Branch เดิมไม่หัก quota ซ้ำ
รหัส Error
| รหัส | HTTP Status | คำอธิบาย |
|---|---|---|
VALIDATION_ERROR | 400 | Body ไม่ถูกต้อง, สลิปว่าง, Batch เกิน 100 สลิป หรือไม่มี callbackUrl และไม่มี default ของ branch |
INVALID_CALLBACK_URL | 400 | callbackUrl ไม่ใช่ https หรือชี้ไปยัง address ภายใน/private |
JOB_NOT_FOUND | 404 | ไม่พบ Job / Job หมดอายุ หรือ Job ไม่ได้เป็นของ Branch คุณ |
Error การยืนยันตัวตนมาตรฐาน (MISSING_API_KEY, INVALID_API_KEY, SERVICE_EXPIRED, QUOTA_EXCEEDED ฯลฯ) ก็เกิดที่นี่ได้เช่นกัน ดู อ้างอิงรหัส Error