Cách thiết lập thông báo hoàn thành đơn hàng API

Sự kiện nào được coi là hoàn thành đơn hàng

Trước tiên, hãy xác định trạng thái nào trong API có nghĩa là đơn hàng thực sự hoàn thành. Ở các nhà cung cấp khác nhau, đó có thể là đơn đã thực hiện, đã giao, đã hủy, bị từ chối, đã hoàn trả hoặc hoàn thành một phần. Đừng chỉ gắn tự động hóa với từ «thành công»: đơn hàng có thể đi qua nhiều trạng thái trung gian rồi dừng lại do giới hạn, kiểm tra hoặc hủy.

Cần xử lý không chỉ kết quả tích cực. Nếu dịch vụ gửi thông báo về lỗi, hủy, hoàn trả hoặc hoàn thành một phần, cũng nên ghi nhận vào hệ thống nội bộ. Nếu không, trong bảng điều khiển, CRM hoặc bot, đơn hàng sẽ vẫn ở trạng thái chờ, dù việc thực hiện tiếp theo sẽ không xảy ra nữa.

Lập bảng ánh xạ trạng thái

Đừng truyền trạng thái API vào giao diện mà không xử lý. Tên gọi và logic của nhà cung cấp có thể thay đổi, và một trạng thái nội bộ đôi khi gộp nhiều trạng thái bên ngoài. Hãy lưu giá trị gốc riêng: nó sẽ hữu ích để phân tích lỗi và đối chiếu với tài liệu.

• pending, created, queued — đơn hàng mới hoặc đang chờ xử lý.
• processing, in_progress, running — đơn hàng đang được thực hiện.
• completed, delivered, success — đơn hàng đã hoàn thành.
• partial, partially_completed — đơn hàng hoàn thành một phần.
• cancelled, rejected, failed — đơn hàng đã hủy hoặc kết thúc với lỗi.
• refunded, returned — đơn hàng cần hoàn tiền hoặc điều chỉnh.
• Trạng thái không xác định — không tự động thay đổi thẻ đơn hàng và được chuyển để kiểm tra.

Các tên trên chỉ là ví dụ về sơ đồ. Bảng cuối cùng cần được xây dựng theo trạng thái của API cụ thể. Nhược điểm của ánh xạ thủ công là sau khi API cập nhật, cần duy trì nó: một trạng thái mới có thể lọt vào trình xử lý trước khi có quy tắc cho nó.

Chọn webhook, gọi API định kỳ hay cả hai

Webhook là yêu cầu từ dịch vụ đến URL của bạn khi trạng thái đơn hàng thay đổi. Gọi API định kỳ thì ngược lại: hệ thống của bạn sau mỗi khoảng thời gian sẽ yêu cầu thông tin về đơn hàng. Với thông báo hoàn thành, webhook thường tiện hơn vì cập nhật đến mà không cần liên tục gọi phương thức kiểm tra trạng thái.

• Webhook phù hợp để phản ứng nhanh: cập nhật thẻ đơn hàng, khởi chạy bước tiếp theo hoặc gửi tin nhắn cho người phụ trách.
• Gọi định kỳ phù hợp nếu nhà cung cấp không hỗ trợ thông báo callback hoặc máy chủ không nhận yêu cầu bên ngoài.
• Sơ đồ kết hợp dùng webhook làm kênh chính, còn gọi định kỳ để tìm các đơn hàng bị bỏ sót hoặc bị treo.

Nhược điểm của gọi định kỳ là độ trễ và tải thừa lên API. Nhược điểm của webhook là cần bảo vệ endpoint, tính đến trùng lặp và không dựa vào thứ tự gửi sự kiện.

Thiết lập endpoint để nhận sự kiện

Để nhận thông báo, cần một địa chỉ HTTPS công khai mà dịch vụ API có thể truy cập. Trong cài đặt tích hợp thường chỉ định URL trình xử lý, secret chữ ký và danh sách sự kiện: thay đổi trạng thái, hoàn thành, hủy, lỗi hoặc hoàn thành một phần.

Hãy tách riêng một tuyến chỉ dành cho sự kiện API. Như vậy dễ hơn để thiết lập ghi log, giới hạn truy cập, đặt giới hạn yêu cầu và không trộn lưu lượng dịch vụ với biểu mẫu của trang web. Đừng dùng địa chỉ môi trường thử nghiệm cho đơn hàng thực tế: sau khi cập nhật môi trường, nhà cung cấp sẽ tiếp tục gửi sự kiện đến URL đã lưu.

