จัดการ error และรหัสผลลัพธ์จาก API ตรวจสลิปให้ถูกต้อง

นักพัฒนาจำนวนมากเขียนโค้ดเชื่อม API ตรวจสลิปเสร็จภายในครึ่งวัน แต่มาเจอปัญหาจริงหลังขึ้นระบบ เพราะโค้ดดูแค่ว่า HTTP ตอบ 200 หรือไม่ แล้วสรุปว่าลูกค้าจ่ายเงินแล้ว บทความนี้อธิบายวิธีอ่านผลลัพธ์จาก API ของ PPay ให้ถูกต้อง แยกประเภทข้อผิดพลาดให้ชัด และตัดสินใจว่าเมื่อไรควรลองใหม่ เมื่อไรควรแจ้งลูกค้า

ผลลัพธ์มีสามชั้น ไม่ใช่สองชั้น

เวลาเรียก POST /api/v1/verify คุณจะเจอสถานการณ์ได้สามแบบ และแต่ละแบบต้องจัดการต่างกัน

• คำขอถูกปฏิเสธ — HTTP status ไม่ใช่ 2xx พร้อมรูปแบบ { "ok": false, "code": "...", "error": "..." } กรณีนี้ไม่มีการหักโควต้าหรือเครดิต
• ตรวจเสร็จแล้ว — HTTP 200 และมีฟิลด์ valid, result, code ที่บอกผลจริง
• ระบบรับเข้าคิว — HTTP 202 พร้อม queued: true และ jobId ช่วงที่ระบบหนาแน่นหรือผู้ให้บริการตรวจสลิปขัดข้องชั่วคราว

จุดที่พลาดบ่อยที่สุดคือ HTTP 200 ไม่ได้แปลว่าสลิปถูกต้อง สลิปปลอมหรือสลิปซ้ำก็ตอบ 200 แต่ valid เป็น false ดังนั้นต้องอ่านฟิลด์ valid และ code เสมอ

ฟิลด์ result ใช้แบ่งกลุ่มใหญ่ได้เลย

ฟิลด์ result มีสามค่า ซึ่งเป็นตัวแบ่งกลุ่มที่ใช้งานง่ายที่สุด

result	ตัวอย่าง code	ควรทำอย่างไร
valid	VALID	ไปเทียบยอดและผู้รับกับออเดอร์ของคุณต่อ
invalid	INVALID_SLIP, SLIP_NOT_FOUND, DUPLICATE_SLIP	แจ้งลูกค้าตามสาเหตุ ห้ามลองซ้ำอัตโนมัติ
error	SERVICE_UNAVAILABLE, NOT_CONFIGURED, INTERNAL_ERROR	ระบบขัดข้อง คืนโควต้าหรือเครดิตแล้ว ลองใหม่ภายหลังได้

ข้อสำคัญคือให้ใช้ code ในโค้ดของคุณ ไม่ควรเทียบกับข้อความ message เพราะข้อความมีไว้แสดงให้ผู้ใช้ปลายทางอ่านและอาจปรับถ้อยคำได้

สำหรับสลิปที่ผู้ใช้เห็นแล้วงงที่สุดคือ SLIP_NOT_FOUND เพราะเอกสารระบุว่าอาจเป็นเพราะเพิ่งโอนเงินและยังไม่พบรายการในระบบธนาคาร ลองใหม่ได้ใน 1-2 นาที หรืออ่าน QR ในรูปไม่ได้ ซึ่งมักเกิดจากรูปที่ถูกครอปหรือบีบอัดมาก ข้อความที่แสดงให้ลูกค้าควรบอกทางออกชัดเจน เช่น ให้รอสักครู่แล้วส่งรูปต้นฉบับจากแอปธนาคารอีกครั้ง

รหัสข้อผิดพลาดของคำขอ

กลุ่มที่ HTTP ไม่ใช่ 2xx แยกตามความหมายได้ดังนี้

