Tích hợp API và webhook: doanh nghiệp cần nghiệm thu những gì?
Nội dung chính
“Có API” không đồng nghĩa hai hệ thống đã làm việc với nhau. API thường cho phép yêu cầu đọc hoặc ghi dữ liệu; webhook thường báo một sự kiện. Phần tích hợp còn phải giải quyết đúng dữ liệu, đúng quyền và đúng hành động khi kết nối gặp lỗi.
Viết một hợp đồng dữ liệu
Với mỗi luồng, ghi nguồn, đích, trường bắt buộc, định dạng và hệ thống có quyền quyết định. Phân biệt thời gian tạo đơn với thời gian nhận thông báo, tiền đồng với số tiền tính theo đơn vị nhỏ, mã hàng với tên hiển thị.
| Nội dung cần chốt | Ví dụ câu hỏi |
|---|---|
| Định danh | Dùng mã nào để nhận ra cùng một đơn? |
| Chiều cập nhật | Nếu sửa ở cả hai nơi thì bên nào thắng? |
| Trạng thái | Đã nhận có nghĩa đã xử lý xong không? |
| Hạn mức | Mỗi phút được gửi bao nhiêu, xử lý khi bị giới hạn thế nào? |
| Phiên bản | Ai sửa kết nối khi nhà cung cấp đổi API? |
Xác thực không chỉ là giữ một khóa
Khóa cần nằm ở phía máy chủ, trong nơi lưu bí mật và đúng môi trường. Cấp quyền hẹp cho từng luồng, có quy trình thay khóa và thu hồi. Với webhook, xác minh chữ ký theo tài liệu của nhà cung cấp trên nội dung gốc; kiểm thời gian và cơ chế chống gửi lại khi hỗ trợ.
Không tin số tiền, quyền truy cập hay trạng thái trả từ trình duyệt. Dữ liệu đầu vào từ đối tác cũng phải được kiểm định dạng và giới hạn trước khi ghi hệ thống.
Chống xử lý trùng
Mạng có thể làm bên gửi không nhận được phản hồi dù bên nhận đã xử lý. Vì vậy, lần gửi lại cùng một sự kiện không được tạo thêm đơn, trừ kho hoặc hoàn tiền lần nữa. Kỹ thuật thường dùng mã sự kiện và khóa xử lý duy nhất được lưu bền vững.
Chỉ khóa bằng biến trong bộ nhớ không đủ khi có nhiều tiến trình hoặc máy chủ khởi động lại. Cần bảo đảm việc nhận diện và ghi nghiệp vụ không tạo khoảng trống gây lặp khi chạy đồng thời.
Thử lại và hàng đợi lỗi
Lỗi tạm thời có thể được thử lại với khoảng chờ tăng dần, giới hạn số lần và tuân thủ chỉ dẫn hạn mức. Lỗi dữ liệu hoặc quyền truy cập cần người xử lý, không gửi vô hạn. Việc chưa xong phải có trạng thái và mã theo dõi.
Với webhook xử lý lâu, có thể tiếp nhận bền vững rồi xử lý nền theo giao thức đã thống nhất. Phản hồi đã nhận không nên bị hiểu nhầm là đã hoàn tất nghiệp vụ.
Những tình huống cần nghiệm thu
- Dữ liệu hợp lệ đi đủ qua hai hệ thống và đối chiếu được.
- Một sự kiện được gửi hai lần hoặc đến không theo thứ tự.
- Đích ngừng hoạt động, hết hạn mức hoặc hết hạn khóa.
- Thiếu trường, sai tiền tệ, mã hàng chưa ánh xạ.
- Tiến trình dừng giữa lúc xử lý rồi chạy lại.
- Nhân viên xử lý lại một việc lỗi có lịch sử rõ ràng.
Giao người theo dõi hàng đợi và cách đối soát tổng số bản ghi, tổng tiền hoặc tồn kho. Log cần đủ để tra lỗi nhưng không ghi khóa, mật khẩu hay toàn bộ dữ liệu khách không cần thiết.
Khi bàn giao, nhận tài liệu ánh xạ, lịch chạy, cảnh báo và cách phát lại có kiểm soát. Nếu tích hợp là một phần của dự án số hóa quy trình lớn hơn, xem phạm vi chuyển đổi số và AI theo nghiệp vụ để chốt luồng nghiệp vụ trước khi viết kết nối.
Xem ứng dụng trong đồng bộ tồn kho, CRM và thanh toán.