Bảo mật

Cơ chế xác thực

Mọi request tới API Baokim đều yêu cầu xác thực danh tính client trước khi xử lý. Baokim sử dụng OAuth2 với JWT Bearer Token:

1. Merchant gọi API /b2b/auth-service/api/oauth/get-token với merchant_code, client_id, client_secret.
2. Baokim trả về access_token (JWT) có thời hạn (expired_at).
3. Merchant đính kèm token vào header mỗi request: Authorization: Bearer <access_token>.

Nếu token hết hạn hoặc không hợp lệ, Baokim trả về lỗi xác thực và request bị từ chối.

Ký yêu cầu

Ngoài xác thực token, Baokim yêu cầu chữ ký số trên toàn bộ request body để đảm bảo dữ liệu không bị chỉnh sửa trong quá trình truyền nhận.

Quy trình ký:

1. Lấy dữ liệu cần ký:
   • Với POST: lấy toàn bộ raw JSON string của request body.
   • Với GET: lấy query string đã sort theo alphabet (không có request body).
2. Ký bằng thuật toán SHA256withRSA (hoặc SHA1withRSA với VA direct) sử dụng private key của Merchant.
3. Base64 encode chuỗi chữ ký.
4. Đặt vào header: Signature: <chuỗi đã base64 encode>

Baokim dùng public key của Merchant (đã trao đổi khi tích hợp) để verify chữ ký. Nếu chữ ký không hợp lệ, request sẽ bị từ chối với mã lỗi xác thực chữ ký.

Chiều ngược lại, Baokim cũng ký vào response và webhook gửi về Merchant — Merchant nên verify chữ ký Baokim để đảm bảo dữ liệu nhận được là toàn vẹn.

Idempotency

Trong môi trường mạng không ổn định, một request có thể được gửi nhiều lần. Để tránh tạo trùng giao dịch, Baokim sử dụng cơ chế Idempotency thông qua trường request_id:

• Mỗi request phải có request_id duy nhất (do Merchant tự sinh).
• Nếu Baokim nhận được hai request có cùng request_id, Baokim sẽ chỉ xử lý lần đầu và trả về kết quả cũ cho các lần sau — không tạo thêm giao dịch mới.
• Định dạng đề xuất: {merchant_code}_{YYYYMMDDHHIISS}_{unique_id}.

⚠️ Quan trọng: Với API tạo đơn / tạo giao dịch, request_id bắt buộc phải là duy nhất cho mỗi lần tạo mới. Không được tái sử dụng request_id của giao dịch cũ khi muốn tạo giao dịch mới.