การเชื่อมต่อระบบลงนามเอกสารอิเล็กทรอนิกส์

ภาพรวมการทำงาน

1. 1ระบบของท่าน ส่ง PDF มาที่ API พร้อม API key ได้รับ requestId และ signUrl กลับไป
2. 2ระบบของท่าน ส่งผู้ใช้ (redirect) ไปที่ signUrl
3. 3ผู้ใช้ เข้าสู่ระบบด้วย UDN3-SSO ตรวจรายละเอียดเอกสาร แล้วใส่ PIN เพื่อลงนาม หรือกดปฏิเสธ
4. 4บริการนี้ ส่งผู้ใช้กลับไปที่ returnUrl ของท่าน พร้อม requestId และผลลัพธ์
5. 5ระบบของท่าน เรียก API ตรวจสถานะ แล้วดาวน์โหลด PDF ที่ลงนามแล้วภายใน 60 นาที

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

ทุกคำขอต้องส่ง API key ใน header x-api-key ผู้ดูแลระบบจะออก key ให้แต่ละระบบผ่านหน้าผู้ดูแลระบบ key มีรูปแบบ udn3sk_… และจะแสดงเพียงครั้งเดียวตอนออก

x-api-key: udn3sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

การเปลี่ยน key โดยไม่ให้บริการสะดุด: ขอ key ใหม่จากผู้ดูแลระบบ (key เดิมยังใช้ได้ระหว่างนั้น) เปลี่ยนระบบของท่านไปใช้ key ใหม่ แล้วแจ้งให้เพิกถอน key เดิม

1. สร้างคำขอลงนาม

POST/api/v1/sign-requests

ส่งแบบ multipart/form-data โดยมีฟิลด์ดังนี้

curl -X POST "https://signing-service.udonthani3.go.th/api/v1/sign-requests" \
  -H "x-api-key: $SIGNING_API_KEY" \
  -F "file=@memo.pdf;type=application/pdf" \
  -F "returnUrl=https://eoffice.example.go.th/signing/callback" \
  -F "signerSub=<SSO sub ของผู้ลงนาม>" \
  -F "documentName=บันทึกข้อความ ขออนุมัติ.pdf" \
  -F "reason=อนุมัติตามเสนอ" \
  -F "state=doc-1234"

เมื่อสำเร็จจะได้ 201 Created

{
  "success": true,
  "requestId": "Q7v2kL9xR4mN8pT1wZ5yAa",
  "status": "PENDING",
  "signUrl": "https://signing-service.udonthani3.go.th/sign/Q7v2kL9xR4mN8pT1wZ5yAa",
  "documentSha256": "3a7bd3e2360a3d29…",
  "expiresAt": "2026-11-02T09:30:00.000Z"
}

documentSha256 คือค่าแฮชของไฟล์ต้นฉบับที่ส่งมา ใช้ยืนยันได้ว่าเอกสารที่ผู้ใช้ลงนามคือฉบับเดียวกับที่ท่านส่ง ส่วน expiresAt คือเวลาที่ผู้ใช้ต้องลงนามให้เสร็จ (30 นาทีหลังสร้างคำขอ)

2. ส่งผู้ใช้ไปลงนามและรับผลกลับ

Redirect ผู้ใช้ไปที่ signUrl ในหน้าต่างเดิม (ไม่ควรเปิดใน iframe เพราะบริการนี้ไม่อนุญาตให้ฝังหน้าลงนาม) เมื่อผู้ใช้ลงนามหรือปฏิเสธ บริการนี้จะส่งผู้ใช้กลับไปที่ returnUrl พร้อม query string ดังนี้

https://eoffice.example.go.th/signing/callback?requestId=Q7v2kL9xR4mN8pT1wZ5yAa&status=signed&state=doc-1234

หากผู้ใช้ไม่ดำเนินการจนหมดเวลา ผู้ใช้จะไม่ถูกส่งกลับ และสถานะจะเป็น EXPIRED ระบบของท่านควรตรวจสถานะคำขอที่ค้างอยู่เป็นระยะ

3. ตรวจสอบสถานะ

GET/api/v1/sign-requests/{requestId}

curl "https://signing-service.udonthani3.go.th/api/v1/sign-requests/Q7v2kL9xR4mN8pT1wZ5yAa" \
  -H "x-api-key: $SIGNING_API_KEY"

