วิธีตั้งค่าการแจ้งเตือนเมื่อคำสั่งซื้อ API เสร็จสมบูรณ์

เหตุการณ์ใดถือเป็นการเสร็จสมบูรณ์ของคำสั่งซื้อ

ก่อนอื่นให้กำหนดว่าสถานะใดใน API หมายถึงการเสร็จสมบูรณ์จริงของคำสั่งซื้อ ผู้ให้บริการแต่ละรายอาจใช้สถานะดำเนินการแล้ว, จัดส่งแล้ว, ยกเลิก, ถูกปฏิเสธ, คืนสินค้า หรือดำเนินการบางส่วน อย่าผูกระบบอัตโนมัติไว้กับคำว่า "สำเร็จ" เพียงอย่างเดียว เพราะคำสั่งซื้ออาจผ่านหลายสถานะกลาง แล้วหยุดลงเนื่องจากถึงขีดจำกัด การตรวจสอบ หรือการยกเลิก

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

สร้างตารางการจับคู่สถานะ

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

• pending, created, queued — คำสั่งซื้อใหม่หรือรอดำเนินการ
• processing, in_progress, running — คำสั่งซื้อกำลังดำเนินการ
• completed, delivered, success — คำสั่งซื้อดำเนินการเสร็จแล้ว
• partial, partially_completed — คำสั่งซื้อดำเนินการบางส่วน
• cancelled, rejected, failed — คำสั่งซื้อถูกยกเลิกหรือสิ้นสุดด้วยข้อผิดพลาด
• refunded, returned — คำสั่งซื้อต้องคืนเงินหรือปรับปรุง
• สถานะที่ไม่รู้จัก — จะไม่เปลี่ยนการ์ดโดยอัตโนมัติและจะถูกส่งไปตรวจสอบ

ชื่อข้างต้นเป็นเพียงตัวอย่างโครงสร้าง ตารางสุดท้ายต้องสร้างตามสถานะของ API แต่ละราย ข้อเสียของการจับคู่ด้วยมือคือต้องดูแลรักษาหลังจาก API อัปเดต เพราะสถานะใหม่อาจเข้าสู่ตัวจัดการก่อนที่จะมีกฎสำหรับสถานะนั้น

เลือกเว็บฮุค การเรียกถาม API หรือทั้งสองแบบ

เว็บฮุคคือคำขอจากบริการมาที่ URL ของคุณเมื่อสถานะคำสั่งซื้อเปลี่ยนแปลง การเรียกถาม API ทำงานในทางกลับกัน คือระบบของคุณจะสอบถามข้อมูลคำสั่งซื้อเป็นระยะ สำหรับการแจ้งเตือนเมื่อเสร็จสมบูรณ์มักใช้เว็บฮุคสะดวกกว่า เพราะการอัปเดตมาถึงโดยไม่ต้องเรียกถามเมธอดตรวจสอบสถานะตลอดเวลา

• เว็บฮุคเหมาะสำหรับการตอบสนองอย่างรวดเร็ว: อัปเดตการ์ด เริ่มขั้นตอนถัดไป หรือส่งข้อความถึงผู้รับผิดชอบ
• การเรียกถามเหมาะเมื่อผู้ให้บริการไม่รองรับการแจ้งเตือนแบบ callback หรือเซิร์ฟเวอร์ไม่รับคำขอจากภายนอก
• รูปแบบผสมใช้เว็บฮุคเป็นช่องทางหลัก และใช้การเรียกถามเพื่อค้นหาคำสั่งซื้อที่พลาดหรือค้างอยู่

ข้อเสียของการเรียกถามคือความล่าช้าและภาระเกินจำเป็นต่อ API ข้อเสียของเว็บฮุคคือต้องป้องกัน endpoint พิจารณารายการซ้ำ และไม่พึ่งพาลำดับการส่งเหตุการณ์

ตั้งค่า endpoint สำหรับรับเหตุการณ์

