Tài liệu API

Idempotency

Lỗi mạng không cho bạn biết máy chủ đã nhận thao tác ghi hay chưa. Với Idempotency-Key, bạn gửi lại mà không tạo ra chuyến thứ hai.

Cách hoạt động

  • Thêm Idempotency-Key: <giá trị duy nhất> vào thao tác ghi. Một UUID ngẫu nhiên cho mỗi thao tác nghiệp vụ là khóa tốt. Mọi thao tác ghi trong tham chiếu API đều nhận header này.
  • Cùng khóa với cùng nội dung trong 24 giờ trả lại câu trả lời đã lưu: cùng trạng thái, cùng nội dung. Không có gì chạy hai lần.
  • Cùng khóa với nội dung khác là 422 IDEMPOTENCY_KEY_REUSED. Hãy dùng khóa mới cho yêu cầu mới.
  • Cùng khóa khi yêu cầu đầu còn đang chạy là 409 IDEMPOTENCY_IN_PROGRESS kèm Retry-After: 2. Chờ rồi gửi lại đúng yêu cầu đó.
  • Yêu cầu bị lỗi không được lưu: gửi lại với cùng khóa và nó chạy lại.
  • Khóa được tách theo tenant, người gọi, ứng dụng, phương thức và đường dẫn. Hai ứng dụng, hay hai thao tác khác nhau, không bao giờ dùng chung khóa.
  • Không có header thì máy chủ tự đặt một khóa, nên việc gửi lại không được loại trùng. Khóa đang dùng được trả về trong header phản hồi Idempotency-Key.
curl
curl -sS https://api.stracker.vn/v1/trips \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b6a2c0e-5c53-4b60-9b3e-2d1f6a0c9d11" \
  -d '{"routeId": 4, "date": "2026-11-20"}'

Khóa bí mật không bao giờ được phát lại

Các câu trả lời hiện khóa bí mật một lần (tạo subscription webhook, đổi khóa của nó) được lưu không kèm khóa. Phát lại trả cùng subscription nhưng không có secret. Nếu bạn mất phản hồi đầu tiên, hãy đổi khóa bí mật và giữ khóa mới.

Khi nào gửi lại

  • Gửi lại với cùng khóa: lỗi mạng hoặc hết thời gian chờ, 5xx, 429 (sau Retry-After), 409 IDEMPOTENCY_IN_PROGRESS.
  • Đừng gửi lại một 4xx nói về chính yêu cầu (400, 403, 404, 409 do xung đột): sửa yêu cầu và dùng khóa mới.
  • Thao tác đọc (GET) lặp lại an toàn và không cần khóa.