Trước khi chạy, hãy kiểm tra phương thức yêu cầu và định dạng body theo tài liệu. Thường nhất là POST với JSON, nhưng cũng có form-data, tham số query hoặc lược đồ tuần tự hóa riêng. Lỗi phân tích cần được ghi vào log, nếu không sẽ khó phân biệt payload sai với sự cố ứng dụng.

Lưu liên kết giữa đơn hàng và sự kiện

Khi tạo đơn hàng qua API, hãy lưu mã định danh mà nhà cung cấp trả về. Bên cạnh đó lưu số đơn hàng nội bộ, loại dịch vụ, trạng thái gốc, thời điểm thay đổi cuối cùng và phản hồi API gốc ở dạng an toàn. Hãy đối chiếu webhook đến theo ID của nhà cung cấp, không theo liên kết kênh, tên dịch vụ hay tên khách hàng.

Nếu API cho phép truyền mã định danh bên ngoài khi tạo, hãy thêm số đơn hàng của bạn vào trường như external_id hoặc client_reference. Điều này giúp tìm kiếm trong log và phân tích các tình huống tranh chấp dễ hơn. Nhưng đừng lấy số bên ngoài làm khóa duy nhất: một số nhà cung cấp không trả nó trong mọi thông báo.

Đừng tạo đơn hàng mới từ ID không xác định trong webhook. Sự kiện không xác định cần được lưu vào log và kiểm tra riêng. Tự động tạo bản ghi có thể dẫn đến dữ liệu sai hoặc xử lý yêu cầu giả mạo.

Dùng cấu trúc payload rõ ràng

Tên trường chính xác phụ thuộc vào API. Dưới đây không phải hợp đồng của một dịch vụ cụ thể, mà là ví dụ sự kiện JSON để tham khảo khi thiết kế trình xử lý nội bộ. Quan trọng là mã sự kiện, ID đơn hàng tại nhà cung cấp, trạng thái, thời điểm thay đổi và dữ liệu để chẩn đoán.

{

  "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

  }

}

Đừng dùng số lượng đơn vị đã hoàn thành làm dấu hiệu hoàn thành mà không có trạng thái. Đơn hàng có thể được hoàn thành một phần, còn con số trong payload có thể bị làm tròn, cập nhật chậm hoặc không được truyền. Nhược điểm của việc lưu toàn bộ body sự kiện là có thể chứa dữ liệu cá nhân hoặc trường nội bộ, nên các bản ghi như vậy cần được che và giới hạn thời hạn lưu.

Kiểm tra chữ ký theo body yêu cầu gốc

URL trình xử lý công khai có thể nhận yêu cầu không chỉ từ dịch vụ API. Nếu nhà cung cấp truyền chữ ký, secret hoặc token, hãy kiểm tra chúng trước khi thay đổi đơn hàng. Lược đồ phổ biến là HMAC-SHA256: nhà cung cấp tính chữ ký từ byte của body yêu cầu và secret chung, rồi truyền kết quả trong header HTTP.

Nguyên tắc tính như sau: lấy body yêu cầu gốc, ví dụ byte JSON không thay đổi, và secret tích hợp. Sau đó tính HMAC-SHA256. Nếu kết quả dạng hex khớp với giá trị header, body không bị thay đổi sau khi ký và yêu cầu có khả năng được gửi từ bên biết secret.

Ví dụ có điều kiện: HMAC_SHA256(secret, raw_body) = chữ ký từ header X-Signature. Tên header, thuật toán và định dạng kết quả chỉ nên lấy từ tài liệu API. Một số dịch vụ thêm dấu thời gian hoặc ID sự kiện vào chuỗi ký. Trong trường hợp này không thể chỉ kiểm tra body JSON.

Không thay đổi JSON trước khi kiểm tra chữ ký

Chữ ký được kiểm tra theo byte gốc của yêu cầu, không theo đối tượng JSON mà ứng dụng đã phân tích và dựng lại. Khi tuần tự hóa lại, thứ tự trường, khoảng trắng, ký tự thoát, xuống dòng hoặc mã hóa có thể thay đổi. Với con người, JSON vẫn như cũ, nhưng tập byte đã thay đổi và HMAC sẽ không khớp.