การแจ้งเตือนต้องใช้ที่อยู่ HTTPS สาธารณะที่เข้าถึงได้จากฝั่งบริการ API ในการตั้งค่าการเชื่อมต่อมักระบุ URL ของตัวจัดการ ความลับของลายเซ็น และรายการเหตุการณ์: การเปลี่ยนสถานะ การเสร็จสมบูรณ์ การยกเลิก ข้อผิดพลาด หรือการดำเนินการบางส่วน

แยกเส้นทางเฉพาะสำหรับเหตุการณ์ API เท่านั้น วิธีนี้ทำให้ตั้งค่าการบันทึก日志 จำกัดการเข้าถึง กำหนดขีดจำกัดคำขอ และไม่ปะปนทราฟฟิกบริการกับฟอร์มของเว็บไซต์ได้ง่ายขึ้น อย่าใช้ที่อยู่ของสภาพแวดล้อมทดสอบสำหรับคำสั่งซื้อจริง เพราะหลังจากอัปเดตสภาพแวดล้อม ผู้ให้บริการจะยังคงส่งเหตุการณ์ไปยัง URL ที่บันทึกไว้

ก่อนเปิดใช้งาน ให้ตรวจสอบเมธอดคำขอและรูปแบบ body ตามเอกสาร ส่วนใหญ่มักเป็น POST พร้อม JSON แต่ก็พบ form-data พารามิเตอร์ query หรือรูปแบบการทำให้เป็นอนุกรมเฉพาะได้ ข้อผิดพลาดในการแยกวิเคราะห์ต้องบันทึกลง日志 มิฉะนั้นจะแยกได้ยากว่า payload ผิดหรือแอปพลิเคชันขัดข้อง

เก็บความเชื่อมโยงระหว่างคำสั่งซื้อและเหตุการณ์

เมื่อสร้างคำสั่งซื้อผ่าน API ให้เก็บตัวระบุที่ผู้ให้บริการส่งกลับมา เก็บหมายเลขคำสั่งซื้อภายใน ประเภทบริการ สถานะดั้งเดิม เวลาที่เปลี่ยนแปลงล่าสุด และการตอบกลับ API ดั้งเดิมในรูปแบบที่ปลอดภัยไว้ข้าง ๆ จับคู่เว็บฮุคที่เข้ามาด้วย ID ของผู้ให้บริการ ไม่ใช่ด้วยลิงก์ไปยังช่อง ชื่อบริการ หรือชื่อลูกค้า

หาก API อนุญาตให้ส่งตัวระบุภายนอกตอนสร้าง ให้เพิ่มหมายเลขคำสั่งซื้อของคุณในฟิลด์เช่น external_id หรือ client_reference วิธีนี้ช่วยค้นหาใน日志และวิเคราะห์กรณีพิพาทได้ง่ายขึ้น แต่อย่าใช้หมายเลขภายนอกเป็นคีย์เดียว เพราะผู้ให้บริการบางรายไม่ส่งกลับมาในทุกการแจ้งเตือน

อย่าสร้างคำสั่งซื้อใหม่จาก ID ที่ไม่รู้จักในเว็บฮุค เหตุการณ์ที่ไม่รู้จักต้องบันทึกลง日志และตรวจสอบแยกต่างหาก การสร้างระเบียนอัตโนมัติอาจนำไปสู่ข้อมูลที่ผิดพลาดหรือการประมวลผลคำขอปลอม

ใช้โครงสร้าง payload ที่เข้าใจง่าย

ชื่อฟิลด์ที่แน่นอนขึ้นอยู่กับ API ด้านล่างไม่ใช่สัญญาของบริการใดบริการหนึ่ง แต่เป็นตัวอย่างเหตุการณ์ JSON ที่ใช้เป็นแนวทางในการออกแบบตัวจัดการภายใน สิ่งสำคัญคือตัวระบุเหตุการณ์ ID คำสั่งซื้อของผู้ให้บริการ สถานะ เวลาที่เปลี่ยนแปลง และข้อมูลสำหรับการวินิจฉัย

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