• 400 — INVALID_FILE, INVALID_REFERENCE, INVALID_FILE_COUNT เป็นปัญหาที่ข้อมูลที่ส่ง แก้ที่ฝั่งผู้เรียก ลองซ้ำด้วยข้อมูลเดิมไม่ช่วย
• 401 — INVALID_API_KEY คีย์ผิด ถูกเพิกถอน หรือบัญชีถูกระงับ ต้องแจ้งเตือนผู้ดูแลระบบของคุณ ไม่ใช่แจ้งลูกค้า
• 402 — INSUFFICIENT_BALANCE โควต้าและเครดิตหมด ควรมีการแจ้งเตือนภายในก่อนถึงจุดนี้
• 413 — FILE_TOO_LARGE รูปใหญ่เกินหรือคำขอไม่ใช่ multipart ปกติ
• 429 — RATE_LIMITED ให้รอตาม header Retry-After (หน่วยวินาที) ส่วน QUEUE_FULL แปลว่ามีงานค้างครบ 100 งาน ต้องรอให้ประมวลผลเสร็จ
• 503 — STORAGE_UNAVAILABLE หรือ QUEUE_UNAVAILABLE ระบบขัดข้องชั่วคราวและไม่หักเงิน ลองใหม่ได้

ตัวอย่างโค้ดแยกประเภทผลลัพธ์

ตัวอย่างนี้ต่อยอดจากโค้ด Node.js ในคู่มือ โดยแยกผลลัพธ์เป็นกลุ่มที่ระบบของคุณเอาไปตัดสินใจต่อได้ง่าย

async function classify(res) {
  const data = await res.json();
  if (res.status === 202) return { kind: "queued", jobId: data.jobId };
  if (!res.ok) {
    const retryable = res.status === 429 || res.status === 503;
    return { kind: "request-error", code: data.code, retryable: retryable,
             retryAfter: res.headers.get("retry-after") };
  }
  if (data.valid) return { kind: "valid", slip: data.slip };
  if (data.result === "error") return { kind: "system-error", code: data.code, retryable: true };
  return { kind: "rejected", code: data.code };   // invalid: tell the customer, do not auto-retry
}

สังเกตว่ากลุ่ม rejected ไม่มี retry อัตโนมัติ เพราะคู่มือเตือนไว้ว่าการส่งสลิปใบเดิมซ้ำจะได้ DUPLICATE_SLIP และถูกหักเพิ่มอีกครั้ง

ผ่าน valid แล้วยังไม่จบ

เมื่อ valid เป็น true แปลว่าสลิปเป็นของจริงและยังไม่เคยใช้ แต่การตัดสินว่ายอดและบัญชีผู้รับตรงกับออเดอร์หรือไม่ เป็นหน้าที่ของระบบคุณ ให้เทียบ slip.amount และ slip.receiver กับออเดอร์ก่อนอนุมัติ หากผูกกับร้านค้าด้วยฟิลด์ shop ระบบจะตรวจผู้รับให้ และถ้าไม่ตรงจะได้ RECEIVER_MISMATCH อ่านเพิ่มเรื่องการตรวจผู้รับได้ที่ การตรวจบัญชีผู้รับในสลิป และเรื่องยอดไม่ตรงที่ ยอดในสลิปไม่ตรงกับออเดอร์

เช็กลิสต์ก่อนขึ้นระบบจริง

1. รองรับทั้ง HTTP 200 และ 202 ในทุก endpoint ที่รอผล
2. ใช้ code ในการตัดสินใจ ไม่ใช้ข้อความ
3. แยกข้อผิดพลาดที่ลองใหม่ได้ (429, 503, result: "error") ออกจากที่ลองใหม่ไม่ได้
4. บันทึก id หรือ jobId ของทุกคำขอไว้ใน log เพื่อตรวจย้อนหลัง
5. ตั้งการแจ้งเตือนภายในเมื่อเจอ 401 หรือ 402
6. แสดงข้อความถึงลูกค้าเป็นภาษาที่เข้าใจง่ายและบอกขั้นตอนถัดไป

รายละเอียดครบทุกรหัสอยู่ใน คู่มือ API หากยังไม่มีบัญชี สามารถ สมัครสมาชิก แล้วสร้าง API key เพื่อลองยิงรูปสลิปจริงดูผลลัพธ์แต่ละแบบได้เลย