Để tránh điều này, trước tiên hãy lấy raw body dưới dạng bytes hoặc buffer, lưu vào bộ nhớ, tính chữ ký và chỉ sau khi kiểm tra thành công mới phân tích JSON. Đừng áp dụng trim, chuyển đổi mã hóa, sắp xếp khóa và định dạng cho body. Trong middleware của framework, hãy kiểm tra xem JSON có bị tự động phân tích trước khi truy cập body gốc không.

Nhược điểm của lược đồ này là trình xử lý trở nên phụ thuộc vào thứ tự middleware. Nếu cấu hình sai, ứng dụng sẽ chỉ thấy đối tượng đã biến đổi, và các thông báo hợp lệ sẽ bắt đầu bị từ chối.

Ví dụ trình xử lý có kiểm tra HMAC

Dưới đây là ví dụ có điều kiện bằng Python. Nó thể hiện thứ tự thao tác, không phải tích hợp sẵn sàng: header, thuật toán, định dạng chữ ký và trường payload cần được thay bằng giá trị từ tài liệu nhà cung cấp.

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)

Để so sánh, hãy dùng hàm không dừng ở ký tự không khớp đầu tiên. Điều này giảm rủi ro lộ dữ liệu về chữ ký qua thời gian phản hồi. Không truyền secret vào mã phía client, không thêm vào URL và không ghi toàn bộ vào log.

Làm cho việc xử lý sự kiện có tính idempotent

Nhà cung cấp có thể gửi cùng một sự kiện nhiều lần. Nguyên nhân thường gặp: máy chủ của bạn phản hồi lâu, kết nối bị ngắt sau khi lưu dữ liệu, endpoint tạm thời trả lỗi hoặc dịch vụ khởi chạy gửi lại theo quy tắc của họ. Gửi lại không có nghĩa là API đã tạo đơn hàng mới.

Idempotent nghĩa là cùng một sự kiện chỉ thay đổi kết quả một lần. Nếu không tính đến quy tắc này, bản trùng sẽ gửi lại tin nhắn cho khách hàng, tạo nhiều nhiệm vụ cho quản lý, cộng bồi thường hoặc khởi chạy lại thao tác.

Tốt nhất là dùng event_id từ payload. Hãy lưu nó trong bảng riêng hoặc log sự kiện đã xử lý với ràng buộc duy nhất. Nếu không có ID riêng, hãy tạo khóa từ các trường ổn định: ID đơn hàng nhà cung cấp, loại sự kiện, trạng thái và thời điểm thay đổi. Cách này kém hơn: khi dấu thời gian không chính xác, các sự kiện khác nhau có thể trông giống nhau.

Lưu sự kiện và trạng thái trong một thao tác

Việc kiểm tra «sự kiện đã được xử lý chưa» và ghi kết quả phải được thực hiện nguyên tử. Nếu không, hai yêu cầu giống nhau đến cùng lúc sẽ đều thấy chưa có bản ghi và khởi chạy hành động hai lần. Cách thực tế là chỉ mục duy nhất theo event_id và giao dịch cơ sở dữ liệu.

Phần tiếp theo có điều kiện của trình xử lý như sau:

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)

Nhược điểm của việc trả mã thành công cho đơn hàng không xác định là nhà cung cấp có thể không gửi lại. Vì vậy, sự kiện không xác định cần được giám sát riêng và phân tích nhanh. Nếu tài liệu API khuyến nghị mã phản hồi khác cho các trường hợp này, hãy làm theo.

Tính đến việc sự kiện đến sai thứ tự

Webhook không phải lúc nào cũng đến đúng theo thời gian thay đổi trạng thái. Có thể sự kiện hoàn thành đến trước, rồi sau đó là thông báo trễ về trạng thái «đang thực hiện». Nếu chỉ ghi giá trị nhận được cuối cùng, đơn hàng đã hoàn thành sẽ lại thành đang hoạt động.

Hãy đặt các chuyển đổi được phép. Ví dụ, trạng thái trung gian không thể ghi đè trạng thái cuối, và đơn hàng đã hủy không được chuyển sang hoàn thành mà không có kiểm tra riêng. Nếu API cho phép điều chỉnh trạng thái cuối, hãy lưu nguyên nhân, giá trị gốc và nguồn thay đổi.

