REST API v1

Đánh giá Chuyến thuê xe & Tích lũy Điểm uy tín

1. Địa chỉ Endpoint

POST https://rentid.vn/api/v1/ratings

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/ratings" \
  -H "x-api-key: YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "phone": "0912345678",
    "cccd": "001089123456",
    "full_name": "Nguyễn Văn Tuấn",
    "star": 5,
    "comment": "Khách trả xe sạch sẽ, đúng giờ, giao tiếp lịch sự.",
    "contract_number": "HD-2026-9812",
    "rental_start_date": "2026-10-10 08:00:00",
    "rental_end_date": "2026-10-12 18:00:00",
    "rater_info": {
      "full_name": "Trần Thị Mai",
      "phone": "0988776655",
      "cccd": "001089123456"
    }
  }'

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

Yêu cầu gửi kèm thông tin đánh giá chuyến và tối thiểu 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
Thông tin định danh khách thuê (Cần ít nhất 1 trường)
phone string Tùy chọn* Số điện thoại khách thuê (10 số chuẩn VN: 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 chữ số).
license string Tùy chọn* Số Giấy phép lái xe (GPLX 6–20 ký tự).
passport string Tùy chọn* Số Hộ chiếu (cho khách nước ngoài).
full_name string Tùy chọn Họ và tên hiển thị của khách thuê xe (2–100 ký tự).
Thông tin Đánh giá & Nhận xét
star integer Bắt buộc Số sao đánh giá chuyến đi: Số nguyên từ 1 đến 5.
comment string Tùy chọn Nhận xét chi tiết về hành vi khách thuê (tối đa 2000 ký tự).
Thông tin Chuyến xe & Hợp đồng
external_reference_id string Tùy chọn Mã đơn hàng / mã chuyến xe duy nhất phía đối tác. Dùng chống gửi đúp.
contract_number string Tùy chọn Số hợp đồng thuê xe của đối tác.
rental_start_date string Tùy chọn Thời gian nhận xe (Định dạng: YYYY-MM-DD HH:mm:ss hoặc YYYY-MM-DD).
rental_end_date string Tùy chọn Thời gian trả xe. Phải cùng hoặc sau thời gian nhận xe.
contract_images array Tùy chọn Mảng URL ảnh chụp hợp đồng / biên bản bàn giao xe (tối đa 10 URL).
Thông tin Người thực hiện đánh giá (BẮT BUỘC)
rater_info object Bắt buộc Object chứa thông tin người đánh giá (chủ xe hoặc nhân viên đối tác). Bên trong bắt buộc phải có full_name.
rater_info.full_name string Bắt buộc Họ và tên người thực hiện đánh giá (2–100 ký tự). Dùng để hiển thị tại lịch sử thuê xe thay vì chỉ hiện tên đối tác.
rater_info.phone string Tùy chọn Số điện thoại liên hệ của người đánh giá (10 số chuẩn VN: 03, 05, 07, 08, 09).
rater_info.cccd string Tùy chọn Số Căn cước công dân của người đánh giá (9–20 chữ số). Phục vụ lưu trữ, tra cứu đối soát khi cần thiết.

info Quy tắc định danh tối thiểu:

Bắt buộc phải có ít nhất 1 trong 4 thông tin: phone, cccd, license, hoặc passport để hệ thống xâu chuỗi hồ sơ khách hàng.

shield Chống gửi đúp (Deduplication):

Mỗi chuyến thuê xe chỉ được đánh giá 1 lần duy nhất. Nếu gửi lại cùng external_reference_id hoặc contract_number, API sẽ trả về 409 Conflict.

4. Cơ chế Tính điểm Tín nhiệm (Trust Score)

Hệ thống tự động tính toán tác động điểm số theo số sao đánh giá và thưởng hoàn thành chuyến đi:

Mức đánh giá Điểm thay đổi Ý nghĩa nghiệp vụ
star star star star star
(5 Sao)
+20 điểm Khách thuê xuất sắc, trả xe hoàn hảo, giao tiếp lịch sự.
star star star star star
(4 Sao)
+10 điểm Khách thuê tốt, hoàn thành chuyến đi suôn sẻ.
star star star star star
(3 Sao)
0 điểm Bình thường. Ghi nhận lịch sử giao dịch, không thay đổi điểm số.
star star star star star
(2 Sao)
-10 điểm Kém. Trả xe trễ, xe bẩn, vi phạm nhỏ trong quá trình thuê.
star star star star star
(1 Sao)
-20 điểm Rất tệ. Thái độ bất hợp tác, phát sinh tranh chấp hoặc hỏng hóc.

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

1. Đánh giá thành công (201 Created):

{
  "status": 201,
  "success": true,
  "message": "Đánh giá chuyến đi đã được tiếp nhận thành công.",
  "data": {
    "rating_id": 842,
    "external_reference_id": "TRIP-2026-9812",
    "contract_number": "HD-2026-9812",
    "customer": {
      "name": "Nguyễn Văn Tuấn",
      "phone_masked": "0912***678",
      "cccd_masked": "0010***456"
    },
    "star": 5,
    "comment": "Khách giữ gìn xe rất sạch, giao tiếp lịch sự và trả xe đúng hạn.",
    "created_at": "2026-10-15T15:30:00+07:00"
  }
}

2. Lỗi trùng lặp chuyến (409 Conflict):

{
  "status": 409,
  "success": false,
  "message": "Đánh giá cho chuyến đi hoặc hợp đồng này đã được ghi nhận trước đó (Rating ID: #842)."
}

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

Tham số chuyến & Đánh giá

Thông tin người thực hiện đánh giá (Chủ xe / NV đối tác)
Phản hồi từ máy chủ

7. Bảng Mã Lỗi Chuẩn (HTTP Error Codes)

Mã HTTP Mã lỗi nội bộ Ý nghĩa & Hướng xử lý
401 Unauthorized AUTH_FAILED Khóa x-api-key không tồn tại, sai định dạng hoặc đã bị vô hiệu hóa.
403 Forbidden IP_FORBIDDEN Địa chỉ IP của server đối tác không nằm trong whitelist được duyệt.
404 Not Found NOT_FOUND Không tìm thấy bản ghi đánh giá hoặc bản ghi không thuộc quyền sở hữu của đối tác.
409 Conflict DUPLICATE_RATING Chuyến đi hoặc hợp đồng này đã được đối tác đánh giá trước đó.
422 Unprocessable VALIDATION_FAILED Dữ liệu vi phạm quy tắc: thiếu thông tin định danh tối thiểu, số sao ngoài khoảng 1..5, hoặc ngày trả xe trước ngày nhận xe.
429 Too Many Req RATE_LIMITED Vượt quá tần suất gửi yêu cầu trong 1 phút đã cấp cho đối tác.
500 Internal Error SYSTEM_ERROR Lỗi máy chủ nội bộ. Vui lòng liên hệ đội ngũ kỹ thuật RentID.

Đăng nhập

error

Hoặc đăng nhập với
Đăng nhập với Google Đăng nhập với Facebook Đăng nhập với X

Chưa có tài khoản? Đăng ký ngay