อย่าใช้จำนวนหน่วยที่ดำเนินการแล้วเป็นสัญญาณของการเสร็จสมบูรณ์โดยไม่มีสถานะ คำสั่งซื้ออาจดำเนินการบางส่วน และตัวเลขใน payload อาจถูกปัดเศษ อัปเดตด้วยความล่าช้า หรือไม่ถูกส่งมาเลย ข้อเสียของการเก็บ body ของเหตุการณ์ทั้งหมดคืออาจมีข้อมูลส่วนบุคคลหรือฟิลด์บริการปะปนอยู่ จึงต้องปิดบังระเบียนดังกล่าวและจำกัดระยะเวลาการเก็บ

ตรวจสอบลายเซ็นจาก body ของคำขอต้นฉบับ

URL ของตัวจัดการที่เปิดเผยอาจได้รับคำขอไม่ได้มาจากบริการ API เท่านั้น หากผู้ให้บริการส่งลายเซ็น ความลับ หรือโทเค็น ต้องตรวจสอบก่อนเปลี่ยนสถานะคำสั่งซื้อ รูปแบบที่พบบ่อยคือ HMAC-SHA256: ผู้ให้บริการคำนวณลายเซ็นจากไบต์ของ body คำขอและความลับร่วม แล้วส่งผลลัพธ์ใน HTTP header

หลักการคำนวณมีดังนี้: นำ body ของคำขอต้นฉบับ เช่น ไบต์ JSON โดยไม่เปลี่ยนแปลง และความลับของการเชื่อมต่อ จากนั้นคำนวณ HMAC-SHA256 หากผลลัพธ์ในรูปแบบเลขฐานสิบหกตรงกับค่าใน header แสดงว่า body ไม่ได้เปลี่ยนแปลงหลังการลงลายเซ็น และคำขออาจถูกส่งจากฝ่ายที่รู้ความลับ

ตัวอย่างเชิงเงื่อนไข: HMAC_SHA256(ความลับ, raw_body) = ลายเซ็นจาก header X-Signature ชื่อ header อัลกอริทึม และรูปแบบผลลัพธ์ต้องนำมาจากเอกสาร API เท่านั้น บริการบางรายเพิ่มการประทับเวลา或 ID เหตุการณ์ลงในสตริงสำหรับลายเซ็น ในกรณีนี้ไม่สามารถตรวจสอบเฉพาะ JSON body ได้

อย่าแก้ไข JSON ก่อนตรวจสอบลายเซ็น

ลายเซ็นตรวจสอบจากไบต์ต้นฉบับของคำขอ ไม่ใช่จากออบเจกต์ JSON ที่แอปพลิเคชันแยกวิเคราะห์และประกอบใหม่แล้ว การทำให้เป็นอนุกรมซ้ำอาจเปลี่ยนลำดับฟิลด์ ช่องว่าง การ escape อักขระ การขึ้นบรรทัดใหม่ หรือการเข้ารหัส สำหรับมนุษย์ JSON จะยังเหมือนเดิม แต่ชุดไบต์จะเปลี่ยนไป และ HMAC จะไม่ตรงกันอีก

เพื่อหลีกเลี่ยงปัญหานี้ ให้รับ raw body เป็น bytes หรือ buffer ก่อน เก็บไว้ในหน่วยความจำ คำนวณลายเซ็น และแยกวิเคราะห์ JSON หลังจากตรวจสอบสำเร็จแล้วเท่านั้น อย่าใช้ trim การแปลงการเข้ารหัส การเรียงลำดับคีย์ และการจัดรูปแบบกับ body ใน middleware ของเฟรมเวิร์ก ให้ตรวจสอบว่า JSON ถูกแยกวิเคราะห์อัตโนมัติก่อนเข้าถึง body ต้นฉบับหรือไม่

ข้อเสียของรูปแบบนี้คือตัวจัดการจะขึ้นอยู่กับลำดับของ middleware หากตั้งค่าไม่ถูกต้อง แอปพลิเคชันจะเห็นเพียงออบเจกต์ที่ถูกแปลงแล้ว และการแจ้งเตือนที่ถูกต้องจะเริ่มถูกปฏิเสธ