Nếu payload chứa thời điểm thay đổi đơn hàng, hãy so sánh chính nó, không phải thời điểm nhận webhook. Khi API không truyền dấu thời gian như vậy, hãy dùng mức ưu tiên trạng thái và đối chiếu qua phương thức lấy đơn hàng. Nhược điểm của mức ưu tiên là chúng không thay thế trình tự thực tế, đặc biệt nếu nhà cung cấp cho phép hoàn trả từ trạng thái cuối.

Xác nhận gửi nhanh và đưa hành động vào hàng đợi

Đừng thực hiện thao tác lâu trước khi phản hồi nhà cung cấp. Kiểm tra chữ ký, tìm đơn hàng, ghi sự kiện và cập nhật trạng thái thường có thể hoàn tất nhanh. Gửi tin nhắn, đồng bộ với CRM, tạo báo cáo hoặc yêu cầu đến hệ thống bên thứ ba nên được chuyển vào hàng đợi nhiệm vụ.

Thứ tự làm việc như sau: kiểm tra chữ ký, lưu nguyên tử sự kiện và thay đổi trạng thái, trả phản hồi thành công, sau đó thực hiện các hành động thứ cấp. Nếu phản hồi trước khi lưu, dữ liệu sẽ mất khi có sự cố. Nếu phản hồi sau khi gửi thông báo lâu, nhà cung cấp có thể coi việc gửi không thành công và gửi bản trùng.

Nhược điểm của hàng đợi là xuất hiện thành phần riêng cần kiểm soát: lỗi nhiệm vụ, độ trễ và khởi chạy lại. Bù lại, sự cố trong thông báo cho quản lý không chặn việc nhận trạng thái đơn hàng.

Thiết lập thông báo cho nhóm và khách hàng

Sau khi trạng thái thay đổi, không cần thông báo cho mọi người giống nhau. Quản lý thường quan tâm đến hủy, lỗi, hoàn thành một phần và các đơn hàng lâu không thay đổi. Khách hàng thường chỉ cần kết quả rõ ràng: đơn hàng đã hoàn thành, đã hủy hoặc cần làm rõ.

• Đơn hàng hoàn thành — cập nhật trong tài khoản cá nhân hoặc tin nhắn ngắn cho khách hàng.
• Lỗi thực hiện — thông báo cho người phụ trách kèm lý do mà API đã truyền.
• Hoàn thành một phần — nhiệm vụ kiểm tra điều chỉnh, hoàn tiền hoặc hành động tiếp theo.
• Trạng thái không xác định — ghi vào log và thông báo cho chuyên viên kỹ thuật.
• ID đơn hàng không xác định — kiểm tra riêng liên kết giữa hệ thống của bạn và nhà cung cấp.

Đừng gửi tin nhắn ở mỗi chuyển đổi kỹ thuật. Dòng thông báo sẽ nhanh chóng thành nhiễu, còn vấn đề quan trọng sẽ bị bỏ qua. Thông báo nội bộ nên chứa số đơn hàng, dịch vụ, trạng thái hiện tại, ID bên ngoài và liên kết đến thẻ đơn hàng.

Ghi log và đối chiếu các đơn hàng chưa hoàn thành

Log cần thiết để hiểu dịch vụ có gửi sự kiện không, body nào đã đến, vì sao chữ ký không qua và việc xử lý dừng ở giai đoạn nào. Hãy lưu thời điểm nhận, ID sự kiện, ID đơn hàng, loại sự kiện, kết quả kiểm tra chữ ký, trạng thái nội bộ và mã phản hồi. Hãy che secret, token và dữ liệu cá nhân.

Theo dõi riêng lỗi gửi, chữ ký không hợp lệ, đơn hàng không xác định, trạng thái không được hỗ trợ, bản trùng và sự kiện không thể áp dụng do thứ tự trạng thái. Sự gia tăng các bản ghi như vậy có thể nghĩa là lược đồ API đã thay đổi, secret hết hạn, tuyến bị lỗi hoặc logic trình xử lý sai.

Định kỳ đối chiếu các đơn hàng ở trạng thái trung gian qua phương thức lấy dữ liệu API. Việc kiểm tra này không thay thế webhook, nhưng giúp phát hiện sự kiện bị bỏ sót, sự cố hàng đợi hoặc trường hợp trạng thái bên ngoài đã thay đổi mà không có thông báo chính xác.