Tra cứu uy tín Khách thuê
Endpoint cho phép đối tác gửi các tiêu chí định danh (Số điện thoại, CCCD, GPLX, Hộ chiếu, Email hoặc Từ khóa) để truy vấn lịch sử vi phạm, kiểm tra danh bạ và tính điểm tín nhiệm rủi ro theo thời gian thực.
1. Địa chỉ Endpoint
https://rentid.vn/api/v1/lookup
2. Xác thực Header
Yêu cầu truyền khóa API của đối tác qua HTTPS Header x-api-key:
curl -X GET "https://rentid.vn/api/v1/lookup?phone=0987654321" \
-H "x-api-key: YOUR_PARTNER_API_KEY" \
-H "Accept: application/json"3. Tham số Tra cứu (Query Parameters)
Hệ thống hỗ trợ tra cứu linh hoạt theo từng tiêu chí riêng lẻ hoặc kết hợp đa trường:
| Tham số | Kiểu | Mô tả & Định dạng |
|---|---|---|
| phone | string | Số điện thoại đối tượng (10 chữ số). |
| cccd | string | Số Căn cước công dân hoặc CMND (9 hoặc 12 chữ số). |
| license | string | Số Giấy phép lái xe (GPLX 12 số). |
| passport | string | Số Hộ chiếu (khách nước ngoài hoặc công dân). |
| string | Địa chỉ email đối tượng tra cứu. | |
| full_name | string | Họ và tên người thuê xe dùng đối chiếu danh tính. |
| keyword | string | Từ khóa tra cứu nhanh (hệ thống tự động phát hiện định dạng). |
(*) Yêu cầu truyền tối thiểu 1 trong các trường định danh (phone, cccd, license, passport, email hoặc keyword).
4. Cấu trúc Phản hồi (JSON Response)
Cấu trúc các trường dữ liệu được trả về trong đối tượng data:
| Trường dữ liệu | Kiểu | Mô tả & Ý nghĩa |
|---|---|---|
| record_found | boolean | Đã có hồ sơ trên hệ thống (true: đã có hồ sơ, false: chưa từng phát sinh dữ liệu trong hệ thống). |
| has_reports | boolean | Có báo cáo vi phạm được duyệt (true: có ít nhất 1 vi phạm, false: 0 vi phạm). |
| total_reports | integer | Số lượng báo cáo vi phạm được duyệt trong hệ thống. |
| score | integer|null | Điểm tín nhiệm đối tượng (thang điểm 0–1000). Trả về null khi chưa có dữ liệu hồ sơ. |
| status | string | Mã trạng thái phân loại tín nhiệm (not_found: chưa có hồ sơ trong hệ thống, standard: tiêu chuẩn, good: uy tín, very_good: rất uy tín, excellent: xuất sắc, caution: cần theo dõi, risk: rủi ro cao). |
| violations | array | Danh sách chi tiết vi phạm kèm bằng chứng. Rỗng [] nếu không có vi phạm. |
| url | string | Đường dẫn URL dẫn thẳng đến trang tìm kiếm trên giao diện Web RentID. |
Ví dụ phản hồi theo từng kịch bản
1. Trường hợp có vi phạm
Số điện thoại hoặc CCCD tra cứu có lịch sử vi phạm được ghi nhận trong hệ thống (ví dụ: bùng xe, nợ xấu, lừa đảo). Điểm tín nhiệm giảm và trả về danh sách chi tiết các vi phạm kèm bằng chứng.
{
"status": 200,
"success": true,
"message": "Tra cứu thông tin thành công!",
"data": {
"query": {
"phone": "0987654321",
"cccd": "001200001234"
},
"record_found": true,
"has_reports": true,
"score": 200,
"status": "risk",
"status_label": "Cảnh báo rủi ro",
"name": "Nguyễn Văn Gian Lận",
"url": "https://rentid.vn/tra-cuu-thong-tin?phone=0987654321&signature=...",
"total_reports": 1,
"violations": [
{
"id": 12,
"reason": "Bùng tiền thuê xe",
"description": "Không trả xe đúng hạn và chặn liên lạc",
"score_impact": -500,
"reported_at": "2026-09-01T08:30:00Z",
"images": [
"https://rentid.vn/storage/reports/evidence1.jpg"
]
}
],
"search_at": "2026-09-08T10:00:00Z"
}
}2. Trường hợp hồ sơ sạch
Khách hàng đã có thông tin trong hệ thống nhưng không có bất kỳ báo cáo vi phạm nào. Điểm tín nhiệm ở mức tiêu chuẩn hoặc tốt, không có danh sách vi phạm.
{
"status": 200,
"success": true,
"message": "Tra cứu thông tin thành công!",
"data": {
"query": {
"phone": "0911223344"
},
"record_found": true,
"has_reports": false,
"score": 500,
"status": "standard",
"status_label": "Tiêu chuẩn",
"name": "Nguyễn Văn Uy Tín",
"url": "https://rentid.vn/tra-cuu-thong-tin?phone=0911223344&signature=...",
"total_reports": 0,
"violations": [],
"search_at": "2026-09-08T10:00:00Z"
}
}3. Trường hợp chưa có dữ liệu
Đối tượng mới hoàn toàn, chưa từng ghi nhận dữ liệu trong hệ thống. API vẫn phản hồi mã HTTP 200 để đối tác tiếp tục thẩm định theo quy trình khách hàng mới.
{
"status": 200,
"success": true,
"message": "Tra cứu thông tin thành công!",
"data": {
"query": {
"phone": "0999999999"
},
"record_found": false,
"has_reports": false,
"score": null,
"status": "not_found",
"status_label": "Chưa có hồ sơ trong hệ thống",
"name": null,
"url": "https://rentid.vn/tra-cuu-thong-tin?phone=0999999999&signature=...",
"total_reports": 0,
"violations": [],
"search_at": "2026-09-08T10:00:00Z"
}
}play_circle 5. Thử nghiệm Trực tiếp (Sandbox)
6. Mã Trạng Thái & Lỗi (HTTP Codes)
Các mã phản hồi chuẩn mà hệ thống API có thể trả về:
| Mã HTTP | Ý nghĩa | Mô tả chi tiết |
|---|---|---|
| 200 OK | Thành công | Yêu cầu hợp lệ và đã trả về kết quả thẩm định. |
| 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ị khóa. |
| 422 Unprocessable | Lỗi tham số | Không truyền bất kỳ tiêu chí định danh nào hoặc định dạng không hợp lệ. |
| 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ỳ. |