{
  "success": true,
  "requestId": "Q7v2kL9xR4mN8pT1wZ5yAa",
  "status": "SIGNED",
  "documentName": "บันทึกข้อความ ขออนุมัติ.pdf",
  "documentSha256": "3a7bd3e2360a3d29…",
  "signedBy": "<SSO sub ของผู้ลงนาม>",
  "certSerialNumber": "1f4c9e07a2b35d68c0e1f2a3b4c5d6e7f8091a2b",
  "timestampedAt": "2026-11-02T09:12:41.000Z",
  "signedPdfAvailable": true,
  "createdAt": "2026-11-02T09:00:00.000Z",
  "completedAt": "2026-11-02T09:12:41.512Z",
  "expiresAt": "2026-11-02T10:12:41.512Z"
}

ระบบของท่านเห็นได้เฉพาะคำขอที่ระบบของท่านสร้าง คำขอของระบบอื่นจะได้ 404

4. ดาวน์โหลด PDF ที่ลงนามแล้ว

GET/api/v1/sign-requests/{requestId}/pdf

ได้ไฟล์ application/pdf กลับมาโดยตรง ดาวน์โหลดได้ภายใน 60 นาทีหลังลงนามหลังจากนั้นบริการนี้จะลบไฟล์ทิ้ง (เก็บไว้เพียงค่าแฮช) และจะได้ 410 ระบบของท่านจึงต้องเก็บไฟล์ไว้เอง

curl -f -o signed.pdf "https://signing-service.udonthani3.go.th/api/v1/sign-requests/Q7v2kL9xR4mN8pT1wZ5yAa/pdf" \
  -H "x-api-key: $SIGNING_API_KEY"

สถานะของคำขอ

คำขอแต่ละรายการเปลี่ยนสถานะจาก PENDING ได้เพียงครั้งเดียว และไม่สามารถนำกลับมาใช้ซ้ำได้

ข้อผิดพลาด

เมื่อเกิดข้อผิดพลาด จะได้ JSON รูปแบบเดียวกันเสมอ

{
  "success": false,
  "error": "returnUrl origin is not registered for this client",
  "details": { }
}

ข้อจำกัด

• ไฟล์ PDF ขนาดไม่เกิน 20 MB ต่อคำขอ
• หนึ่งเอกสารลงนามได้หนึ่งคน PDF ที่มีลายเซ็นดิจิทัลอยู่แล้วจะถูกปฏิเสธ (ยังไม่รองรับการลงนามหลายคนในฉบับเดียว)
• ผู้ใช้มีเวลาลงนาม 30 นาทีหลังสร้างคำขอ และระบบของท่านมีเวลาดาวน์โหลด 60 นาทีหลังลงนาม
• ผู้ลงนามต้องมีชื่อภาษาอังกฤษในบัญชี UDN3-SSO เพราะชื่อนี้จะอยู่ในใบรับรอง (อีเมลไม่บังคับ)
• returnUrl ต้องอยู่ใน origin ที่ลงทะเบียนไว้เท่านั้น

รูปแบบลายเซ็น

• มาตรฐาน PAdES (ETSI.CAdES.detached) ระดับ B-T เมื่อได้รับการประทับเวลาจาก TSA หรือระดับ B-B เมื่อไม่มีการประทับเวลา (ดูได้จาก timestampedAt)
• กุญแจ RSA 3072 บิต และ SHA-256 ของผู้ลงนามแต่ละคน ออกใบรับรองโดย UDN3 CA ระบุชื่อภาษาอังกฤษ, SSO sub (ในช่อง serialNumber) และอีเมลของผู้ลงนามหากมี
• ฝัง chain ของใบรับรองไว้ในไฟล์ จึงตรวจสอบลายเซ็นใน Adobe Acrobat Reader หรือโปรแกรมตรวจสอบ PDF อื่นได้ เมื่อเครื่องนั้นเชื่อถือ Root CA ของ UDN3
• ห้ามแก้ไขไฟล์หลังลงนาม การแก้ไขใดๆ จะทำให้ลายเซ็นไม่ถูกต้อง

Checklist ก่อนใช้งานจริง

• ได้รับ API key จากผู้ดูแลระบบ และเก็บไว้ใน secret ของ server
• แจ้ง origin ของ returnUrl ทุกสภาพแวดล้อม (ทดสอบ / ใช้งานจริง) ให้ผู้ดูแลระบบลงทะเบียน
• ระบุ signerSub ของผู้ลงนามทุกคำขอ
• หน้า returnUrl เรียก API ตรวจสถานะ และตรวจ state ทุกครั้ง
• ดาวน์โหลดและเก็บ PDF ที่ลงนามแล้วภายใน 60 นาที
• จัดการกรณี REJECTED และ EXPIRED (เช่น ตรวจคำขอที่ค้างเป็นระยะ)