API Xác minh Khách hàng (v1)

2. Xác thực Header

Yêu cầu truyền khóa API của đối tác qua Header x-api-key cùng định dạng JSON:

curl -X POST "https://rentid.vn/api/v1/verifications" \
  -H "x-api-key: YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "full_name": "Nguyễn Văn A",
    "phone": "0912345678",
    "cccd": "001099123456",
    "emergency_phone": "0988776655",
    "emergency_relation": "Người thân"
  }'

3. Tham số Yêu cầu (Request Body)

Đối tác có thể gửi linh hoạt thông tin trong một lần hoặc theo từng đợt. Bắt buộc phải có ít nhất 1 trong 4 tiêu chí định danh của khách hàng:

Tham số	Kiểu	Bắt buộc	Mô tả & Ràng buộc định dạng
phone	string	Tùy chọn*	Số điện thoại chính chủ (10 số chuẩn VN, đầu số 03, 05, 07, 08, 09).
cccd	string	Tùy chọn*	Số Căn cước công dân hoặc CMND (9–20 ký tự).
passport	string	Tùy chọn*	Số Hộ chiếu (6–20 ký tự) cho khách nước ngoài hoặc công dân.
license	string	Tùy chọn*	Số Giấy phép lái xe (GPLX 6–20 ký tự).
email	string	Tùy chọn	Địa chỉ Email hợp lệ của khách hàng.
full_name	string	Tùy chọn	Họ và tên khách thuê xe (2–100 ký tự).
emergency_phone	string	Tùy chọn	SĐT liên hệ khẩn cấp / người thân. (*) Không được trùng với số điện thoại chính.
emergency_relation	string	Tùy chọn	Mối quan hệ với người liên hệ khẩn cấp (ví dụ: "Bố", "Mẹ", "Vợ/Chồng", "Bạn bè").

info Quy tắc kiểm tra định danh:

Hệ thống sẽ từ chối với mã lỗi 422 Unprocessable Entity nếu không có bất kỳ trường nào trong số 4 trường định danh (phone, cccd, passport, license).

4. Bảng Lịch sử & Đồng Bộ RentID Core

Mỗi tiêu chí xác minh được cộng trực tiếp vào điểm tín nhiệm tổng hợp của người dùng (Thang điểm từ 0 đến 1000, mặc định 500 điểm cho hồ sơ mới):

Tiêu chí xác minh	Điểm cộng	Cơ chế xử lý
Xác thực CCCD / Hộ chiếu	+50 điểm	Cộng khi có số CCCD hoặc số Hộ chiếu hợp lệ
Xác thực Giấy phép lái xe (GPLX)	+50 điểm	Cộng khi cung cấp số bằng lái hợp lệ
Xác thực Số điện thoại chính	+20 điểm	Cộng khi cung cấp SĐT chính chủ
Bổ sung SĐT liên hệ khẩn cấp	+20 điểm	Cộng lần đầu khi lưu người thân khẩn cấp
Xác thực Địa chỉ Email	+20 điểm	Cộng khi cung cấp email hợp lệ

5. Cấu trúc Phản hồi (Response Format)

Hệ thống trả về phản hồi chuẩn hóa với cấu trúc tinh gọn gồm điểm tổng hợp và phân hạng rủi ro:

Cấu trúc phản hồi thành công (200 OK):

{
  "status": 200,
  "success": true,
  "message": "Xác minh thông tin thành công.",
  "data": {
    "score": 590,
    "status": "standard",
    "status_label": "Tiêu chuẩn"
  }
}

play_circle 6. Thử nghiệm Trực tiếp (Sandbox)

POST /api/v1/verifications

Partner API Key *

Họ và tên khách hàng

Số điện thoại chính

Số CCCD / CMND

Số Hộ chiếu (Passport)

Số Giấy phép lái xe (GPLX)

Địa chỉ Email

SĐT liên hệ khẩn cấp

Mối quan hệ khẩn cấp

Kết quả phản hồi (Response)

7. Mã Trạng Thái & Lỗi (HTTP Codes)

Các mã phản hồi HTTP chuẩn có thể trả về từ API:

Mã HTTP	Ý nghĩa	Mô tả chi tiết & Hướng xử lý
200 OK	Thành công	Xác minh thành công, điểm uy tín đã được cập nhật và đồng bộ.
401 Unauthorized	Chưa xác thực	Thiếu header `x-api-key` hoặc khóa API không tồn tại / đã bị vô hiệu hóa.
403 Forbidden	Bị từ chối	Tài khoản đối tác đang ở trạng thái tạm dừng (Inactive) hoặc IP gọi không nằm trong Whitelist.
422 Unprocessable Entity	Lỗi dữ liệu	Không có bất kỳ tiêu chí định danh nào trong 4 trường bắt buộc, hoặc SĐT khẩn cấp trùng với SĐT chính.
429 Too Many Requests	Vượt hạn mức	Đối tác đã vượt quá số lượt gọi API cho phép trong chu kỳ Rate Limiting.

API Đối tác (REST)

Xác minh Khách hàng & Tích lũy Điểm uy tín

1. Địa chỉ Endpoint