Webhook Nhận Thông báo vi phạm mới
RentID tự động gửi thông báo (HTTP POST) đến server của đối tác ngay khi có báo cáo vi phạm mới được phê duyệt. Để nhận dữ liệu theo thời gian thực, đối tác chỉ cần tạo một Webhook URL trên server của mình và cung cấp cho RentID để cấu hình.
1. Thông số kết nối
| Thành phần | Giá trị quy chuẩn | Yêu cầu & Ghi chú |
|---|---|---|
| Endpoint Đối tác | https://your-domain.com/webhook | Đối tác tự thiết lập trên server của mình và cung cấp cho RentID |
| Method | POST | RentID luôn gửi dưới dạng HTTP POST |
| Giao thức | HTTPS (bắt buộc) | Bắt buộc chứng chỉ SSL/TLS để mã hóa dữ liệu trên đường truyền |
| Header: X-Api-Key | YOUR_PARTNER_API_KEY | Khóa đối tác dùng để so khớp xác thực request từ RentID |
| Mã phản hồi hợp lệ | HTTP 2xx (200 hoặc 204) | Chấp nhận mọi mã thuộc dải HTTP 2xx (Khuyến nghị 200 OK hoặc 204 No Content). RentID không ràng buộc định dạng Body phản hồi. |
| Thời gian phản hồi | < 3 giây (Timeout: 25s) | Server đối tác nên phản hồi nhanh trong < 3s. Thời gian chờ tối đa 25s. RentID tự động thử lại nếu gặp sự cố mạng hoặc timeout. |
2. Cấu Trúc Dữ Liệu Payload
Để tuân thủ Nghị định 13/2023/NĐ-CP về bảo vệ dữ liệu cá nhân, thông tin định danh đối tượng được hệ thống RentID tự động che các ký tự nhạy cảm ở giữa:
| Thuộc tính | Kiểu | Mô tả chi tiết |
|---|---|---|
| report_code | string | Mã đơn duy nhất của RentID. |
| name | string | null | Họ và tên đối tượng vi phạm. |
| gender | string | null | Giới tính đối tượng. |
| phone | string | null | Số điện thoại đối tượng. |
| cccd | string | null | Số Căn cước công dân / CMND. |
| string | null | Địa chỉ email đối tượng. | |
| license_number | string | null | Số Giấy phép lái xe GPLX. |
| passport_number | string | null | Số Hộ chiếu. |
| address | string | null | Địa chỉ cư trú đầy đủ. |
| reason | string | Hành vi vi phạm. |
| description | string | null | Mô tả tóm tắt sự việc vi phạm. |
| approved_at | string | Thời điểm Admin RentID phê duyệt đơn. |
{
"report_code": "RP-20260914-00152",
"name": "Nguyễn *** An",
"gender": "Nam",
"phone": "098***1234",
"cccd": "0010***345",
"email": "ng***@gmail.com",
"license_number": "0101***789",
"passport_number": null,
"address": "Số 12 phố ***, Phường Hàng Bạc, Hà Nội",
"reason": "Mang xe đi cầm cố / Chiếm đoạt tài sản",
"description": "Khách thuê xe tự lái hiệu Mazda 3 quá hạn 10 ngày không trả, tự ý tháo định vị mang đi cầm đồ...",
"approved_at": "2026-09-14 11:00:00"
}3. Quy Chuẩn Phản Hồi Từ Đối Tác
Để xác nhận đã tiếp nhận dữ liệu báo cáo vi phạm thành công từ RentID, server của đối tác cần lưu ý các quy chuẩn sau:
check_circle Mã trạng thái HTTP (Status Code)
Server đối tác cần phản hồi mã trạng thái thuộc dải HTTP 2xx (khuyến nghị 200 OK hoặc 204 No Content). Các mã lỗi 4xx, 5xx hoặc không nhận được phản hồi sẽ được hệ thống RentID tính là gửi thất bại.
schedule Thời gian xử lý & Phản hồi (Response Time)
Hệ thống RentID thiết lập thời gian chờ tối đa là 25 giây (phản hồi trong khoảng thời gian này đều được ghi nhận thành công). Tuy nhiên, đối tác nên phản hồi sớm (khuyến nghị dưới 3 giây) bằng cách đẩy dữ liệu vào Hàng đợi (Queue hoặc Background Task) để xử lý riêng, tránh chạy các tác vụ nặng trực tiếp làm treo hoặc đứt kết nối.
fingerprint Chống xử lý trùng lặp (Idempotency)
Mỗi báo cáo luôn đi kèm một mã định danh duy nhất là report_code (ví dụ: RP-20260914-00152). Đối tác nên lưu và kiểm tra mã này trong cơ sở dữ liệu để tự động bỏ qua nếu nhận được bản tin gửi lại do sự cố mạng.
Ví dụ định dạng dữ liệu trả về (Response Body)
RentID không bắt buộc cấu trúc Response Body. Đối tác có thể để trống hoàn toàn (với mã 204 No Content) hoặc trả về một gói tin JSON đơn giản xác nhận đã nhận:
{
"success": true,
"message": "Webhook received successfully"
}4. Trình Giả Lập Bắn Webhook (Interactive Sandbox)
Nhập endpoint URL server của bạn để RentID bắn thử dữ liệu báo cáo vi phạm giả lập và kiểm tra khả năng phản hồi trực tiếp:
