เอกสาร Integration: ThaiID Popup Reader Callback (GET/POST)

เวอร์ชัน: 1.4
อัปเดตล่าสุด: 2026-02-07

เอกสารนี้ประกอบด้วย:

1. Flow diagram (ผังงาน)
2. คู่มือสำหรับทีม Backend
3. เอกสาร API callback format (GET/POST)

---

1) Flow diagram (ผังงาน)

---

2) คู่มือสำหรับทีม Backend

2.1 ภาพรวม

Backend จะได้รับ callback ได้ 2 รูปแบบ โดย payload เหมือนกัน ต่างกันแค่ “วิธีส่ง”:

• GET: แอปเปิด URL callback พร้อม query string
• POST (multipart/form-data): แอป POST ไปที่ callback_url เดิมด้วย multipart/form-data

2.2 เงื่อนไขความสำเร็จ/ล้มเหลว

• POST: สำเร็จเมื่อ server ตอบ HTTP 2xx
• POST: ถ้า server ตอบ 4xx/5xx หรือ timeout → แอปจะแสดง “ส่งไม่สำเร็จ” และให้กด “ลองส่งอีกครั้ง”
• GET: แอปถือว่าสำเร็จเมื่อ launchUrl เปิดได้

2.3 ขนาดข้อมูล

เมื่อ img_require=true payload อาจใหญ่เพราะมี base64 รูปภาพ (อาจถูก chunk) ควรรองรับ body size และจำนวนฟิลด์ photo_p0..photo_pN.

2.4 การประกอบรูปจาก chunks

• ถ้ามี photo_b64: decode base64 → bytes
• ถ้ามี photo_parts + photo_p0..photo_pN: ต่อสตริงตามลำดับ แล้ว decode base64 → bytes

2.5 Security & Idempotency

• แนะนำใช้ HTTPS + token/secret ใน callback_url
• กันข้อมูลซ้ำ (ผู้ใช้กดส่งใหม่) ด้วย idempotency key หรือ request_id

---

3) เอกสาร API callback format (GET/POST)

3.1 Common fields (เหมือนกันทั้ง GET/POST)

• ok: "1"
• state: string (จาก deep link หรือ default "success")
• img_require: "true" | "false"
• ThaiIdData fields: cid, thFullname, enFullname, dob, gender, address, issueDate, expireDate, ... (ตาม toFlatMap())

รูปภาพเมื่อ img_require=true

• photo_mime: "image/jpeg"
• รูปเล็ก: photo_b64
• รูปใหญ่: photo_parts, photo_p0..photo_pN

3.2 GET

GET callback_url?query...

3.3 POST (multipart/form-data)

POST callback_url ด้วย multipart/form-data (สำเร็จเมื่อ HTTP 2xx)

---

4) Checklist

1. POST สำเร็จ: callback_type=post และ server ตอบ 2xx → แอปปิด popup
2. POST fail: server 500/timeout → แอปโชว์ error + ปุ่ม “ลองส่งอีกครั้ง”
3. GET flow: callback_type ไม่ใช่ post → เปิด URL ได้
4. รูปภาพ: img_require=false ไม่มี photo_* / img_require=true มี photo_b64 หรือ chunks