Đồng bộ thời gian

Trả về timestamp hiện tại của server và cấu hình TOTP, để thiết bị có thể phát hiện độ lệch đồng hồ (clock drift). Vì một mã chỉ có hiệu lực trong 15 giây, một đồng hồ thiết bị lệch một phút sẽ khiến mọi lần xác minh thất bại.

Endpoint

POST /api/v1/saas-sotp/sync-time
Content-Type: application/json

{
  "partner_id": "{{partner_id}}",
  "partner_key": "{{partner_key}}",
  "token": "{{token}}",
  "app_id": "{{app_id}}",
  "client_timestamp": "1672204839",
  "period": 15,
  "otp": "123456",
  "previous_otp": "654321"
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
partner_id	string	Có	—	Partner ID.
partner_key	string	Có	—	Partner key.
token	string	Có	—	Token đăng ký được tạo bởi Đăng ký.
period	int	Có	—	Số giây một OTP còn hiệu lực.
app_id	string	Không	—	App ID, dùng để tracking.
client_timestamp	int	Không	—	Timestamp hiện tại của client.
otp	string	Không	—	SmartOTP hiện tại.
previous_otp	string	Không	—	OTP từ khung thời gian (time block) trước đó.

Việc cung cấp otp và previous_otp giúp server tính ra đồng hồ thiết bị đã lệch bao nhiêu, bằng cách xác định các mã đó thực sự thuộc khung thời gian nào.

Trả về: SyncTimeResponse

Ví dụ request

curl --location --request POST '<BASE_URL>/saas-sotp/sync-time' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "partner_id": "{{partner_id}}",
    "partner_key": "{{partner_key}}",
    "token": "{{token}}",
    "app_id": "{{app_id}}",
    "client_timestamp": "1672204839",
    "period": 15,
    "otp": "123456",
    "previous_otp": "654321"
  }'

Response

{
  "success": true,
  "code": 1,
  "message": "Success",
  "data": {
    "timestamp": "1666756646",
    "period": 15,
    "algorithm": "HmacSHA512",
    "length": 6,
    "type": "totp",
    "issuer": "SOTP"
  }
}

Trường	Kiểu	Mô tả
success	bool	Trạng thái của request.
code	int	status code — 1 khi thành công.
message	string	Thông báo trạng thái hoặc lỗi.
data.timestamp	int	Timestamp của server.
data.period	int	Số giây một OTP còn hiệu lực.
data.algorithm	string	Thuật toán HMAC — HmacSHA512.
data.length	int	Số chữ số của một mã OTP.
data.type	string	Loại soft OTP — totp.
data.issuer	string	Issuer đã tạo ra OTP.

Lỗi

Mã	Mô tả
103	Thông tin Partner không chính xác — Partner details are incorrect.
129	Token không hợp lệ — Invalid token.
190108	Tài khoản chưa hoạt động — Account not activated.
190301	Period không chính xác — Incorrect period.
190303	Client time không chính xác — Incorrect client time.

190303 là tín hiệu lệch đồng hồ: đồng hồ thiết bị đang cách quá xa so với server. Hãy áp dụng timestamp được trả về như một độ lệch (offset) thay vì yêu cầu người dùng tự chỉnh đồng hồ.

Bước tiếp theo

• Xác minh OTP — thử xác minh lại sau khi đồng hồ đã được đối chiếu
• Kích hoạt — nơi cùng cấu hình TOTP này được cấp lần đầu