Contracts & Events

Service ของคุณจะถูกเขียนใหม่ 2 ครั้งใน 5 ปี แต่ API จะยังอยู่ที่เดิม Contract คือคำสัญญาที่ทีมอื่นเอาไป build ต่อ — และมันอยู่นานกว่า implementation เสมอ เพราะฉะนั้นออกแบบมันก่อนออกแบบข้างใน

Payment API contract แบบมีคำอธิบาย#

POST /v1/transfers
Idempotency-Key: 9f2c1e4a-7b3d-4c8e-9f1a-2b3c4d5e6f70
Authorization: Bearer <token>
Content-Type: application/json

{
  "source_account_id": "acc_123",
  "destination": { "type": "promptpay", "proxy_id": "08XXXXXXXX" },
  "amount": { "currency": "THB", "minor_units": 25000 },
  "reference": "invoice-8891",
  "client_timestamp": "2026-08-07T12:00:03Z"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/transfers/trf_01J9XYZ

{
  "transfer_id": "trf_01J9XYZ",
  "status": "PENDING",
  "created_at": "2026-08-07T12:00:03.418Z",
  "_links": { "self": "/v1/transfers/trf_01J9XYZ" }
}

ในบล็อกเล็กๆ นั้นมีการตัดสินใจซ่อนอยู่ 7 เรื่อง แต่ละเรื่องคือบทเรียนจาก incident จริงที่ไหนสักแห่ง

1. เงินเป็น integer หน่วยย่อย ห้ามเป็น float#

25000 คือ 25,000 สตางค์ = 250.00 บาท ไม่ใช่ 250.00

ในเลขทศนิยมฐานสอง:  0.1 + 0.2 = 0.30000000000000004
สะสม 1 ล้านรายการ  →  ผลต่างที่ reconciliation จะเจอในวันที่แย่ที่สุด

และ currency ต้องเดินทางไปพร้อมจำนวนเงินเสมอ — field amount: 25000 ที่ลอยเดี่ยวๆ คือ bug ที่รอวันโผล่ตอนเปิดสกุลเงินที่ 2

2. Idempotency key เป็น required ไม่ใช่ optional#

Mobile network ทำ response หาย client จะ retry ถ้าไม่มี key คุณแยกไม่ได้ว่านั่นคือ retry หรือการจ่ายครั้งที่ 2

System map

กฎที่ต้องเขียนใน contract ให้ชัด:

• key เดิม + body เดิม → คืน ผลลัพธ์เดิม พร้อม status code เดิม
• key เดิม + body ต่าง → 409 Conflict (นี่คือ bug ของ client)
• key มีอายุเท่าไหร่ (ปกติ 24–72 ชั่วโมง) และหลังหมดอายุจะเกิดอะไร

การ implement เก็บไว้ที่บทที่ 16

3. Status เป็น PENDING ไม่ใช่ SUCCESS#

ถ้าเงินออกจากระบบของคุณไปยัง rail ที่คุณไม่ได้ควบคุม คุณสัญญาความสำเร็จแบบ synchronous ไม่ได้ การโกหกใน contract บังคับให้ consumer ทุกรายต้องเขียน workaround

4. Path มี version (/v1/)#

คุณจะต้องมี v2 ตัดสินใจเรื่องกลยุทธ์ versioning ตั้งแต่วันแรก การมาใส่ทีหลังเจ็บกว่ามาก

5. มี URL ให้ poll และ (บน production) มี webhook#

ห้ามให้ client เดา ว่าจะรู้ผลลัพธ์ได้อย่างไร ในสัญญาต้องระบุทั้ง 2ทาง พร้อมกฎของ webhook: signature ตรวจยังไง, retry กี่ครั้ง, ส่งซ้ำได้ไหม (ได้ — consumer ต้อง dedupe)

6. รับ timestamp จาก client แต่ไม่เชื่อ#

มีประโยชน์สำหรับ debug clock skew และช่วยตรวจ duplicate แต่ห้ามใช้จัดลำดับหรือใช้ตัดสิน authorization — นาฬิกาของ client ตั้งเองได้

7. Destination เป็น tagged union ไม่ใช่ column optional เรียงกัน#

{ "destination": { "type": "promptpay", "proxy_id": "08XXXXXXXX" } }

ดีกว่า

{ "promptpay_id": null, "bank_account": "123-4-56789", "bank_code": "014", "wallet_id": null }

เพราะเพิ่ม rail ใหม่ได้โดยไม่ทำให้ client เก่าพัง และ validation เขียนได้ต่อ type

Error semantics — ส่วนที่คนข้ามกันหมด#

คำถามที่ error response ต้องตอบให้ client ได้มีข้อเดียว: retry ได้ไหม

System map

Error body ที่ใช้งานได้#

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "ยอดเงินคงเหลือไม่เพียงพอ",
    "trace_id": "01J9XYZABCDEF",
    "details": { "available_minor_units": 12000, "required_minor_units": 25000 }
  }
}