ตัวอย่างตัวจัดการพร้อมการตรวจสอบ HMAC

ด้านล่างเป็นตัวอย่างเชิงเงื่อนไขใน Python แสดงลำดับการทำงาน ไม่ใช่การเชื่อมต่อที่พร้อมใช้: header อัลกอริทึม รูปแบบลายเซ็น และฟิลด์ payload ต้องเปลี่ยนเป็นค่าจากเอกสารของผู้ให้บริการ

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

สำหรับการเปรียบเทียบ ให้ใช้ฟังก์ชันที่ไม่หยุดทำงานเมื่ออักขระตัวแรกไม่ตรงกัน วิธีนี้ลดความเสี่ยงของการรั่วไหลข้อมูลเกี่ยวกับลายเซ็นผ่านเวลาตอบสนอง อย่าส่งความลับไปยังโค้ดฝั่งไคลเอนต์ อย่าเพิ่มใน URL และอย่าบันทึกทั้งหมดลง日志

ทำให้การประมวลผลเหตุการณ์เป็นแบบ idempotent

ผู้ให้บริการอาจส่งเหตุการณ์เดียวกันหลายครั้ง สาเหตุเป็นเรื่องปกติ: เซิร์ฟเวอร์ของคุณตอบสนองช้า การเชื่อมต่อขาดหลังบันทึกข้อมูล endpoint ส่งข้อผิดพลาดชั่วคราว หรือบริการเริ่มการส่งซ้ำตามกฎของตน การส่งซ้ำไม่ได้หมายความว่า API สร้างคำสั่งซื้อใหม่

Idempotency หมายความว่าเหตุการณ์เดียวกันจะเปลี่ยนผลลัพธ์เพียงครั้งเดียว หากไม่คำนึงถึงกฎนี้ รายการซ้ำจะส่งข้อความถึงลูกค้าอีกครั้ง สร้างงานหลายรายการให้ผู้จัดการ ให้ค่าชดเชย หรือเริ่มการดำเนินการซ้ำ

วิธีที่ดีที่สุดคือใช้ event_id จาก payload เก็บไว้ในตารางแยกหรือ日志ของเหตุการณ์ที่ประมวลผลแล้วพร้อมข้อจำกัด unique หากไม่มี ID แยก ให้สร้างคีย์จากฟิลด์ที่เสถียร: ID คำสั่งซื้อของผู้ให้บริการ ประเภทเหตุการณ์ สถานะ และเวลาที่เปลี่ยนแปลง วิธีนี้แย่กว่า เพราะหากการประทับเวลาไม่แม่นยำ เหตุการณ์ต่างกันอาจดูเหมือนกัน

บันทึกเหตุการณ์และสถานะในการดำเนินการเดียว

การตรวจสอบว่า "ประมวลผลเหตุการณ์แล้วหรือไม่" และการบันทึกผลลัพธ์ต้องทำแบบ atomic มิฉะนั้นคำขอเดียวกันสองรายการที่มาพร้อมกันจะเห็นว่าไม่มีระเบียนทั้งคู่และเริ่มการดำเนินการสองครั้ง วิธีที่ใช้ได้จริงคือ unique index บน event_id และทรานแซกชันฐานข้อมูล

ส่วนต่อเนื่องเชิงเงื่อนไขของตัวจัดการมีดังนี้:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

ข้อเสียของการตอบกลับด้วยรหัสสำเร็จสำหรับคำสั่งซื้อที่ไม่รู้จักคือผู้ให้บริการอาจไม่ส่งซ้ำ ดังนั้นเหตุการณ์ที่ไม่รู้จักต้องติดตามแยกและวิเคราะห์อย่างรวดเร็ว หากเอกสาร API แนะนำรหัสตอบกลับอื่นสำหรับกรณีเหล่านี้ ให้ปฏิบัติตามนั้น

