API Idempotency

GIỚI THIỆU

Một yêu cầu (request) được gọi là idempotent nếu kết quả thành công hay thất bại không phụ thuộc vào số lần request được gọi. Như vậy, API idempotency giúp cho request trở nên an toàn hơn, có thể lặp lại request mà không xảy ra vấn đề xử lý nhiều lần. Điều này hữu ích khi việc gọi API bị gián đoạn trong quá trình chuyển tiếp và bạn không nhận được phản hồi.

Ví dụ, khi request một quản phí gặp lỗi do kết nối mạng, bạn có thể thử lại yêu cầu đó với cùng một requestID, đảm bảo khoản phí đó chỉ được thanh toán duy nhất một lần.

Để thực thi idempotency trên lệnh gọi REST API POST, sử dụng requestId ở phần nội dung, gồm một requestId duy nhất mà hệ thống lưu trữ trong khoảng thời gian đó.

Mọi request POST của Open APIs đều chấp nhận requestId như là idempotency key.

requestId - được xem như Idempotence keys - được xem là chìa khóa tạo giá trị duy nhất. Ví dụ, bạn có thể gửi UUID như một requestId và đảm bảo được chỉ một kết quả được tạo ra bất kể số lần yêu cầu được gửi đến hệ thống.

VÍ DỤ

Một yêu cầu thanh toán chứa requestId trong phần nội dung bị quá thời gian, nhưng hệ thống vẫn capture khoản thanh toán.

Bạn có thể thử lại request ban đầu với cùng một requestId:

Nếu yêu cầu này thành công, PosApp sẽ trả về trạng thái mới nhất của yêu cầu, đó là mã trạng thái HTTP 200 Created và nội dung phản hồi JSON hiển thị chi tiết thanh toán được captured. Hệ thống sẽ không capture lại khoản thanh toán này vì việc capture đã thực hiện thành công ở lần gọi đầu tiên.

{
    "partner_code": "PAC1234567",
    "request_id": "123456735",
    "cardId": "locnguyen",
    "amount": 20000,
    "posapp_trans_id": "b042ef69-f067-4dc9-9143-9537bbcd695f",
    "order_id": "12345",
    "order_info": "Thanh toan don hang CH001",
    "message": "Nạp tiền thành công",
    "extra_data": null,
    "lang": "vi",
    "signature": "119d1d2535d65068a7913c9b0588f6b5d0bb89c3435227d541b86de0e744657b"
}

GIỚI THIỆU#

VÍ DỤ#

GIỚI THIỆU

VÍ DỤ