• code เป็น enum ที่คงที่ — client เขียน logic กับมันได้ ห้ามเปลี่ยนคำ
• message เป็นข้อความสำหรับคน อาจเปลี่ยนได้ตามภาษา — client ห้าม parse
• trace_id ทำให้ support ไล่ log ต่อได้ใน 1 นาที ไม่ใช่ 1 ชั่วโมง
• details ใส่เฉพาะที่ client ต้องใช้ตัดสินใจ และต้องคิดว่ามันรั่วอะไรไหม

Pagination และ list endpoint#

สำหรับ transaction history ให้ใช้ cursor เสมอ และ cursor ต้องเป็น opaque string (encode created_at + id เข้าด้วยกัน) ไม่ใช่ตัวเลขที่ client เดาต่อได้

GET /v1/accounts/acc_123/transfers?limit=20&after=eyJ0IjoiMjAyNi0wOC0wN1QxMjowMDowM1oiLCJpZCI6InRyZl8wMUo5WFlaIn0

{
  "data": [ { "transfer_id": "trf_01J9XYZ", "amount": { "currency": "THB", "minor_units": 25000 } } ],
  "next_cursor": "eyJ0IjoiMjAyNi0wOC0wN1QxMTo1OTo0MVoiLCJpZCI6InRyZl8wMUo5V1FSIn0",
  "has_more": true
}

ถ้า interface เป็น asynchronous ก็ต้องออกแบบ event ด้วย#

{
  "event_id": "evt_01J9ABC",
  "event_type": "TransferSettled",
  "occurred_at": "2026-08-07T12:00:07.412Z",
  "version": 1,
  "transfer_id": "trf_01J9XYZ",
  "account_id": "acc_123",
  "amount": { "currency": "THB", "minor_units": 25000 },
  "trace_id": "01J9XYZABCDEF"
}

Metadata ของ topic ที่ต้องตัดสินใจไปพร้อมกัน:

topic: payments.transfer.v1     # domain.entity.version
key:   transfer_id              # การรับประกันลำดับเป็นแบบต่อ key เท่านั้น

4 กฎที่ต้องทำ:

1. ตั้งชื่อ event เป็นอดีตกาล — TransferSettled ไม่ใช่ SettleTransfer event คือ ข้อเท็จจริงที่เกิดขึ้นแล้ว, command คือ คำสั่งให้ทำ การผสม 2 อย่างนี้คือจุดเริ่มที่ระบบ event-driven กลายเป็นสปาเกตตีกระจาย
2. ต้องมี event_id เพราะ delivery guarantee ปกติคือ at-least-once consumer ต้อง dedupe ได้
3. อย่าใส่ข้อมูลส่วนบุคคลที่ไม่จำเป็น — event จะถูก copy ไป 5 ระบบกับ 3 data lake ภายใต้ PDPA คำขอลบข้อมูลต้องไปถึงทุกที่ ให้ publish identifier แล้วให้ consumer ไปดึงรายละเอียดผ่าน API ที่มี access control
4. ใส่ version ที่ topic หรือที่ payload และตัดสินใจกฎ compatibility ไว้ — ปกติคือ consumer ต้องทน field ที่ไม่รู้จัก และ producer ห้ามลบหรือเปลี่ยนความหมายของ field

REST หรือ gRPC หรือ event#

กฎที่ใช้ได้: ขอบนอก (partner, mobile) ใช้ REST; ภายในใช้ gRPC ถ้า latency สำคัญ; การแจ้งข้อเท็จจริงใช้ event — และห้ามใช้ event เป็น request/response แบบอ้อมๆ

Checklist ก่อนปิด contract#

• เงินเป็น integer หน่วยย่อย และมี currency ติดไปทุกที่
• Idempotency key required พร้อมกฎ key ซ้ำ + อายุ key
• Status ตรงกับความจริง (PENDING เมื่อยังไม่รู้ผล)
• ตาราง error ครบ พร้อมคอลัมน์ "retry ปลอดภัยไหม"
• 429 ส่ง Retry-After และ 503 บอกชัดว่าไม่มีอะไรเกิดขึ้น
• Error body มี code แบบ enum + trace_id
• 403 ไม่รั่วว่า resource มีอยู่จริงไหม
• List endpoint ใช้ cursor แบบ opaque และมีเพดาน limit
• Event เป็นอดีตกาล มี event_id และไม่มี PII เกินจำเป็น
• กลยุทธ์ versioning ตัดสินใจแล้วและเขียนไว้
• มีการยืนยันกับ consumer จริง อย่างน้อย 1 ราย ก่อนประกาศว่า contract นิ่ง