คำนึงถึงการละเมิดลำดับเหตุการณ์

เว็บฮุคไม่ได้มาตามเวลาที่เปลี่ยนแปลงสถานะเสมอไป อาจมีเหตุการณ์เกี่ยวกับการเสร็จสมบูรณ์มาก่อน แล้วตามด้วยการแจ้งเตือนสถานะ "กำลังดำเนินการ" ที่ล่าช้า หากเพียงบันทึกค่าล่าสุดที่ได้รับ คำสั่งซื้อที่เสร็จแล้วจะกลับมาเป็นสถานะใช้งานอีกครั้ง

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

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

ยืนยันการส่งอย่างรวดเร็วและย้ายการดำเนินการไปยังคิว

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

ลำดับการทำงานที่ใช้ได้คือ: ตรวจสอบลายเซ็น บันทึกเหตุการณ์และการเปลี่ยนสถานะแบบ atomic ตอบกลับสำเร็จ แล้วจึงดำเนินการขั้นที่สอง หากตอบกลับก่อนบันทึก ข้อมูลจะสูญหายเมื่อเกิดข้อขัดข้อง หากตอบกลับหลังการส่งการแจ้งเตือนที่ใช้เวลานาน ผู้ให้บริการอาจถือว่าการส่งไม่สำเร็จและส่งรายการซ้ำ

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

ตั้งค่าการแจ้งเตือนสำหรับทีมและลูกค้า

หลังการเปลี่ยนสถานะ ไม่จำเป็นต้องแจ้งทุกฝ่ายเหมือนกัน ผู้จัดการมักสนใจการยกเลิก ข้อผิดพลาด การดำเนินการบางส่วน และคำสั่งซื้อที่ไม่เปลี่ยนแปลงเป็นเวลานาน ลูกค้ามักต้องการเพียงผลลัพธ์ที่เข้าใจง่าย: คำสั่งซื้อเสร็จสมบูรณ์ ถูกยกเลิก หรือต้องการการยืนยัน

• คำสั่งซื้อที่เสร็จสมบูรณ์ — อัปเดตในพื้นที่ส่วนตัวหรือข้อความสั้นถึงลูกค้า
• ข้อผิดพลาดในการดำเนินการ — แจ้งผู้รับผิดชอบพร้อมสาเหตุที่ API ส่งมา
• การดำเนินการบางส่วน — งานสำหรับตรวจสอบการปรับปรุง การคืนเงิน หรือการดำเนินการถัดไป
• สถานะที่ไม่รู้จัก — บันทึกลง日志และแจ้งผู้เชี่ยวชาญด้านเทคนิค
• ID คำสั่งซื้อที่ไม่รู้จัก — ตรวจสอบความเชื่อมโยงระหว่างระบบของคุณกับผู้ให้บริการแยกต่างหาก

อย่าส่งข้อความทุกครั้งที่มีการเปลี่ยนสถานะทางเทคนิค ฟีดจะกลายเป็นเสียงรบกวนอย่างรวดเร็ว และปัญหาสำคัญจะไม่ถูกสังเกต การแจ้งเตือนภายในควรมีหมายเลขคำสั่งซื้อ บริการ สถานะปัจจุบัน ID ภายนอก และลิงก์ไปยังการ์ด

บันทึก日志และตรวจสอบคำสั่งซื้อที่ยังไม่เสร็จสมบูรณ์

日志จำเป็นเพื่อให้เข้าใจว่าบริการส่งเหตุการณ์มาหรือไม่ body ใดเข้ามา ทำไมลายเซ็นไม่ผ่าน และการประมวลผลหยุดที่ขั้นตอนใด บันทึกเวลาที่ได้รับ ID เหตุการณ์ ID คำสั่งซื้อ ประเภทเหตุการณ์ ผลการตรวจสอบลายเซ็น สถานะภายใน และรหัสตอบกลับ ปิดบังความลับ โทเค็น และข้อมูลส่วนบุคคล

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

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