Idempotency – chống tạo trùng

Mạng giữa máy chủ của bạn và Hensa có thể đứt sau khi Hensa đã tạo yêu cầu thanh toán nhưng trước khi bạn nhận được phản hồi. Gửi lại mà không có idempotency = hai mã QR cho một đơn.

Cách dùng

Mọi request tạo mới hoặc chạm tới tiền (POST) bắt buộc có header:

Idempotency-Key: 6f1c2a9e-0d3b-4c5e-9a7f-2b8e4d6c1a03

• Sinh một khóa cho một ý định (vd. “tạo mã cho đơn DH-1024”) – thường là UUID.
• Thử lại thì dùng lại đúng khóa đó. Đừng sinh khóa mới mỗi lần thử – như vậy là mất tác dụng.
• Hensa nhớ khóa 24 giờ.

Hensa xử lý thế nào

Tình huống	Kết quả
Khóa mới	Xử lý bình thường, lưu kết quả
Cùng khóa, cùng nội dung, trong 24 giờ	Trả lại đúng kết quả lần đầu (kể cả mã HTTP) – không tạo bản ghi mới
Cùng khóa, khác nội dung	409 idempotency_conflict – bạn đang dùng lại khóa cho một việc khác
Lần đầu đang xử lý dở	409 idempotency_conflict – chờ một chút rồi thử lại

Thử lại thế nào cho đúng

Thử lại với backoff tăng dần (vd. 1 s, 2 s, 4 s… tối đa 5 lần) khi gặp lỗi mạng, 429 hoặc 5xx. Không thử lại với 4xx khác (400, 401, 422) – sửa request trước.