NAV

Phiên bản hiện tại: 1.0.1

Phiên bản Mô tả Chi tiết thay đổi
1.0.0 Các API ban đầu
1.0.1 Thêm chi tiết lỗi đã được cover cho API gọi Engine Mục chi tiết lỗi đầu ra
1.0.2 Thêm API trả về ảnh có vẽ sẵn mask Chi tiết API
1.0.3 Thêm trường oldImageId để xóa ảnh cũ cho API call engine
1.0.4 Thay đổi API lấy link upload ảnh (không bắt buộc truyền filePaths và trả thêm 1 trường filePath ở response dùng để call engine) Chi tiết field
2.0.0 Thay đổi API gọi engine cho phần cấp đơn (bắt buộc truyền claimFolderId để call engine) Chi tiết field

1. Đặc tả tài liệu kết nối

1.1 Các thông tin cơ bản

Method
API Url
API Headers

1.2 Các mã HTTP Code trả về

1.3 Base Url:

https://api.aicycle.ai/insurance

API Key: Liên hệ đội ngũ support tích hợp của AICycle để được cấp apiKey cho tổ chức.

2. APIs tích hợp ValueMe

2.1: Flow tích hợp giữa các đối tác và AICycle

alt text

2.2: API định giá xe v3 (sử dụng CodeBook hãng hiệu và phiên bản của đối tác)

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/valuation/v3/car-valuate
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/valuation/v3/car-valuate' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "versionCode": "BMW02006",
    "year": 2021
}'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
versionCode Code phiên bản xe Bắt buộc Text 1,255 BMW02006
year Năm sản xuất Bắt buộc Number 1,9999 2020
vinCode Thông tin số khung (số VIN) Tùy chọn Text 1,9999 VNICODETOY211
gearBox Hộp số Tùy chọn Text 1,9999 AT
wheelDrive Dẫn động Tùy chọn Text 1,9999 4WD
engineCapacity Dung tích động cơ Tùy chọn Float 1,9999 1.5

c. Chi tiết đầu ra

HTTP Status Code Mô tả
200 Định giá thành công
400 Định giá không thành công (do sai dữ liệu đầu vào)
401 Sai thông tin xác thực
500 Lỗi từ hệ thống AICycle (liên hệ AIC Customer Support với)
{
    "message": "This version not support versionCode (TOYAVA0111NK)",
    "name": "BadRequestError",
    "status": 400,
    "traceId": "6ae1188803e4aebc9bb7ade579994fc3"
}

{
    "message": "This version not support year (2020)",
    "name": "BadRequestError",
    "status": 400,
    "errors": null,
    "listAvailableYears": [
        2006,
        2007,
        2008,
        2009,
        2010,
        2011,
        2012,
        2013,
        2013,
        2014,
        2014,
        2015
    ],
    "traceId": "d097a03a9e03e50ef7925b72bdeef9a8"
}

{
    "message": "Api token is required.",
    "traceId": "1716f059b256f097771ceba42667f3c6"
}


[<ValuationResult>]

























Chi tiết Object item ValuationResult

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
companyCode Mã hãng xe của tổ chức Tùy chọn Text 1,255 code-hang-xe
modelCode Mã hiệu xe của tổ chức Tùy chọn Text 1,255 code-hieu-xe
versionCode Mã phiên bản xe của tổ chức Bắt buộc Text 1,255 code-phien-ban-xe
year Năm sản xuất Bắt buộc Number 1,9999 2020
minPrice Giá min của xe Bắt buộc Number 1,999999999 100000000
maxPrice Giá max của xe Bắt buộc Number 1,999999999 300000000
carValue Giá trị xe Bắt buộc Number 1,999999999 300000000
isWarning Thông tin về dòng xe này trên thị trường có đang thiếu hay không? Bắt buộc Boolean n true
listedPrice Giá xe niêm yết Bắt buộc Number 1,999999999 320000000
minListedPrice Giá trị min của giá niêm yết Bắt buộc Number 1,999999999 305000000
maxListedPrice Giá trị max của giá niêm yết Bắt buộc Number 1,999999999 330000000
hanoiOnRoadPrice Gía lăn bánh tại Hà Nội Bắt buộc Number 1,999999999 323000000
hcmOnRoadPrice Gía lăn bánh tại TP HCM Bắt buộc Number 1,999999999 323000000
generalOnRoadPrice Gía lăn bánh tại các tỉnh khác Bắt buộc Number 1,999999999 323000000
carFuelName Nhiên liệu Bắt buộc Text 1,255 Xăng
numOfSeat Số chỗ ngồi Bắt buộc Number 1,9999 5
listAvailableYears Danh sách các năm gợi ý hợp lệ cho CodeBook hiện tại Bắt buộc Array[Number] 1,999999999 [2020,2021]

d. Ví dụ đầu ra

[
    {
        "companyCode": "<companyCode>",
        "modelCode": "<modelCode>",
        "versionCode": "<versionCode>",
        "year": <year>,
        "maxPrice": 679943600,
        "carValue": 601720000,
        "minPrice": 559599600,
        "isWarning": true,
        "listedPrice": 710000000,
        "minListedPrice": 674500000,
        "maxListedPrice": 816500000,
        "hanoiOnRoadPrice": 732380000,
        "generalOnRoadPrice": 713380000,
        "hcmOnRoadPrice": 732380000,
        "carFuelName": "Xăng",
        "numOfSeat": 5,
        "listAvailableYears": [
            2006,
            2007,
            2008,
            2009,
            2010,
            2011,
            2012,
            2013,
            2013,
            2014,
            2014,
            2015
        ]
    }
]












2.3: API lấy danh sách hãng xe của AICycle (car company)

a. Thông tin cơ bản

Method GET
API Url https://api.aicycle.ai/insurance/car-info/company
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Ví dụ

curl --location --request GET 'https://stage-api-insurance.aicycle.ai/car-info/company?limit=1000' \
--header 'Authorization: Bearer <API Key>'

Loại đầu vào: Query

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehicleBrandName Tên hãng xe Tùy chọn Text 1, 255 TOYOTA
limit Limit số lượng bản ghi trả về Tùy chọn Number 1,9999 30
offset Bỏ qua 1 số bản ghi Tùy chọn Number 0,9999 0

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
count Số lượng bản ghi Bắt buộc Number 1,9999 30
limit Giới hạn bản ghi Bắt buộc Number 1,9999 100
offset Bỏ qua 1 số bản ghi Bắt buộc Number 0,9999 0
records Chi tiết các hãng xe Bắt buộc Array[carCompanyInfo] n []

Chi tiết Object item carCompanyInfo

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompanyId Mã hãng xe Bắt buộc Text 1,255 uuid-hang-xe
vehicleBrandName Tên hãng xe Bắt buộc Text 1,255 TOYOTA

d. Ví dụ đầu ra

{
    "count": 114,
    "limit": 1000,
    "offset": 0,
    "records": [
        {
            "carCompanyId": "uuid-hang-xe",
            "vehicleBrandName": "TOYOTA"
        }
    ]
}





2.4: API lấy danh sách hiệu xe của AICycle (car model)

a. Thông tin cơ bản

Method GET
API Url https://api.aicycle.ai/insurance/car-info/model
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Query

Ví dụ

curl --location --request GET 'https://stage-api-insurance.aicycle.ai/car-info/model?carCompanyId=<uuid-hang-xe>&limit=100' \
--header 'Authorization: Bearer <API Key>'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
name Tên hiệu xe Tùy chọn Text 1,255 VIOS
carCompanyId Id hãng xe Tùy chọn Text 1,255 uuid-hieu-xe
limit Limit số lượng bản ghi trả về Tùy chọn Number 1,9999 30
offset Bỏ qua 1 số bản ghi Tùy chọn Number 0,9999 0

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
count Số lượng bản ghi Bắt buộc Number 1,9999 30
limit Giới hạn bản ghi Bắt buộc Number 1,9999 100
offset Bỏ qua 1 số bản ghi Bắt buộc Number 0,9999 0
records Chi tiết các hiệu xe Bắt buộc Array[carModelInfo] n []

Chi tiết Object item carModelInfo

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carModelId Mã hiệu xe Bắt buộc Text 1,255 uuid-hieu-xe
carModelName Tên hiệu xe Bắt buộc Text 1,255 VIOS

d. Ví dụ đầu ra

{
    "count": 114,
    "limit": 1000,
    "offset": 0,
    "records": [
        {
            "carModelId": "uuid-hieu-xe",
            "carModelName": "VIOS"
        }
    ]
}





2.5: API lấy danh sách các năm sản xuất (manufactured year) theo hãng xe và hiệu xe

a. Thông tin cơ bản

Method GET
API Url https://api.aicycle.ai/insurance/car-info/company/{carCompanyId}/model/{carModelId}/manufactured-years
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Param

Ví dụ

curl --location --request GET 'https://api.aicycle.ai/insurance/car-info/company/{carCompanyId}/model/{carModelId}/manufactured-years' \
--header 'Authorization: Bearer <API Key>'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompanyId Id hãng xe Bắt buộc Text 1,255 uuid-hang-xe
carModelId Id hiệu xe Bắt buộc Text 1,255 uuid-hieu-xe

c. Ví dụ đầu ra

[
    2023,
    2022,
    2021,
    2020,
    2019,
    2018,
    2017,
    2016,
    2015,
    2014,
    2013,
    2012,
    2011
]






2.6: API lấy ra các phiên bản xe (car version) theo hãng xe và hiệu xe

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/car-info/company/{carCompanyId}/model/{carModelId}/versions
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Param

Ví dụ

curl --location --request GET 'https://api.aicycle.ai/insurance/car-info/company/{carCompanyId}/model/{carModelId}/versions?year=2011' \
--header 'Authorization: Bearer <API Key>'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompanyId Id hãng xe Bắt buộc Text 1,255 uuid-hang-xe
carModelId Id hiệu xe Bắt buộc Text 1,255 uuid-hieu-xe

Loại đầu vào: Query

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
year Năm sản xuất Tùy chọn Number 1,9999 2001

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carVersionId Id phiên bản xe Bắt buộc Text 1,255 uuid-phien-ban-xe
carVersionName Tên phiên bản xe Bắt buộc Text 1,255 VIOS 1.5.G
carCompanyId Id hãng xe Bắt buộc Text 1,255 uuid-hang-xe
carModelId Id hiệu xe Bắt buộc Text 1,255 uuid-hieu-xe
carVersionKey Key unique của phiên bản xe Bắt buộc Text 1,255 key-version
year Năm sản xuất Bắt buộc Number 1,999999 2011
carTypeName Loại xe Không bắt buộc Text 1,255 CROSSOVER
carFuelName Loại nhiên liệu Không bắt buộc Text 1,255 Xăng
carOriginName Tên xuất xứ Không bắt buộc Text 1,255 LRTN
carGearboxName Loại hộp số Không bắt buộc Text 1,255 AT
carOptionName Tên tùy chọn Không bắt buộc Text 1,255 OPTION NAME
carWheelDriveName Loại bánh xe Không bắt buộc Text 1,255 FWD
payload Trọng tải Không bắt buộc Array 1,255 [“900kg”, “890kg”]
numOfSeat Số lượng ghế Không bắt buộc Number 1,9999 5
engineDisplacement Dung tích động cơ Không bắt buộc Number 1,9999 1.5

d. Ví dụ đầu ra

[
    {
        "carVersionId": "<carVersionId>",
        "carVersionName": "1.5 G",
        "carCompanyId": "<carCompanyId>",
        "carModelId": "<carModelId>",
        "carVersionKey": "toyota-vios-1.5.g-2011",
        "year": 2011,
        "carTypeName": "CROSSOVER",
        "carFuelName": "Xăng",
        "carOriginName": "LRTN",
        "carGearboxName": "AT",
        "carOptionName": "OPTION NAME",
        "carWheelDriveName": "FWD",
        "payload": [
            "900kg",
            "890kg"
        ],
        "numOfSeat": 5,
        "engineDisplacement": 1.5
    }
]




2.7: API yêu cầu mở mới codebook

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/codebook-requests
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/codebook-requests' \
--header 'Authorization: Bearer <API Key> \
--header 'Content-Type: application/json' \
--data '{
    "carCompanyName": "TOYOTA",
    "carCompanyCode": "TOY",
    "carModelName": "FORTUNER",
    "carModelCode": "TOY03",
    "carVersionName": "3.0 V",
    "carVersionCode": "TOY03011",
    "price": 250000000,
    "option": "PIN",
    "carType": "SUV",
    "carGearBox": "AT",
    "engineCapacity": 2.7,
    "numOfSeat": 7,
    "carFuel": "Xăng",
    "carWheelDrive": "RFD"
}'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompanyName Tên hãng xe Bắt buộc Text 1,255 TOYOTA
carCompanyCode Code hãng xe Tùy chọn Text 1,255 TOY
carModelName Tên hiệu xe Bắt buộc Text 1,255 FORTUNER
carModelCode Code hiệu xe Tùy chọn Text 1,255 TOY03
carVersionName Tên phiên bản Bắt buộc Text 1,255 3.0 V
carVersionCode Code phiên bản Tùy chọn Text 1,255 TOY03011
price Giá xe Tùy chọn Number 1,9999 250000000
option Option riêng Tùy chọn Text 1,255 PIN
carType Kiểu xe Tùy chọn Text 1,255 SUV
carGearBox Hộp số Tùy chọn Text 1,255 AT
engineCapacity Dung tích động cơ Tùy chọn Number 1,9999 2.7
numOfSeat Số chỗ ngồi Tùy chọn Number 1,9999 7
carFuel Nhiên liệu Tùy chọn Text 1,255 Xăng
carWheelDrive Dẫn động Tùy chọn Text 1,255 RFD

c. Chi tiết đầu ra

Loại đầu ra: StatusCode

Code Mô tả
201 Tạo request codebook thành công
400 Lỗi request từ client, review lại request và thử lại
401 Lỗi thông tin xác thực hoặc ủy quyền
500 Lỗi từ hệ thống API

2.8: API định giá xe v1 (sử dụng CodeBook hãng hiệu và phiên bản của AICycle) (deprecated)

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/valuation/car-valuate
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Ví dụ

curl --location --request POST 'https://api.aicycle.ai/insurance/valuation/car-valuate' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "carCompanyId": "uuid-hang-xe",
    "carModelId": "uuid-hieu-xe",
    "carVersionId": "uuid-phien-ban-xe",
    "year": 2020
}'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompanyId Id hãng xe Bắt buộc Text 1,255 uuid-hang-xe
carModelId Id hiệu xe Bắt buộc Text 1,255 uuid-hieu-xe
carVersionId Id phiên bản xe Bắt buộc Text 1,255 uuid-phien-ban-xe
year Năm sản xuất Bắt buộc Number 1,9999 2020
option Option riêng của xe Optional Text 1,255 pin
carStatus Tình trạng xe Optional Text 1,255 old

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompanyId Id hãng xe Bắt buộc Text 1,255 uuid-hang-xe
carModelId Id hiệu xe Bắt buộc Text 1,255 uuid-hieu-xe
carVersionId Id phiên bản xe Bắt buộc Text 1,255 uuid-phien-ban-xe
year Năm sản xuất Bắt buộc Number 1,9999 2020
minPrice Giá min của xe Bắt buộc Number 1,999999999 100000000
maxPrice Giá max của xe Bắt buộc Number 1,999999999 300000000
carValue Giá trị xe Bắt buộc Number 1,999999999 300000000
isWarning Thông tin về dòng xe này trên thị trường có đang thiếu hay không? Bắt buộc Boolean n true
listedPrice Giá xe niêm yết Bắt buộc Number 1,999999999 320000000
minListedPrice Giá trị min của giá niêm yết Bắt buộc Number 1,999999999 305000000
maxListedPrice Giá trị max của giá niêm yết Bắt buộc Number 1,999999999 330000000
hanoiOnRoadPrice Gía lăn bánh tại Hà Nội Bắt buộc Number 1,999999999 323000000
hcmOnRoadPrice Gía lăn bánh tại TP HCM Bắt buộc Number 1,999999999 323000000
generalOnRoadPrice Gía lăn bánh tại các tỉnh khác Bắt buộc Number 1,999999999 323000000
listAvailableYears Danh sách các năm thực sự hỗ trợ (chỉ trả về khi năm yêu cầu không được hỗ trợ ở phiên bản này và cơ chế trả lỗi bị tắt) Không bắt buộc Array[Number] [2023, 2022, 2020]

d. Ví dụ đầu ra

[
    {
        "carVersionId": "<carVersionId>",
        "carCompanyId": "<carCompanyId>",
        "carModelId": "<carModelId>",
        "year": <year>,
        "maxPrice": 679943600,
        "carValue": 601720000,
        "minPrice": 559599600,
        "isWarning": true,
        "listedPrice": 710000000,
        "minListedPrice": 674500000,
        "maxListedPrice": 816500000,
        "hanoiOnRoadPrice": 732380000,
        "generalOnRoadPrice": 713380000,
        "hcmOnRoadPrice": 732380000,
        "listAvailableYears": [2023, 2022, 2020]
    }
]







Trường hợp Lỗi

Chi tiết Response Body (Lỗi)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
message Thông báo lỗi Có Text Phiên bản xe này hiện không hỗ trợ năm 2023
listAvailableYears Danh sách các năm hỗ trợ nếu phiên bản xe không hỗ trợ năm định giá Không Array[Number] [2018, 2017, 2016]
name Loại lỗi Không Text BadRequestError
status Mã lỗi HTTP Có Number 400
errors Chi tiết lỗi Không Object/Array null
traceId ID tra cứu log Không Text 1

Ví dụ Response Lỗi

{
    "message": "Phiên bản xe này hiện không hỗ trợ năm 2023",
    "name": "BadRequestError",
    "status": 400,
    "errors": null,
    "listAvailableYears": [
        2018,
        2017,
        2016,
        2015,
        2014,
        2013
    ],
    "traceId": "1"
}

2.9: API OCR (Upload ảnh để nhận diện thông tin xe)

a. Thông tin Request

Method POST
API Url https://api.aicycle.ai/insurance/valuation/external/ocr/upload
API Headers { "Authorization": "Bearer $$API_KEY$$" }

Chi tiết Body (FormData)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
img File ảnh cần nhận diện Bắt buộc File

Ví dụ Request

curl --location 'https://api.aicycle.ai/insurance/valuation/external/ocr/upload' \
--header 'Authorization: Bearer <API Key>' \
--form 'img=@"/path/to/image.jpeg"'

b. Thông tin Response

1. Trường hợp Thành công (HTTP 200)

Chi tiết Response Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehicleInspectionOcrId ID OCR Có Number 176
imageUrls Mảng các URL ảnh đã upload Có Array[Text] [“imageUrl”]
registrationNumber Biển số xe Có Text 60K-539.36
inspectionNumber Số đăng kiểm Có Text 6001S-178649
typeValue Loại phương tiện Có Text ô tô tải thùng kín
markValue Nhãn hiệu Có Text KIA
modelCode Số loại Có Text A27R131E5-K11
engineNumber Số máy Có Text SD599967D4CB
chassisNumber Số khung Có Text RNHA39KHGST014330
manufacturedYearCountry Năm, Nước sản xuất Có Text 2025, Việt Nam
wheelFormula Công thức bánh xe Có Text 4x2
typeOfFuel Loại nhiên liệu Có Text Diesel
engineDisplacement Dung tích động cơ Có Text 2497
seriNumber Số sê-ri Có Text VA 1832605
docNumber Số giấy tờ Có Text EF7C61E
wheelTread Vết bánh xe Có Text 1490/1340
overallDimension Kích thước bao Có Text 5270x1835x2650
wheelbase Chiều dài cơ sở Có Text 2615
containerDimension Kích thước lòng thùng Có Text 3200x1670x1830
kerbMass Khối lượng bản thân Có Text 1900
payLoadMassFifthWheel Khối lượng hàng chuyên chở Có Text 1900/1900
totalMass Khối lượng toàn bộ Có Text 3995/3995
towedMass Khối lượng kéo theo Có Text
permissiblePersCarried Số người cho phép chở Có Text Ngồi: 2 Đứng: 0 Nằm: 0
maxOutputRpm Công suất lớn nhất/tốc độ quay Có Text 96kW/3800rpm
tireInformation Thông tin lốp Có Text 2:4;155R12 1:2:195R15
engineModel Kiểu động cơ Có Text D4CB
engineType Loại động cơ Có Text 4 xi lanh thẳng hàng
serviceLife Niên hạn sử dụng Có Text 2050
vehicleGroup Nhóm xe Có Text ô tô tải
motorType Loại động cơ điện Không Text
numberOfMotorsMotorModel Số động cơ điện Không Text
voltageTotalRatedPower Điện áp Không Text
batteryType Loại pin Không Text
voltageCapacity Dung lượng Không Text
maxLuggageDimension Kích thước hành lý Không Text
authorizedMassOnFifthWheel Tải trọng cho phép móc Không Text
xmcdType XMCD Type Không Text
tankOverallDimension Kích thước bồn Không Text
totalMassOnKingpin Khối lượng toàn bộ chốt Không Text
isValidDocument Trạng thái hợp lệ của tài liệu Có Boolean true
seriNumberScore Điểm tin cậy số seri Có Number 0.977454
problem Vấn đề của giấy tờ Không Text
imageName Tên ảnh gốc Có Text wQTK-sAik…
carCompany Hãng xe nhận diện được Có Text KIA
carModel Dòng xe nhận diện được Có Text A27R131E5-K11
carVersion Phiên bản nhận diện được Có Text K200 Thùng kín 1.9 tấn
manufactureYear Năm sản xuất nhận diện được Có Text 2025
vehicleCategory Phân loại xe Có Text truck
suggestedVersions Danh sách phiên bản gợi ý Có Array

Chi tiết Object item suggestedVersions

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
codebookName Tên phiên bản trong codebook Có Text KIA FRONTIER K200…
carCompany Hãng xe Có Text KIA
carModel Dòng xe Có Text A27R131E5-K11
carVersion Phiên bản Có Text K200 Thùng kín 1.9 tấn
manufactureYear Năm sản xuất Có Text 2025
carValue Giá trị xe ước tính hiện tại Không Number 384000000
minPrice Giá định giá thấp nhất Không Number 380000000
maxPrice Giá định giá cao nhất Không Number 388000000
newCarPrice Giá xe mới (niêm yết) Không Number 415900000
barrelType Loại thùng (dành cho xe tải) Không Text Thùng kín
numOfSeat Số chỗ ngồi Không Number 2
score Điểm tin cậy Có Number 1
isAiGenerated Kết quả do LLM sinh ra Có Boolean true

Ví dụ Response Thành công

{
    "vehicleInspectionOcrId": 176,
    "imageUrls": [
        "imageUrl"
    ],
    "registrationNumber": "60K-539.36",
    "inspectionNumber": "6001S-178649",
    "typeValue": "ô tô tải thùng kín",
    "markValue": "KIA FRONTIER K200",
    "modelCode": "A27R131E5-K11",
    "engineNumber": "SD599967D4CB",
    "chassisNumber": "RNHA39KHGST014330",
    "manufacturedYearCountry": "2025, Việt Nam",
    "wheelFormula": "4x2",
    "typeOfFuel": "Diesel",
    "engineDisplacement": "2497",
    "seriNumber": "VA 1832605",
    "docNumber": "EF7C61E",
    "wheelTread": "1490/1340",
    "overallDimension": "5270x1835x2650",
    "wheelbase": "2615",
    "containerDimension": "3200x1670x1830",
    "kerbMass": "1900",
    "payLoadMassFifthWheel": "1900/1900",
    "totalMass": "3995/3995",
    "towedMass": "",
    "permissiblePersCarried": "Ngồi: 2 Đứng: 0 Nằm: 0",
    "maxOutputRpm": "96kW/3800rpm",
    "tireInformation": "2:4;155R12 1:2:195R15",
    "engineModel": "D4CB",
    "engineType": "4 xi lanh thẳng hàng",
    "serviceLife": "2050",
    "vehicleGroup": "ô tô tải",
    "motorType": "",
    "numberOfMotorsMotorModel": "",
    "voltageTotalRatedPower": "",
    "batteryType": "",
    "voltageCapacity": "",
    "maxLuggageDimension": "",
    "authorizedMassOnFifthWheel": "",
    "xmcdType": "",
    "tankOverallDimension": "",
    "totalMassOnKingpin": "",
    "isValidDocument": true,
    "seriNumberScore": 0.9774546325206757,
    "problem": "",
    "imageName": "wQTK-sAikZ34SXS_YSi9iLcOW20NKQK.png",
    "carCompany": "KIA",
    "carModel": "A27R131E5-K11",
    "carVersion": "K200 Thùng kín 1.9 tấn",
    "manufactureYear": "2025",
    "suggestedVersions": [
        {
            "codebookName": "KIA FRONTIER K200 ô tô tải thùng kín",
            "carCompany": "KIA",
            "carModel": "A27R131E5-K11",
            "carVersion": "K200 Thùng kín 1.9 tấn",
            "manufactureYear": "2025",
            "carValue": 384000000,
            "minPrice": 380000000,
            "maxPrice": 388000000,
            "newCarPrice": 415900000,
            "barrelType": "Thùng kín",
            "numOfSeat": 2,
            "score": 1,
            "isAiGenerated": true
        }
    ],
    "vehicleCategory": "truck"
}

2. Trường hợp Lỗi

Các mã HTTP Status Code

HTTP Status Code Mô tả
400 Lỗi dữ liệu đầu vào (Ví dụ: Thiếu tham số bắt buộc, sai định dạng)
401 Lỗi xác thực (Ví dụ: Token không hợp lệ hoặc đã hết hạn)
403 Lỗi không có quyền truy cập
500 Lỗi hệ thống từ server

Chi tiết Response Body (Lỗi)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
message Thông báo lỗi Có Text Error message description
name Tên mã lỗi (nếu có) Không Text BadRequestError
status Mã HTTP code tương ứng Có Number 400

Ví dụ Response Lỗi

{
    "message": "Error message description",
    "name": "BadRequestError",
    "status": 400
}

2.10: API định giá xe v2 (sử dụng tên hãng hiệu và phiên bản của AICycle)

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/valuation/v2/car-valuate
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Ví dụ

curl --location --request POST 'https://api.aicycle.ai/insurance/valuation/v2/car-valuate' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "carCompany": "VINFAST",
    "carModel": "VF8",
    "carVersion": "ECO",
    "year": 2024,
    "originName": "LRTN",
    "optionName": "PIN"

}'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompany Hãng xe Bắt buộc Text 1,255 VINFAST
carModel Hiệu xe Bắt buộc Text 1,255 VF8
carVersion Phiên bản xe Bắt buộc Text 1,255 ECO
year Năm sản xuất Bắt buộc Number 1,9999 2020
carOriginName Tên xuất xứ Không bắt buộc Text 1,255 LRTN
carOptionName Tên tùy chọn Không bắt buộc Text 1,255 PIN

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompany Hãng xe Bắt buộc Text 1,255 VINFAST
carModel Hiệu xe Bắt buộc Text 1,255 VF8
carVersion Phiên bản xe Bắt buộc Text 1,255 ECO
year Năm sản xuất Bắt buộc Number 1,9999 2020
carOptionName Tên tùy chọn Không bắt buộc Text 1,255 PIN
carOriginName Tên xuất xứ Không bắt buộc Text 1,255 LRTN
carFuelName Loại nhiên liệu Bắt buộc Text 1,255 Xăng
numOfSeat Số lượng ghế Bắt buộc Number 1,9999 8
minPrice Giá min của xe Bắt buộc Number 1,999999999 100000000
maxPrice Giá max của xe Bắt buộc Number 1,999999999 300000000
carValue Giá trị xe Bắt buộc Number 1,999999999 300000000
isWarning Thông tin về dòng xe này trên thị trường có đang thiếu hay không? Bắt buộc Boolean n true
listedPrice Giá xe niêm yết Bắt buộc Number 1,999999999 320000000
minListedPrice Giá trị min của giá niêm yết Bắt buộc Number 1,999999999 305000000
maxListedPrice Giá trị max của giá niêm yết Bắt buộc Number 1,999999999 330000000
hcmOnRoadPrice Gía lăn bánh tại TP HCM Bắt buộc Number 1,999999999 323000000
generalOnRoadPrice Gía lăn bánh tại các tỉnh khác Bắt buộc Number 1,999999999 323000000
additions Thông tin bổ sung Không bắt buộc Array 1,999999999 []

d. Ví dụ đầu ra

{
    "carCompany": "VINFAST",
    "carModel": "VF8",
    "carVersion": "ECO",
    "year": 2020,
    "carOptionName": "PIN",
    "carOriginName": "LRTN",
    "carFuelName": "Xăng",
    "numOfSeat": 8,
    "maxPrice": 657800000,
    "carValue": 557400000,
    "minPrice": 518400000,
    "isWarning": false,
    "listedPrice": 755000000,
    "minListedPrice": 717300000,
    "maxListedPrice": 868300000,
    "hanoiOnRoadPrice": 868400000,
    "generalOnRoadPrice": 834300000,
    "hcmOnRoadPrice": 853300000,
    "additions": []
}







2. Trường hợp Lỗi

Các mã HTTP Status Code

HTTP Status Code Mô tả
400 Lỗi dữ liệu đầu vào
401 Lỗi xác thực
403 Lỗi không có quyền truy cập
500 Lỗi hệ thống

Chi tiết Response Body (Lỗi)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
message Thông báo lỗi Có Text Error message description
vehicleInspectionOcrId ID OCR Không Number 157

Ví dụ Response Lỗi

{
    "message": "Error message description",
    "vehicleInspectionOcrId": 157
}

2.11: API tra cứu Codebook xe tải (Truck)

a. Thông tin cơ bản

Method GET
API Url https://api.aicycle.ai/insurance/api/v1/truck/codebooks
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Query

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/api/v1/truck/codebooks' \
--header 'Authorization: Bearer <API Key>'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
companyName Tên hãng xe Tùy chọn Text 1, 255 Hyundai
versionName Tên phiên bản Tùy chọn Text 1, 255 HD120SL 8 tấn
modelCode Model code xe Tùy chọn Text 1, 255 HD120SL
vehicleType Loại xe Tùy chọn Enum(truck,specialized,coach) truck
limit Giới hạn bản ghi Tùy chọn Number Default 30 30
offset Bỏ qua n bản ghi Tùy chọn Number Default 0 0

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
count Số lượng bản ghi Có Number 1
limit Giới hạn bản ghi Có Number 30
offset Bỏ qua n bản ghi Có Number 0
records Danh sách bản ghi Có Array[TruckCodebook] []

Chi tiết Object item TruckCodebook

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
companyName Tên hãng xe Có Text Hyundai
versionName Tên phiên bản Có Text HD120SL 8 tấn
modelCode Model code xe Có Text HD120SL
vehicleType Loại xe Có Text TRUCK
carType Loại xe Có Text Xe tải
barrelType Loại thùng Có Text Thùng kín
engine Động cơ Có Text D4DB
totalPayload Tổng tải trọng (kg) Có Number 12000
payload Tải trọng hàng hóa (kg) Có Number 8000
numberOfBoards Số bửng Có Number 2
truckBedSize Kích thước lòng thùng Có Text 6000x2000x2000
heightLength Chiều cao/dài Có Text 6000
origin Xuất xứ Có Text Vietnam

d. Ví dụ đầu ra

{
  "count": 1,
  "limit": 30,
  "offset": 0,
  "records": [
    {
      "companyName": "Hyundai",
      "versionName": "HD120SL 8 tấn",
      "modelCode": "HD120SL",
      "carType": "Xe tải",
      "vehicleType": "TRUCK",
      "barrelType": "Thùng kín",
      "engine": "D4DB",
      "totalPayload": 12000,
      "payload": 8000,
      "numberOfBoards": 2,
      "truckBedSize": "6000x2000x2000",
      "heightLength": "6000",
      "origin": "Vietnam"
    }
  ]
}

e. Mã lỗi thường gặp

HTTP Status Code Mô tả
200 Thành công
400 Lỗi request từ client, review lại request và thử lại
401 Lỗi thông tin xác thực hoặc ủy quyền
403 Lỗi không có quyền truy cập
500 Lỗi từ hệ thống API

2.12: API Định giá xe tải, xe chuyên dụng, xe khách

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/valuation/v3/truck-valuate
API Headers Authorization: Bearer <API Key>
Content-Type: application/json

b. Chi tiết đầu vào

Loại đầu vào: Body

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/valuation/v3/truck-valuate' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "companyName": "CHENGLONG",
    "versionName": "340HP 10X4 22.45 TẤN THÙNG MUI BẠT ALP",
    "modelCode": "LZ1340PELT/ALP-MB-1",
    "manufactureYear": 2020
}'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
companyName Tên hãng xe Có Text CHENGLONG
versionName Tên phiên bản Có Text 340HP 10X4 22.45 TẤN THÙNG MUI BẠT ALP
modelCode Model code Có Text LZ1340PELT/ALP-MB-1
manufactureYear Năm sản xuất Có Integer 2020

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehicleType Loại xe Có Text Truck
companyName Tên hãng xe Có Text CHENGLONG
versionName Tên phiên bản Có Text 340HP 10X4 22.45 TẤN THÙNG MUI BẠT ALP
modelCode Model code Có Text LZ1340PELT/ALP-MB-1
barrelType Loại thùng xe Không Text Thùng mui bạt
carTypeName Loại xe Không Text Xe quét đường
numOfSeat Số chỗ ngồi Không Number 2
manufactureYear Năm sản xuất Có Integer 2020
price Giá trị xe (VNĐ) Có Number 180000000
minPrice Giá trị xe tối thiểu (VNĐ) Có Number 171000000
maxPrice Giá trị xe tối đa (VNĐ) Có Number 189000000

d. Ví dụ đầu ra

{
    "vehicleType": "Truck",
    "companyName": "CHENGLONG",
    "versionName": "340HP 10X4 22.45 TẤN THÙNG MUI BẠT ALP",
    "modelCode": "LZ1340PELT/ALP-MB-1",
    "barrelType": "Thùng mui bạt",
    "manufactureYear": 2020,
    "price": 180000000,
    "minPrice": 171000000,
    "maxPrice": 189000000
}

e. Mã lỗi thường gặp

HTTP Status Code Mô tả
200 Định giá xe thành công
400 Lỗi request từ client, review lại request và thử lại
401 Lỗi thông tin xác thực hoặc ủy quyền
500 Lỗi từ hệ thống API

2.13: API Đồng bộ Codebook (Danh sách xe)

a. Thông tin Request

Method GET
API Url https://api.aicycle.ai/insurance/api/v1/sync-codebooks
API Headers { "Authorization": "Bearer $$API_KEY$$" }

Chi tiết Query

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
limit Số lượng bản ghi trả về Không Number 1,9999 30
offset Điểm bắt đầu (phân trang) Không Number 0,9999 0
vehicleType Phân loại xe muốn lấy Không Text 1,255 car

Ví dụ Request

curl --location --request GET 'https://api.aicycle.ai/insurance/api/v1/sync-codebooks?limit=30&offset=0&vehicleType=car' \
--header 'Authorization: Bearer <API Key>'

b. Thông tin Response

1. Trường hợp Thành công (HTTP 200)

Chi tiết Response Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
count Tổng số bản ghi Có Number 8311
limit Số lượng bản ghi trả về Có Number 5
offset Điểm bắt đầu Có Number 0
records Danh sách các xe Có Array[RecordItem] []

Chi tiết Object item RecordItem

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
codebookKey Mã định danh Có Text 1,255 acura-cl-3.0-at-nk
carCompanyName Hãng xe Có Text 1,255 ACURA
carModelName Dòng xe Có Text 1,255 CL
carVersionName Phiên bản Có Text 1,255 3.0 AT
availableYears Mảng các năm sản xuất Có Array[Number] 1,9999 [1997]
originName Xuất xứ Không Text 1,255 NK
fuel Nhiên liệu Không Text 1,255 Xăng
numOfSeat Số chỗ ngồi Không Number 1,9999 4
carType Loại thân xe Không Text 1,255 COUPE
barrelType Loại thùng (xe tải) Không Text 1,255 Thùng Mui Bạt
carGearBox Hộp số Không Text 1,255 AT
engineDisplacement Dung tích động cơ Không Text 1,255 3
carWheelDrive Dẫn động Không Text 1,255 FWD
payload Tải trọng Không Text 1,255 30000
vehicleCategory Phân loại xe Có Text 1,255 car

Ví dụ Response Thành công

{
    "count": 8311,
    "limit": 5,
    "offset": 0,
    "records": [
        {
            "codebookKey": "acura-cl-3.0-at-nk",
            "carCompanyName": "ACURA",
            "carModelName": "CL",
            "carVersionName": "3.0 AT",
            "availableYears": [
                1997
            ],
            "originName": "NK",
            "fuel": "Xăng",
            "numOfSeat": 4,
            "carType": "COUPE",
            "barrelType": null,
            "carGearBox": "AT",
            "engineDisplacement": "3",
            "carWheelDrive": "FWD",
            "payload": null,
            "vehicleCategory": "car"
        }
    ]
}

2. Trường hợp Lỗi

Các mã HTTP Status Code

HTTP Status Code Mô tả
400 Lỗi dữ liệu đầu vào (Ví dụ: Thiếu tham số bắt buộc, sai định dạng)
401 Lỗi xác thực (Ví dụ: Token không hợp lệ hoặc đã hết hạn)
403 Lỗi không có quyền truy cập
500 Lỗi hệ thống từ server

Chi tiết Response Body (Lỗi)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
message Thông báo lỗi Có Text Error message description
name Tên mã lỗi (nếu có) Không Text BadRequestError
status Mã HTTP code tương ứng Có Number 400

Ví dụ Response Lỗi

{
    "message": "Error message description",
    "name": "BadRequestError",
    "status": 400
}

2.14: API Định giá xe v4 (Định giá mọi loại xe)

a. Thông tin Request

Method POST
API Url https://api.aicycle.ai/insurance/valuation/v4/valuate
API Headers { "Authorization": "Bearer $$API_KEY$$" }

Chi tiết Body (JSON)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carVersionId UUID (xe con) hoặc text ID (xe tải, chuyên dụng) Tuỳ chọn Text 5fe73296-de1b…
codebookKey Mã codebook của phiên bản xe Tuỳ chọn Text toyota-vios-1-5g
carCompanyName Tên hãng xe Bắt buộc nếu không có ID/Key Text 1,255 ACURA
carModelName Tên dòng xe Bắt buộc nếu không có ID/Key Text 1,255 CL
carVersionName Tên phiên bản Bắt buộc nếu không có ID/Key Text 1,255 3.0 AT
year Năm sản xuất Có Number 1,9999 1997
vehicleCategory Phân loại xe (car, truck, specialized, coach) Có Text 1,255 car

Ví dụ Request

curl --location 'https://api.aicycle.ai/insurance/valuation/v4/valuate' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "carCompanyName": "ACURA",
    "carModelName": "CL",
    "carVersionName": "3.0 AT",
    "year": 1997,
    "vehicleCategory": "car"
}'

b. Thông tin Response

1. Trường hợp Thành công (HTTP 200)

Chi tiết Response Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompanyName Hãng xe Có Text 1,255 ACURA
carModelName Dòng xe Có Text 1,255 CL
carVersionName Phiên bản xe Có Text 1,255 3.0 AT
year Năm sản xuất Có Number 1,9999 1997
vehicleCategory Loại xe Có Text 1,255 car
carOriginName Nơi sản xuất Không Text 1,255 Lắp ráp trong nước
carFuelName Nhiên liệu Không Text 1,255 Xăng
numOfSeat Số chỗ ngồi Không Number 1,9999 4
barrelType Loại thùng (Không trả về cho xe con/khách) Không Text 1,255 Thùng kín
payload Tải trọng (Không trả về cho xe con) Không Text 1,255 7500
price Giá trị xe ước tính hiện tại Có Number 1,999999999 164800000
minPrice Giá trị định giá thấp nhất Có Number 1,999999999 156500000
maxPrice Giá trị định giá cao nhất Có Number 1,999999999 173000000
listedPrice Giá niêm yết Không Number 1,999999999
minListedPrice Giá niêm yết thấp nhất Không Number 1,999999999
maxListedPrice Giá niêm yết cao nhất Không Number 1,999999999
hanoiOnRoadPrice Giá lăn bánh tại Hà Nội Không Number 1,999999999
generalOnRoadPrice Giá lăn bánh tỉnh Không Number 1,999999999
hcmOnRoadPrice Giá lăn bánh tại TP HCM Không Number 1,999999999
mappingId ID mapping Không Text
sessionId Session ID Có Number 219

Ví dụ Response Thành công (Xe Con - car)

{
    "carCompanyName": "ACURA",
    "carModelName": "CL",
    "carVersionName": "3.0 AT",
    "year": 1997,
    "vehicleCategory": "car",
    "carOriginName": "Nhập khẩu",
    "carFuelName": "Xăng",
    "numOfSeat": 4,
    "carType": "Sedan",
    "price": 164800000,
    "minPrice": 156500000,
    "maxPrice": 173000000,
    "listedPrice": null,
    "minListedPrice": null,
    "maxListedPrice": null,
    "hanoiOnRoadPrice": null,
    "generalOnRoadPrice": null,
    "hcmOnRoadPrice": null,
    "mappingId": null,
    "sessionId": 219
}

Ví dụ Response Thành công (Xe Tải - truck)

{
    "carCompanyName": "DOOSUNG",
    "carModelName": "DV-DSKS-230 FCJ",
    "carVersionName": "SOMI ROMOOC TẢI BEN 3 TRỤC XILANH HYVA FC202 28.314 TẤN",
    "year": 2022,
    "vehicleCategory": "truck",
    "carOriginName": null,
    "carFuelName": null,
    "numOfSeat": null,
    "carType": "Sơ mi rơ moóc tải (tự đổ)",
    "barrelType": "Thùng ben",
    "payload": "28314 kg",
    "price": 445700000,
    "minPrice": 423400000,
    "maxPrice": 468000000,
    "listedPrice": null,
    "minListedPrice": null,
    "maxListedPrice": null,
    "hanoiOnRoadPrice": null,
    "generalOnRoadPrice": null,
    "hcmOnRoadPrice": null,
    "mappingId": null,
    "sessionId": 436
}

Ví dụ Response Thành công (Xe Khách - coach)

{
    "carCompanyName": "HYUNDAI",
    "carModelName": "COUNTY",
    "carVersionName": "29 CHỖ",
    "year": 2020,
    "vehicleCategory": "coach",
    "carOriginName": "Lắp ráp trong nước",
    "carFuelName": "Diesel",
    "numOfSeat": 29,
    "carType": "Xe khách",
    "payload": null,
    "price": 1150000000,
    "minPrice": 1100000000,
    "maxPrice": 1200000000,
    "listedPrice": null,
    "minListedPrice": null,
    "maxListedPrice": null,
    "hanoiOnRoadPrice": null,
    "generalOnRoadPrice": null,
    "hcmOnRoadPrice": null,
    "mappingId": null,
    "sessionId": 501
}

2. Trường hợp Lỗi

Các mã HTTP Status Code

HTTP Status Code Mô tả
400 Lỗi dữ liệu đầu vào (Ví dụ: Thiếu tham số bắt buộc, sai định dạng)
401 Lỗi xác thực (Ví dụ: Token không hợp lệ hoặc đã hết hạn)
403 Lỗi không có quyền truy cập
500 Lỗi hệ thống từ server

Chi tiết Response Body (Lỗi)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
message Thông báo lỗi Có Text Error message description
name Tên mã lỗi (nếu có) Không Text BadRequestError
status Mã HTTP code tương ứng Có Number 400

Ví dụ Response Lỗi

{
    "message": "Error message description",
    "name": "BadRequestError",
    "status": 400
}

2.15 API Tạo yêu cầu duyệt mã xe Codebook (POST)

API này cho phép đối tác tải lên thông tin xe (hoặc hình ảnh đăng ký/đăng kiểm) để tạo mới hoặc yêu cầu hệ thống định danh một dòng xe chưa có trong cơ sở dữ liệu. API xử lý theo cơ chế bất đồng bộ (Polling).

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/api/v2/codebook-requests
API Headers { "Authorization": "Bearer $$API_KEY$$" }
Content-Type multipart/form-data

b. Chi tiết đầu vào

Loại đầu vào: Form-Data

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/api/v2/codebook-requests' \
--header 'Authorization: Bearer <API Key>' \
--form 'images=@"giay_to_xe.jpg"' \
--form 'carCompanyName="TOYOTA"' \
--form 'carModelName="VIOS"' \
--form 'carVersionName="1.5G"' \
--form 'vehicleTypeKey="car"' \
--form 'numOfSeat="5"'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Ví dụ
images Tối đa 5 file ảnh (đăng ký/đăng kiểm) Bắt buộc (nếu không truyền đủ 3 thông tin Hãng, Dòng, Phiên bản) File file1.jpg
carCompanyName Hãng xe Bắt buộc (nếu không có ảnh) Text TOYOTA
carModelName Mẫu xe Bắt buộc (nếu không có ảnh) Text VIOS
carVersionName Phiên bản xe Bắt buộc (nếu không có ảnh) Text 1.5G CVT
vehicleTypeKey Loại xe (car, truck, specialized…) Tùy chọn Text car
numOfSeat Số chỗ ngồi Tùy chọn Number 5
engineCapacity Dung tích động cơ Tùy chọn Number 1.5
carType Kiểu dáng (Sedan, SUV…) Tùy chọn Text Sedan
carGearBox Hộp số (AT, MT) Tùy chọn Text AT
carFuel Nhiên liệu (Xăng, Dầu…) Tùy chọn Text Xăng
carWheelDrive Dẫn động (FWD, AWD…) Tùy chọn Text FWD
truckBarrelTypeKey Loại thùng xe (Dành cho xe tải) Tùy chọn Text thung_kin
price Giá xe Tùy chọn Number 600000000

c. Chi tiết đầu ra

Vì xử lý bất đồng bộ, API sẽ phản hồi ngay một codebookRequestId để bạn có thể gọi vào API Trạng thái (GET) để kiểm tra.

HTTP Status Code Mô tả
201 Khởi tạo thành công tiến trình ngầm
400 Dữ liệu đầu vào không hợp lệ
401 Lỗi xác thực
{
    "codebookRequestId": "a1b2c3d4-e5f6-7a8b-9c0d-1234567890ab",
    "status": "PROCESSING",
    "message": "Your request is being processed. Please check back later."
}

2.16 API Lấy trạng thái duyệt mã xe Codebook (GET)

Đối tác sử dụng codebookRequestId trả về từ API POST để tra cứu (polling) trạng thái xử lý định danh xe.

a. Thông tin cơ bản

Method GET
API Url https://api.aicycle.ai/insurance/api/v2/codebook-requests/{codebookRequestId}/status
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Path Variable

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/api/v2/codebook-requests/a1b2c3d4-e5f6-7a8b-9c0d-1234567890ab/status' \
--header 'Authorization: Bearer <API Key>'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Ví dụ
codebookRequestId Mã request ID nhận được ở bước POST Bắt buộc Text a1b2c3d4-...

c. Chi tiết đầu ra

HTTP Status Code Mô tả
200 Lấy trạng thái thành công
400 Request ID không hợp lệ

Trạng thái ban đầu đang được xử lý (PROCESSING hoặc PENDING):

{
    "codebookRequestId": "a1b2c3d4-e5f6-7a8b-9c0d-1234567890ab",
    "status": "PENDING",
    "reason": null,
    "codebookData": null,
    "createdDate": "17/09/2026 10:42:59",
    "updatedDate": "17/09/2026 10:42:59"
}

Trạng thái xử lý hoàn tất (LINKED_TO_EXISTING hoặc APPROVED):

{
    "codebookRequestId": "a1b2c3d4-e5f6-7a8b-9c0d-1234567890ab",
    "status": "LINKED_TO_EXISTING",
    "reason": null,
    "codebookData": {
        "carCompanyName": "TOYOTA",
        "carCompanyCode": "TOYOTA",
        "carModelName": "VIOS",
        "carModelCode": "VIOS",
        "carVersionName": "1.5G CVT",
        "carVersionCode": "1.5G CVT",
        "codebookKey": "toyota-vios-1.5g-cvt",
        "carVersionId": "b18b48f9-5fbe-47d3-9bc4-3b2d1847e3a2",
        "engineCapacity": 1.5,
        "numOfSeat": 5,
        "carWheelDrive": "FWD",
        "carGearBox": "AT",
        "carFuel": "Xăng",
        "vehicleCategory": "car",
        "carType": "Sedan",
        "origin": "LRTN",
        "truckBarrelType": null,
        "payload": null
    },
    "createdDate": "17/09/2026 10:42:59",
    "updatedDate": "17/09/2026 10:43:05"
}

2.17 API Lấy danh sách loại xe (GET)

Đối tác sử dụng API này để đồng bộ danh sách các loại xe trong hệ thống, kèm theo thông tin về nhóm xe tương ứng.

a. Thông tin cơ bản

Method GET
API Url https://api.aicycle.ai/insurance/api/v1/car-types
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Query Parameters

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/api/v1/car-types?limit=100&offset=0&vehicleCategory=car' \
--header 'Authorization: Bearer <API Key>'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Ví dụ
limit Số lượng bản ghi tối đa (mặc định 30, tối đa 100) Không Number 100
offset Số bản ghi bỏ qua (mặc định 0) Không Number 0
vehicleCategory Mã nhóm xe (ví dụ: car, truck) Không Text car
carType Tên loại xe Không Text Xe Oto

c. Chi tiết đầu ra

HTTP Status Code Mô tả
200 Lấy danh sách thành công
500 Lỗi hệ thống
{
    "count": 79,
    "limit": 100,
    "offset": 0,
    "records": [
        {
            "carTypeId": 708,
            "carTypeName": "Ô tô tưới nhựa đường",
            "carTypeKey": "o-to-tuoi-nhua-duong",
            "isActive": true,
            "vehicleCategory": {
                "key": "specialized",
                "name": "Xe chuyên dụng"
            }
        }
    ]
}

2.18 API Upload giấy tờ đăng kiểm, đăng ký xe (POST)

API này cho phép đối tác tải lên hình ảnh giấy tờ xe (đăng ký, đăng kiểm…) để hệ thống AI tự động bóc tách thông tin và định giá xe.

a. Thông tin Request

Method POST
API Url https://api.aicycle.ai/insurance/valuation/ocr/upload
API Headers { "Authorization": "Bearer $$API_KEY$$" }
Content-Type multipart/form-data

Chi tiết Body (FormData)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
img File ảnh giấy tờ xe (đăng ký / đăng kiểm). Cho phép tải lên tối đa 2 file (mặt trước & mặt sau). Bắt buộc File 1,2 dang_kiem.jpg
vehicleType Phân loại nhóm xe: car, truck, specialized, coach Tùy chọn Text 1,255 car
enableFallback Bật/tắt chế độ định giá dự phòng AI Fallback nếu OCR không đủ độ tin cậy (mặc định true) Tùy chọn Boolean true

Ví dụ Request

curl --location 'https://stage.api.aicycle.ai/insurance/valuation/ocr/upload' \
--header 'Authorization: Bearer <API Key>' \
--header 'Cookie: stage-aicycle-session-id=<Session ID>' \
--form 'img=@"/path/to/dang_kiem_mat_truoc.jpg"' \
--form 'img=@"/path/to/dang_kiem_mat_sau.jpg"' \
--form 'vehicleType="car"' \
--form 'enableFallback="true"'

b. Thông tin Response

1. Trường hợp Khởi tạo AI Fallback thành công (HTTP 202)

Khi dữ liệu cần phân tích thêm hoặc độ tin cậy thấp hơn ngưỡng, hệ thống chuyển sang xử lý ngầm (Accepted).

Chi tiết Response Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Ví dụ
code Mã HTTP status phản hồi Có Number 202
message Thông báo trạng thái xử lý Có Text Processing via AI Fallback
meta Thông tin đối tượng tác vụ ngầm Có Object
meta.jobId Mã ID tác vụ định danh (UUID) dùng để tra cứu trạng thái ở API polling Có Text 0c9c9bb6-45e1-42b7-a743-0f8686f9a463
meta.status Trạng thái ban đầu của tác vụ (PENDING) Có Text PENDING

Ví dụ Response Khởi tạo Fallback (HTTP 202)

{
    "code": 202,
    "message": "Processing via AI Fallback",
    "meta": {
        "jobId": "0c9c9bb6-45e1-42b7-a743-0f8686f9a463",
        "status": "PENDING"
    }
}

2. Trường hợp Bóc tách OCR & Khớp Codebook trực tiếp (HTTP 200)

Khi ảnh rõ nét và hệ thống tự tin cao, thông tin xe và gợi ý phiên bản Codebook được phản hồi đồng bộ ngay lập tức (cấu trúc chi tiết tương tự mục 2.9).

3. Trường hợp Lỗi

Các mã HTTP Status Code

HTTP Status Code Mô tả
400 Dữ liệu đầu vào không hợp lệ (ví dụ: vehicleType không đúng hoặc thiếu file)
401 Lỗi xác thực hoặc không có quyền truy cập (valueMe:access)
500 Lỗi hệ thống từ server

Chi tiết Response Body (Lỗi)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Ví dụ
message Thông báo lỗi chi tiết Có Text Invalid vehicleType
name Tên mã lỗi Không Text BadRequestError
status Mã HTTP code Có Number 400

Ví dụ Response Lỗi

{
    "message": "Invalid vehicleType",
    "name": "BadRequestError",
    "status": 400
}

2.19 API Lấy trạng thái bóc tách & định giá xe từ giấy tờ (GET)

Đối tác sử dụng jobId nhận được từ API Upload giấy tờ (2.18) để tra cứu (polling) trạng thái bóc tách OCR và định giá xe tự động.

a. Thông tin Request

Method GET
API Url https://api.aicycle.ai/insurance/valuation/fallback/status/{jobId}
API Headers { "Authorization": "Bearer $$API_KEY$$" }

Chi tiết Path Variable

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Ví dụ
jobId Mã ID tác vụ nhận được từ API Upload giấy tờ Bắt buộc Text 0c9c9bb6-45e1-42b7-a743-0f8686f9a463

Ví dụ Request

curl --location 'https://stage.api.aicycle.ai/insurance/valuation/fallback/status/0c9c9bb6-45e1-42b7-a743-0f8686f9a463' \
--header 'Authorization: Bearer <API Key>' \
--header 'Cookie: stage-aicycle-session-id=<Session ID>'

b. Thông tin Response

1. Trường hợp Thành công (HTTP 200)

Xử lý hoàn tất thành công (fallbackStatus === 'SUCCESS'), hệ thống phản hồi đầy đủ thông tin phương tiện đã được bóc tách và các mức giá thẩm định tương ứng.

Chi tiết Response Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Ví dụ
vehicleTypeKey Khóa phân loại phương tiện (car, truck…) Có Text car
vehicleType Phân loại phương tiện Có Text car
carCompany / companyName Tên hãng xe Có Text TOYOTA
carModel / modelCode Tên mẫu xe / mã mẫu xe Có Text COROLLA
carVersion / versionName Tên phiên bản xe Có Text LE 1.8 AT
year / manufactureYear Năm sản xuất của phương tiện Có Number 2003
listedPrice Giá niêm yết tham chiếu Không Number 152085568
minListedPrice Giá niêm yết tối thiểu Không Number 144481290
maxListedPrice Giá niêm yết tối đa Không Number 174898403
carValue Giá trị định giá ước tính của xe Có Number 218000000
minPrice Giá trị định giá cận dưới (thấp nhất) Có Number 200000000
maxPrice Giá trị định giá cận trên (cao nhất) Có Number 236000000
newCarPrice Giá xe mới tham chiếu Không Number 152085568
numOfSeat Số chỗ ngồi Không Number 5
carFuelName Loại nhiên liệu (Xăng, Dầu…) Không Text Xăng
carOriginName Xuất xứ (Lắp ráp trong nước, Nhập khẩu…) Không Text Nhập khẩu
barrelTypeKey / barrelType / barrelTypeName Loại thùng xe (đối với xe tải) Không Text chassis
carType / carTypeName Chủng loại xe chi tiết (Ô tô con, Ô tô đầu kéo…) Không Text Ô tô đầu kéo
numberOfBoards Số bửng (đối với xe tải thùng) Không Number 5
isAiGenerated Cờ xác định dữ liệu được AI bóc tách & định danh tự động Có Boolean true
fallbackJobId Mã jobId tương ứng của tác vụ Có Text 0c9c9bb6-45e1-42b7-a743-0f8686f9a463
fallbackStatus Trạng thái hoàn tất của AI Fallback (SUCCESS, FAILED) Có Text SUCCESS

Ví dụ Response Thành công (Xe con - car)

{
    "vehicleTypeKey": "car",
    "vehicleType": "car",
    "carCompany": "TOYOTA",
    "carModel": "COROLLA",
    "carVersion": "LE 1.8 AT",
    "year": 2003,
    "listedPrice": 152085568,
    "minListedPrice": 144481290,
    "maxListedPrice": 174898403,
    "carFuelName": null,
    "numOfSeat": 5,
    "carOriginName": null,
    "isAiGenerated": true,
    "carValue": 218000000,
    "maxPrice": 236000000,
    "minPrice": 200000000,
    "newCarPrice": 152085568,
    "fallbackJobId": "0c9c9bb6-45e1-42b7-a743-0f8686f9a463",
    "fallbackStatus": "SUCCESS"
}

Ví dụ Response Thành công (Xe tải / Xe chuyên dụng / Xe khách - truck/specialized/coach)

{
    "vehicleTypeKey": "truck",
    "companyName": "CHENGLONG",
    "versionName": "H7 385HP 6X4 CẦU LÁP",
    "modelCode": "LZ4256H7DB (CẦU LÁP)",
    "carCompany": "CHENGLONG",
    "carModel": "LZ4256H7DB (CẦU LÁP)",
    "carVersion": "H7 385HP 6X4 CẦU LÁP",
    "manufactureYear": 2025,
    "barrelTypeKey": "chassis",
    "barrelType": "Chassis",
    "barrelTypeName": "Chassis",
    "carType": null,
    "carTypeName": "Ô tô đầu kéo",
    "numOfSeat": null,
    "numberOfBoards": null,
    "vehicleType": "truck",
    "sessionId": null,
    "isAiGenerated": true,
    "carValue": 705600000,
    "maxPrice": 832600000,
    "minPrice": 656200000,
    "newCarPrice": 720000000,
    "fallbackJobId": "8736d302-6d6e-49a6-9ee4-2e5a04765849",
    "fallbackStatus": "SUCCESS"
}

2. Trường hợp Đang xử lý (HTTP 202)

Khi tác vụ đang trong hàng đợi (PENDING) hoặc AI đang bóc tách phân tích (PROCESSING).

Chi tiết Response Body (Đang xử lý)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Ví dụ
code Mã HTTP status phản hồi Có Number 202
message Thông báo trạng thái xử lý Có Text Processing via AI Fallback
meta Thông tin đối tượng tác vụ Có Object
meta.jobId Mã ID tác vụ Có Text 0c9c9bb6-45e1-42b7-a743-0f8686f9a463
meta.status Trạng thái hiện tại (PENDING hoặc PROCESSING) Có Text PROCESSING

Ví dụ Response Đang xử lý (HTTP 202)

{
    "code": 202,
    "message": "Processing via AI Fallback",
    "meta": {
        "jobId": "0c9c9bb6-45e1-42b7-a743-0f8686f9a463",
        "status": "PROCESSING"
    }
}

3. Trường hợp Lỗi

Các mã HTTP Status Code

HTTP Status Code Mô tả
400 jobId không hợp lệ hoặc dữ liệu xe sau bóc tách không hợp lệ (isValidVehicle: false)
401 Lỗi xác thực hoặc không có quyền truy cập (valueMe:access)
404 Không tìm thấy tác vụ với jobId tương ứng (Job not found)
500 Lỗi hệ thống từ server

Chi tiết Response Body (Lỗi)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Ví dụ
message Thông báo lỗi chi tiết Có Text Dữ liệu xe không hợp lệ

Ví dụ Response Lỗi

{
    "message": "Dữ liệu xe không hợp lệ"
}

3. APIs tích hợp BuyMe/ClaimMe

3.1: Flow diagram tích hợp cho BuyMe realtime

Alt text

3.2: Tạo mới hồ sơ (claimFolder)

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/claimfolders
API Headers { "Authorization": "Bearer $$apiKey$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Ví dụ

curl --location --request POST 'https://api.aicycle.ai/insurance/claimfolders' \
--header 'authorization: Bearer $$apiKey$$' \
--header 'Content-Type: application/json' \
--data-raw '{
    "claimName":"34AAAAA",
    "vehicleBrandName": "mazda",
    "vehicleModel": "mazda.3_sedan",
    "vehicleSpec": "luxury_1_5l_at",
    "vehicleLicensePlates": "30H84142"
}'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
claimName Mã hồ sơ của đối tác Bắt buộc Text 1,255 Folder-1
vehicleBrandName Tên hãng xe của hồ sơ Text 1,255 mazda
vehicleModel Tên hiệu xe của hồ sơ Text 1,255 mazda.3_sedan
vehicleSpec Tên phiên bản xe của hồ sơ Text 1,255 luxury_1_5l_at
vehicleLicensePlates Biển số xe của hồ sơ Text 1,255 30H84142

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
claimId Id của claim folder Bắt buộc Text 1,255 123

d. Ví dụ đầu ra

{
    "status": "success",
    "msg": "Create claim folder success",
    "data": [
        {
            "claimId": "189",
            "claimName": "34AAAAA",
            "vehicleBrandName": "Toyota Vios"
        }
    ]
}





a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/images/url
API Headers { "Authorization": "Bearer $$apiKey$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Ví dụ

curl --location --request POST 'https://api.aicycle.ai/insurance/images/url' \
--header 'Authorization: Bearer $$API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "filePaths": ['INSURANCE_CLAIM/image-1.jpg', 'INSURANCE_CLAIM/image-2.jpg']
}'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
filePaths Đường dẫn file trên S3 Optional Array[Text] 1,100 [“INSURANCE_CLAIM/image-1.jpg”, “INSURANCE_CLAIM/image-2.jpg”]

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
urls[] Array Urls upload và lấy image trên s3 Bắt buộc Object 1,255 INSURANCE_CLAIM/image-1.jpg
urls[n].fetchUrl Url lấy ảnh Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_CLAIM/image-1.jpg
urls[n].uploadUrl Url upload ảnh Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_CLAIM/image-1.jpg
urls[n].filePath filePath dùng để call engine Bắt buộc Text 1,255 INSURANCE/image-1.jpg

d. Ví dụ đầu ra

{
    "urls": [
        {
            "fetchUrl": "https://dyta7vmv7sqle.cloudfront.net/INSURANCE_CLAIM/quang-6.jpg",
            "uploadUrl": "https://dyta7vmv7sqle.cloudfront.net/INSURANCE_CLAIM/quang-6.jpg",
            “filePath": “INSURANCE/image-1.jpg”
        },
        {
            "fetchUrl": "https://dyta7vmv7sqle.cloudfront.net/INSURANCE_CLAIM/quang-6.jpg",
            "uploadUrl": "https://dyta7vmv7sqle.cloudfront.net/INSURANCE_CLAIM/quang-6.jpg",
            “filePath": “INSURANCE/image-2.jpg”
        }
    ],
    "msg": "Get url image success",
    "status": "success"
}








Sau khi call api lấy link uploadUrl để up ảnh. Trên postman dùng link đó với method là PUT, body dạng binary và select file ảnh trên máy để upload. Khi nhận được status là 200 (upload thành công), dùng đường link fetchUrl đó paste lên browser để xem kết quả

3.4: API Call Engine AICycle BuyMe V2 (new version)

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/v2/buy-me/process
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
claimId Id của Hồ sơ Bắt buộc Number 1,999999 123
imageName Tên ảnh Bắt buộc Text 1,255 INSURANCE_CLAIM/image-1.jpg
filePath Path ảnh trên s3 (lấy từ kết quả trả về của API get imageUrl ở mục 3.3) Bắt buộc Text 1,255 INSURANCE_CLAIM/image-1.jpg
position Slug Loại ảnh (Toàn cảnh, trung cảnh, cận cảnh) Bắt buộc Text 1,255 toan-canh-afh4l5
direction Slug Hướng ảnh Bắt buộc Text 1,255 45-trai-truoc-C1xM02
oldImageId Id ảnh cũ muốn xóa Optional Number 1,9999 3
vehicleType Loại xe muốn engine detect (xe tải, xe con) Optional ENUM(truck, car) 1,255 truck

Lưu ý

Các giá trị của position

positionName positionSlug
Toàn cảnh toan-canh-afh4l5
Trung cảnh trung-canh-0s8mnb
Cận cảnh can-canh-czu5jp

Các giá trị của direction

Ví dụ

curl --location --request POST 'https://api.aicycle.ai/insurance/v2/buy-me/process' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--data-raw '{
   "claimId": 1,
   "imageName": "INSURANCE/1666145614576/1666145614447.jpg",
   "filePath": "INSURANCE/1666145614576/1666145614447.jpg",
   "position": "toan-canh-afh4l5",
   "direction": "45-trai-truoc-C1xM02",
    “oldImageId": 123
}'
directionName directionSlug
Trước truoc-sT9qgX
45° Phải - Trước 45-phai-truoc-UoYzs6
45° Trái - Trước 45-trai-truoc-C1xM02
Sau sau-htBwjB
45° Phải - Sau 45-phai-sau-fRzY3r
45° Trái - Sau 45-trai-sau-1q3G3J
Phải - Trước phai-truoc-eYWg1d
Trái - Trước trai-truoc-r6BEZd
Phải - Sau phai-sau-v1hAm6
Trái - Sau trai-sau-t8QgFO

c. Chi tiết đầu ra

{
    "status": <Trạng trái (String)>,
    "isPhotoValid": <Ảnh có hợp lệ hay không (Boolean)>,
    "traceId": <ID dùng để giải quyết khi liên hệ AICycle (UUID)>,
    "errorCodeFromEngine": <ErrorCode (Number)>,
    "message": <String>,
    "imageId": <ID của ảnh (Number)>,
    "result": [<Image>]
}








Chi tiết Object item Image

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
imgSize Kích thước ảnh Bắt buộc Array[number] n [1920, 1080]
imgUrl Link ảnh gốc Bắt buộc Text 1,255 {{s3Link}}
errorCodeFromEngine Mã lỗi ảnh Bắt buộc Number 1,999999 0
message Chi tiết lỗi ảnh Bắt buộc Text 1,255 Ảnh chụp qua màn hình
damages Các hỏng hóc của ảnh Bắt buộc Array[damage] n
carParts Các bộ phận của ảnh Bắt buộc Array[carPart] n

Chi tiết Object item carPart

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carPartKey Mã bộ phận Bắt buộc Text 1,255 den-gam-truoc-trai-d7WevY
position Vị trí bộ phận Bắt buộc Text 1,255 Trái - Trước
name Tên bộ phận Bắt buộc Text 1,255 Đèn gầm trước trái
maskUrl Url mask bộ phận Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_RESULT/EGfDHztL2Vffgc72cM1DG.png

Chi tiết Object item damage

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
name Tên hỏng hóc Bắt buộc Text 1,255 Trầy (xước)
maskUrl mask hỏng hóc Bắt buộc Text 1,255 …

Chi tiết Object item extraInfo

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
plateNumber Biển số xe Bắt buộc Text 1,255 30A 9999
carCompany Hãng xe Bắt buộc Text 1,255 TOYOTA
carModel Hiệu xe Bắt buộc Text 1,255 Vios
carColor Hiệu xe Bắt buộc [Number] 1,999999 [220,219,215]
imagePosition Slug loại ảnh Bắt buộc Text 1,255 trung-canh-0s8mnb
imageDirection Slug góc chụp Bắt buộc Text 1,255 trai-truoc-r6BEZd

Chi tiết Bảng Mã lỗi cùng httpStatus trả về của errorCodeFromEngine

Chú thích Với những lỗi có level là error sẽ chỉ trả ra mã lỗi và message lỗi, những lỗi level warning sẽ trả ra mã lỗi, message, và car_part, car_damages như bình thường

Mã lỗi HTTP Status Response body Level lỗi
0 200 Ảnh hợp lệ
37143 400 {"errorCodeFromEngine": 37143, "message": "Không thể nhận diện ô tô trong ảnh. Vui lòng chụp lại"} Error
40412 400 {"errorCodeFromEngine": 40412, "message": "Ảnh chụp bị mờ. Vui lòng chụp lại"} Error
32324 400 {"errorCodeFromEngine": 32324, "message": "Không download được ảnh"} Error
23212 200 {"errorCodeFromEngine": 23212, "message": "Ảnh chụp bị tối"} Warning
84680 400 {"errorCodeFromEngine": 84680, "message": "Ảnh chụp qua màn hình. Vui lòng chụp lại"} Error
47565 400 {"errorCodeFromEngine": 47565, "message": "Trả ra error của engine"} Error
67219 400 {"errorCodeFromEngine": 67219, "message": "Không thể nhận diện ô tô trong ảnh. Vui lòng chụp lại"} Error
77704 200 {"errorCodeFromEngine": 77704, "message": "Ảnh chụp bị lóa"} Warning
50676 400 {"errorCodeFromEngine": 50676, "message": "Ảnh không đúng góc chụp. Vui lòng chụp lại"} Error
378224 400 {"errorCodeFromEngine": 378224, "message": "Ảnh không phải xe tải"} Error
178434 400 {"errorCodeFromEngine": 178434, "message": "Ảnh không phải xe con"} Error

d. Ví dụ đầu ra

{
    "status": "success",
    "isPhotoValid": true,
    "traceId": "80540cf80585486f63432dcdf680fd20",
    "errorCodeFromEngine": 0,
    "message": "",
    "imageId": 4808,
    "result": [
        {
            "imgSize": [1920, 1080],
            "extraInfor": {
                "plateNumber": "",
                "chassisNumber": null,
                "carCompany": "",
                "carModel": "",
                "carColor": [222, 220,216],
                "imagePosition": "trung-canh-0s8mnb",
                "imageDirection": "trai-truoc-r6BEZd"
            },
            "damages": [
                {
                    "name": "Móp, bẹp(thụng)",
                    "damageKey": "mop-bep-jtep4m",
                    "location": "",
                    "score": 1,
                    "box": [ 0.34, 0.14, 0.79,0.77],
                    "maskPath": "nfU_HFiSOi4wEkP1ycUwv.png",
                    "isPart": false,
                    "maskUrl": "{{s3Url}}"
                },
                ...
            ],
            "carParts": [
                {
                    "name": "Trụ kính cánh cửa",
                    "carPartKey": "khung-kinh-canh-cua-truoc-trai-KMtJpH",
                    "position": "Trái - Trước",
                    "score": 0.83660888671875,
                    "box": [
                        0.81875,
                        0,
                        0.9994791666666667,
                        0.2
                    ],
                    "maskPath": "vG4wVxBeWvLF5MFGMAfq9.png",
                    "isPart": true,
                    "damages": [
                        {
                            "name": "Trầy, xước",
                            "damageKey": "yfMzer07THdYoCI1SM2LN",
    
                            "score": 1,
                            "box": [
                                0.2171875,
                                0.07685185185185185,
                                0.9989583333333333,
                                0.9425925925925925
                            ],
                            "maskPath": "favy1yqepBr_JM8tAJm2v.png",
                            "isPart": false,
                            "overlapRate": 0.00047147571877818216,
                            "maskUrl": "{{s3Url}}",
                        },
                        ...
                    ],
                },
                ...
            ]
        }
    ]
}




























3.5: API lấy kết quả Hồ sơ (nhóm theo bộ phận)

a. Thông tin cơ bản

Method GET
API Url https://api.aicycle.ai/insurance/claimfolders/claim-results/{claimId}
API Headers { "Authorization": "Bearer $$apiKey$$" }

b. Chi tiết đầu vào

Loại đầu vào: Params

Ví dụ

curl --location --request GET 'https://api.aicycle.ai/insurance/claimfolders/claim-results/2450' \
--header 'authorization: Bearer $$API_KEY$$' \
--data-raw ''
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
claimId Id của Hồ sơ Bắt buộc Number 1,999999 123

c. Chi tiết đầu ra

{
    "results": [<VehiclePart>],
    "summary": <Tổng số tiền thiệt hại theo VND (number)>
}



Chi tiết Object item VehiclePart

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehiclePartExcelId Mã bộ phận Bắt buộc Text 1,255 ba-do-soc-truoc-WUBZvD
vehiclePartName Tên bộ phận Bắt buộc Text 1,255 Ba đờ sốc trước
location Vị trí bộ phận Bắt buộc Text 1,255 Trước
damages Chi tiết hỏng hóc Bắt buộc Array[damage] n []
images Ảnh Bắt buộc Array[image] n []

Chi tiết Object item damage

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
damageTypeName Tên hỏng hóc Bắt buộc Text 1,255 Trầy (xước)
damagePercentage Phần trăm hỏng hóc Bắt buộc Number 0,1 0.05
damageArea Diện tích hỏng hóc Bắt buộc Number 0,1 0.05

Chi tiết Object item image

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
imageUrl Url ảnh Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_RESULT/EGfDHztL2Vffgc72cM1DG.png
imageRange Loại ảnh Bắt buộc Text 1,255 Toàn cảnh
location Nơi ảnh được chụp Bắt buộc TEXT 1,255 Duy Tân, Cầu Giấy, Hà Nội
requestedTime Thời gian chụp ảnh Bắt buộc TEXT 1,255 2023-03-24 03:28:29.414232 +00:00
uploadedTime Thời gian ảnh được upload lên hệ thống Bắt buộc TEXT 1,255 2023-03-24 03:28:29.414232 +00:00
uploadLocation Nơi upload ảnh để thực hiện claim Bắt buộc TEXT 1,255 Hai Bà Trưng, Hà Nội
damageMasks Chi tiết hỏng hóc của ảnh Bắt buộc Array[damageMask] n []

Chi tiết Object item damageMask

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
damageTypeName Loại hỏng hóc Bắt buộc Text 1,255 Trầy (xước)
maskUrl Url mask hỏng hóc Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_RESULT/EGfDHztL2Vffgc72cM1DG.png

d. Ví dụ đầu ra

{
    "result": [
        {
            "vehiclePartExcelId": "ba-do-soc-truoc-WUBZvD",
            "vehiclePartName": "Ba đờ sốc trước",
            "location": "Trước",
            "createdDate": "2022/10/24",
            "damages": [
                {
                    "damageTypeName": "Trầy (xước)",
                    "damagePercentage": 0.0419343353811561,
                    "damageArea": 0.419343353811561,
                    "damageTypeColor": "#FFEC05"
                }
            ],
            "images": [
                {
                    "imageId": 10579,
                    "filePath": "INSURANCE_CLAIM/1652252930377/image_picker7865199709592835107.jpg",
                    "imageUrl": "https://s3-sgn09.fptcloud.com/aicycle/INSURANCE_CLAIM/1652252930377/image_picker7865199709592835107.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=0080fa5f9d06c7ad85c7%2F20221024%2Fsgn09%2Fs3%2Faws4_request&X-Amz-Date=20221024T105823Z&X-Amz-Expires=7200&X-Amz-Signature=1e0ad191019668c5e77af28aa301f00f3d5f22a98882a1024660da2b9d946897&X-Amz-SignedHeaders=host",
                    "imageRange": "Toàn cảnh",
                    "damageExist": true,
                    "errorType": null,
                    "errorNote": null,
                    "location": "Duy Tân, Cầu Giấy, Hà Nội",
                    "requestedTime": "2023-03-24T03:28:29.414Z",
                    "uploadedTime": "2023-03-27T03:04:53.001Z",
                    "uploadLocation": "Quận Cầu Giấy, Hà Nội",
                    "timeProcess": 2.678,
                    "damageMasks": [
                        {
                            "maskPath": "8EskO3gPp1DYO00BOcBPq.png",
                            "maskUrl": "https://s3-sgn09.fptcloud.com/aicycle/INSURANCE_RESULT/8EskO3gPp1DYO00BOcBPq.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=0080fa5f9d06c7ad85c7%2F20221024%2Fsgn09%2Fs3%2Faws4_request&X-Amz-Date=20221024T105823Z&X-Amz-Expires=7200&X-Amz-Signature=d531e05207a16858319bf560331cb684e20e728abd84c516c4d2918d5139dbef&X-Amz-SignedHeaders=host",
                            "vehiclePartName": "Ba đờ sốc trước",
                            "damageTypeUuid": "yfMzer07THdYoCI1SM2LN",
                            "damageTypeName": "Trầy (xước)",
                            "damageTypeColor": "#FFEC05",
                            "boxes": [
                                0,
                                0,
                                1,
                                1
                            ],
                            "isPart": false,
                            "userCreated": false
                        }
                    ]
                }
            ],
            "price": 1000000,
            "laborCost": 0,
            "totalCost": 1000000,
            "area": 10,
            "repairPlan": "Sửa chữa"
        }
    ],
    "summary": 1000000
}
























3.6: API lấy kết quả Hồ sơ (nhóm theo ảnh)

a. Thông tin cơ bản

Method GET
API Url https://api.aicycle.ai/insurance/claimfolders/{claimId}/get-image-results
API Headers { "Authorization": "Bearer $$apiKey$$" }

b. Chi tiết đầu vào

Ví dụ

curl --location --request GET 'https://api.aicycle.ai/insurance/claimfolders/{claimId}/get-image-results' \
--header 'authorization: Bearer $$API_KEY$$' \
--data-raw ''

Loại đầu vào: Params

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
claimId Id của Hồ sơ Bắt buộc Number 1,999999 123

c. Chi tiết đầu ra

{
    "results": {
        images: [<Image>]
    }
}

Chi tiết Object item Image

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
url Link ảnh Bắt buộc Text 1,255 {{imgUrl}}
imageSize Kích thước ảnh Bắt buộc Array[number] n [1920,1080]
directionName Góc chụp Bắt buộc Text 1,255 Trước
imageRangeName Loại ảnh Bắt buộc Text 1,255 Toàn cảnh
location Nơi ảnh được chụp Bắt buộc TEXT 1,255 Duy Tân, Cầu Giấy, Hà Nội
requestedTime Thời gian chụp ảnh Bắt buộc TEXT 1,255 2023-03-24 03:28:29.414232 +00:00
uploadedTime Thời gian ảnh được upload lên hệ thống Bắt buộc TEXT 1,255 2023-03-24 03:28:29.414232 +00:00
uploadLocation Nơi upload ảnh để thực hiện claim Bắt buộc TEXT 1,255 Hai Bà Trưng, Hà Nội
damageInfo Chi tiết hỏng hóc Bắt buộc Array[damageInfo] n []

Chi tiết Object item damageInfo

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehiclePartName Tên bộ phận Bắt buộc TEXT 1,255 Ba đờ sốc trước
price Giá bộ phận Bắt buộc Number 1,9999 1000000
location Vị trí bộ phận Bắt buộc TEXT 1,255 Trước
damageDetail Chi tiết hỏng hóc của bộ phận Bắt buộc Array[damageDetail] n []

Chi tiết Object item damageDetail

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
url Link mask hỏng hóc Bắt buộc TEXT 1,255 {{maskUrl}}
damageTypeName Loại hỏng hóc Bắt buộc TEXT 1,255 Trầy (xước)
damagePercentage Phần trăm hỏng hóc Bắt buộc Number 1,9999 0.08

d. Ví dụ đầu ra

{
    "result": {
        "images": [
            {
                "imageId": 16532,
                "imageName": "1679373021917.jpg",
                "filePath": "INSURANCE/1679373021956/1679373021917.jpg",
                "url": "{{imageUrl}}",
                "imageSize": [
                    1920,
                    1080
                ],
                "directionName": "45° Trái - Sau",
                "imageRangeName": "Toàn cảnh",
                "timeProcess": 1.693,
                "timeAppUpload": 1.501,
                "requestedTime": "2023-03-24T03:28:29.414Z",
                "uploadedTime": "2023-03-27T03:04:53.001Z",
                "uploadLocation": "Quận Cầu Giấy, Hà Nội",
                "location": "Duy Tân, Cầu Giấy, Hà Nội",
                "errorType": null,
                "errorNote": null,
                "traceId": "265e70b629c05b353b1968693a4ca051",
                "damageInfo": [
                    {
                        "vehiclePartName": "Pa vô lê trái",
                        "vehiclePartExcelId": "pavole-trai-tEm7AB",
                        "price": 450000,
                        "laborCost": 0,
                        "totalCost": 450000,
                        "area": 70,
                        "location": "Trái",
                        "repairPlan": "Sửa chữa",
                        "damageDetail": [
                            {
                                "filePath": "fxVIBETAr_Buc1h6ngzC4.png",
                                "url": "{{maskUrl}}",
                                "damageTypeName": "Trầy (xước)",
                                "damageTypeColor": "#FFEC05",
                                "damageUuid": "yfMzer07THdYoCI1SM2LN",
                                "boxes": [
                                    0.3125,
                                    0.6731481481481482,
                                    0.32135416666666666,
                                    0.6953703703703704
                                ],
								"damageArea": 0.6255235966733421,
                                "damagePercentage": 0.008936051381047744
                            }
                        ]
                    }
                ]
            }
     ]
   }
 }       
























3.7: API kiểm tra các ảnh trong Hồ sơ

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/checkCar/{claimId}
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Params

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
claimId Id Hồ sơ Bắt buộc Number 1,999999 1111

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
state trạng thái của folder Bắt buộc Number 1,999999 1
message thông báo chi tiết về trạng thái của folder Bắt buộc Text 1,255 Các ảnh thuộc cùng một xe

d. Chi tiết các state

Loại đầu ra: Response body

state Mô tả
0 trạng thái mặc định, các ảnh thuộc cùng một xe
1 chỉ có 1 ảnh trong folder
2 có ít nhất 1 ảnh trong folder chụp không đúng góc
3 các ảnh trong folder thuộc cùng một xe
4 các ảnh trong folder không thuộc cùng một xe
5 không nhận diện được biển số nào trong folder
6 thư mục ảnh rỗng

e. Ví dụ đầu ra

{ state: 3, message: ‘Các ảnh cùng một xe’ }

f. Ví dụ curl

curl –location –request GET ‘https://api.aicycle.ai/insurance/checkCar/1111'
–header ‘Authorization: Bearer {API Key}’

3.8: API callback lưu kết quả từ khách hàng

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/claimfolders/{claimFolderId}/results-callback
API Headers { "Authorization": "Bearer $$apiKey$$" }

b. Chi tiết đầu vào

Loại đầu vào: Params

Ví dụ

curl --location --request POST 'https://api.aicycle.ai/insurance/claimfolders/52/results-callback' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--data-raw '{
  "carPlate": "30A 115.23",
  "carCompany": "HYUNDAI",
  "carModel": "i10",
  "damages": [
    {
      "damageId": '123',
      "damageType": "Trầy (Xước)",
      "damagePart": "Capo trước",
      "damageName": "Trầy Capo Trước"
    }
  ]
}'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
claimFolderId Id của Hồ sơ Bắt buộc Number 1,999999 123

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carPlate Biển số xe Optional TEXT 1,255 30E 64737
carCompany Hãng xe Optional TEXT 1,255 HYUNDAI
carModel Mẫu xe Optional TEXT 1,255 i10
damages Danh sách các hỏng hóc Optional Array[damage] n []

Chi tiết Object item damage

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
damageId ID hỏng hóc (định danh hỏng hóc ở hệ thống khách hàng) (nếu có) Optional TEXT 1,255 123
damageType Loại hỏng hóc (theo định nghĩa của khách hàng) (nếu có) Optional TEXT 1,255 Trầy (Xước)
damagePart Bộ phận ghi nhận hỏng hóc (theo định nghĩa của khách hàng) (nếu có) Optional TEXT 1,255 Capo trước
damageName Tên hỏng hóc được định nghĩa phía client (tùy chọn) Optional TEXT 1,255 Trầy (Xước) Capo Trước

c. Chi tiết đầu ra

Loại đầu ra:Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min, Max Ví dụ
claimId Tên folder claim Bắt buộc Number 1,999999 123
carPlate Biển số xe Bắt buộc TEXT 1,255 30E 64737
carCompany Hãng xe Bắt buộc TEXT 1,255 HYUNDAI
carModel Hiệu xe Bắt buộc TEXT 1,255 i10
damages Danh sách các hỏng hóc Bắt buộc Array[damage] n []
ownerOrganizationId Id tổ chức Bắt buộc Number 1,999999 1

Chi tiết Object item damage

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
damageId ID hỏng hóc Bắt buộc TEXT 1,255 123
damageType Loại hỏng hóc Bắt buộc TEXT 1,255 Trầy (Xước)
damagePart Bộ phận ghi nhận hỏng hóc Bắt buộc TEXT 1,255 Capo trước
damageName Tên hỏng hóc Bắt buộc TEXT 1,255 Trầy (Xước) Capo Trước

d. Ví dụ đầu ra

{
    "claimId": 123,
    "carPlate": "30A 11523",
    "carCompany": "HYUNDAI",
    "carModel": "i10",
    "damages": [
        {
            "damageId": 123,
            "damageType": "Trầy (Xước)",
            "damagePart": "Capo trước",
            "damageName": "Trầy Capo Trước"
        }
    ],
    "ownerOrganizationId": 2
}






3.9 APIs tích hợp Claim Me

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/v2/claim-me/process
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Ví Dụ

curl --location --request POST 'https://api.aicycle.ai/insurance/v2/claim-me/process' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--data-raw '{
   "claimId": 1,
   "imageName": "INSURANCE/1666145614576/1666145614447.jpg",
   "filePath": "INSURANCE/1666145614576/1666145614447.jpg",
   "position": "toan-canh-afh4l5",
   "direction": "45-trai-truoc-C1xM02",
    “oldImageId": 123
}'

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
claimId Id của folder Bắt buộc Number 1,999999 123
imageName Tên ảnh Bắt buộc Text 1,255 INSURANCE_CLAIM/image-1.jpg
filePath Path ảnh trên s3 (lấy từ kết quả trả về của API get imageUrl ở mục 3.3) Bắt buộc Text 1,255 INSURANCE_CLAIM/image-1.jpg
position Slug Loại ảnh (Toàn cảnh, trung cảnh, cận cảnh) Bắt buộc Text 1,255 toan-canh-afh4l5
direction Slug Hướng ảnh Bắt buộc Text 1,255 45-trai-truoc-C1xM02
oldImageId Id ảnh cũ muốn xóa Optional Number 1,9999 3
vehicleType Loại xe muốn engine detect (xe tải, xe con) Optional ENUM(truck, car) 1,255 truck

Lưu ý

Các giá trị của position

positionName positionSlug
Toàn cảnh toan-canh-afh4l5
Trung cảnh trung-canh-0s8mnb
Cận cảnh can-canh-czu5jp

Các giá trị của direction

directionName directionSlug
Trước truoc-sT9qgX
45° Phải - Trước 45-phai-truoc-UoYzs6
45° Trái - Trước 45-trai-truoc-C1xM02
Sau sau-htBwjB
45° Phải - Sau 45-phai-sau-fRzY3r
45° Trái - Sau 45-trai-sau-1q3G3J
Phải - Trước phai-truoc-eYWg1d
Trái - Trước trai-truoc-r6BEZd
Phải - Sau phai-sau-v1hAm6
Trái - Sau trai-sau-t8QgFO

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "isPhotoValid": <Ảnh có hợp lệ hay không (Boolean)>,
    "traceId": <ID dùng khi liên hệ với AICycle (UUID)>,
    "errorCodeFromEngine": <Mã lỗi trả về từ AICycle Engine (Number)>,
    "message": <Message lỗi trả về từ AICycle Engine (String)>,
    "imageId": <ID của ảnh (Number)>,
    "result": [<Image>]
}







Chi tiết Object item Image

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
imgSize Kích thước ảnh Bắt buộc Array[number] n [1920, 1080]
imgUrl Link ảnh gốc Bắt buộc Text 1,255 {{s3Link}}
errorCodeFromEngine Mã lỗi ảnh Bắt buộc Number 1,999999 0
message Chi tiết lỗi ảnh Bắt buộc Text 1,255 Ảnh chụp qua màn hình
damages Các hỏng hóc của ảnh Bắt buộc Array[damage] n
carParts Các bộ phận của ảnh Bắt buộc Array[carPart] n

Chi tiết Object item carPart

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carPartKey Mã bộ phận Bắt buộc Text 1,255 den-gam-truoc-trai-d7WevY
position Vị trí bộ phận Bắt buộc Text 1,255 Trái - Trước
name Tên bộ phận Bắt buộc Text 1,255 Đèn gầm trước trái
maskUrl Url mask bộ phận Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_RESULT/EGfDHztL2Vffgc72cM1DG.png

Chi tiết Object item damage

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
name Tên hỏng hóc Bắt buộc Text 1,255 Trầy (xước)
maskUrl mask hỏng hóc Bắt buộc Text 1,255 …

Chi tiết Bảng Mã lỗi cùng httpStatus trả về của errorCodeFromEngine

Chú thích

Với những lỗi có level là error sẽ chỉ trả ra mã lỗi và message lỗi, những lỗi level warning sẽ trả ra mã lỗi, message, và car_part, car_damages như bình thường

Mã lỗi HTTP Status Response body Level lỗi
0 200 Ảnh hợp lệ
37143 400 {"errorCodeFromEngine": 37143, "message": "Không thể nhận diện ô tô trong ảnh. Vui lòng chụp lại"} Error
40412 400 {"errorCodeFromEngine": 40412, "message": "Ảnh chụp bị mờ. Vui lòng chụp lại"} Error
32324 400 {"errorCodeFromEngine": 32324, "message": "Không download được ảnh"} Error
23212 200 {"errorCodeFromEngine": 23212, "message": "Ảnh chụp bị tối"} Warning
84680 400 {"errorCodeFromEngine": 84680, "message": "Ảnh chụp qua màn hình. Vui lòng chụp lại"} Error
47565 400 {"errorCodeFromEngine": 47565, "message": "Trả ra error của engine"} Error
67219 400 {"errorCodeFromEngine": 67219, "message": "Không thể nhận diện ô tô trong ảnh. Vui lòng chụp lại"} Error
77704 200 {"errorCodeFromEngine": 77704, "message": "Ảnh chụp bị lóa"} Warning
50676 400 {"errorCodeFromEngine": 50676, "message": "Ảnh không đúng góc chụp. Vui lòng chụp lại"} Error
378224 400 {"errorCodeFromEngine": 378224, "message": "Ảnh không phải xe tải"} Error
178434 400 {"errorCodeFromEngine": 178434, "message": "Ảnh không phải xe con"} Error

d. Ví dụ đầu ra

{
    "status": "success",
    "isPhotoValid": true,
    "traceId": "80540cf80585486f63432dcdf680fd20",
    "errorCodeFromEngine": 0,
    "message": "",
    "imageId": 4808,
    "result": [
        {
            "imgSize": [1920, 1080],
            "damages": [
                {
                    "name": "Móp, bẹp(thụng)",
                    "damageKey": "mop-bep-jtep4m",
                    "location": "",
                    "score": 1,
                    "box": [ 0.34, 0.14, 0.79,0.77],
                    "maskPath": "nfU_HFiSOi4wEkP1ycUwv.png",
                    "isPart": false,
                    "maskUrl": "{{s3Url}}"
                },
                ...
            ],
            "carParts": [
                {
                    "name": "Trụ kính cánh cửa",
                    "carPartKey": "khung-kinh-canh-cua-truoc-trai-KMtJpH",
                    "position": "Trái - Trước",
                    "score": 0.83660888671875,
                    "box": [
                        0.81875,
                        0,
                        0.9994791666666667,
                        0.2
                    ],
                    "maskPath": "vG4wVxBeWvLF5MFGMAfq9.png",
                    "isPart": true,
                    "damages": [
                        {
                            "name": "Trầy, xước",
                            "damageKey": "yfMzer07THdYoCI1SM2LN",
    
                            "score": 1,
                            "box": [
                                0.2171875,
                                0.07685185185185185,
                                0.9989583333333333,
                                0.9425925925925925
                            ],
             "maskPath": "favy1yqepBr_JM8tAJm2v.png",
                            "isPart": false,
                            "overlapRate": 0.00047147571877818216,
                            "maskUrl": "{{s3Url}}",
                        },
                        ...
                    ],
                },
                ...
            ]
        }
    ]
}

























3.10 APIs tích hợp Buy Me V1 (deprecated)

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/claimimages/triton-assessment-box
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Ví dụ

curl --location --request POST 'https://api.aicycle.ai/insurance/v2/claim-me/process' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--data-raw '{
   "claimId": 1,
   "imageName": "INSURANCE/1666145614576/1666145614447.jpg",
   "filePath": "INSURANCE/1666145614576/1666145614447.jpg",
   "imageRangeId": 1,
   "partDirectionId": 2,
    “oldImageId": 123
}'
Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
claimId Id của folder Bắt buộc Number 1,999999 123
imageName Tên ảnh Bắt buộc Text 1,255 INSURANCE_CLAIM/image-1.jpg
filePath Path ảnh trên s3 (lấy từ kết quả trả về của API get imageUrl ở mục 3.3) Bắt buộc Text 1,255 INSURANCE_CLAIM/image-1.jpg
imageRangeId Id Loại ảnh (Toàn cảnh, trung cảnh, cận cảnh) Bắt buộc Number 1,999999 1
partDirectionId Id Hướng ảnh Bắt buộc Number 1,999999 2
oldImageId Id ảnh cũ muốn xóa Optional Number 1,9999 3
vehicleType Loại xe muốn engine detect (xe tải, xe con) Optional ENUM(truck, car) 1,255 truck

Lưu ý

Các giá trị của imageRangeId

imageRangeName positionSlug
Toàn cảnh 1
Trung cảnh 2
Cận cảnh 3

Các giá trị của direction

directionName directionSlug
Trước 2
45° Phải - Trước 3
45° Trái - Trước 4
Sau 5
45° Phải - Sau 6
45° Trái - Sau 7
Phải - Trước 8
Trái - Trước 9
Phải - Sau 10
Trái - Sau 11

Chi tiết Bảng Mã lỗi cùng httpStatus trả về của errorCodeFromEngine

Chú thích

Với những lỗi có level là error sẽ chỉ trả ra mã lỗi và message lỗi, những lỗi level warning sẽ trả ra mã lỗi, message, và car_part, car_damages như bình thường

Mã lỗi HTTP Status Response body Level lỗi
0 200 Ảnh hợp lệ
37143 400 {"errorCodeFromEngine": 37143, "message": "Không thể nhận diện ô tô trong ảnh. Vui lòng chụp lại"} Error
40412 400 {"errorCodeFromEngine": 40412, "message": "Ảnh chụp bị mờ. Vui lòng chụp lại"} Error
32324 400 {"errorCodeFromEngine": 32324, "message": "Không download được ảnh"} Error
23212 200 {"errorCodeFromEngine": 23212, "message": "Ảnh chụp bị tối"} Warning
84680 400 {"errorCodeFromEngine": 84680, "message": "Ảnh chụp qua màn hình. Vui lòng chụp lại"} Error
47565 400 {"errorCodeFromEngine": 47565, "message": "Trả ra error của engine"} Error
67219 400 {"errorCodeFromEngine": 67219, "message": "Không thể nhận diện ô tô trong ảnh. Vui lòng chụp lại"} Error
77704 200 {"errorCodeFromEngine": 77704, "message": "Ảnh chụp bị lóa"} Warning
50676 400 {"errorCodeFromEngine": 50676, "message": "Ảnh không đúng góc chụp. Vui lòng chụp lại"} Error
378224 400 {"errorCodeFromEngine": 378224, "message": "Ảnh không phải xe tải"} Error
178434 400 {"errorCodeFromEngine": 178434, "message": "Ảnh không phải xe con"} Error

c. Ví dụ đầu ra

{
    "status": "success",
    "isCarExistInProfile": false,
    "isPhotoValid": true,
    "traceId": "80540cf80585486f63432dcdf680fd20",
     “errorCodeFromEngine”: 0,
     “message: “: “”,
    "imageId": 4808,
    "result": [
        {
            "img_size": [1920, 1080],
            "extra_infor": {
                "plate_number": "",
                "chassis_number": null,
                "car_company": "",
                "car_model": "",
                "car_color": [222, 220,216],
                "corner": "Trái - Trước",
                "imagePosition": 1
            },
            "car_damages": [
                {
                    "class": "Móp, bẹp(thụng)",
                    "class_uuid": "zmMJ5xgjmUpqmHd99UNq3",
                    "location": "",
                    "score": 1,
                    "box": [ 0.34, 0.14, 0.79,0.77],
                    "mask_path": "nfU_HFiSOi4wEkP1ycUwv.png",
                    "is_part": false,
                    "mask_url": "{{s3Url}}"
                },
	    ….
            ],
            "car_parts": [
                {
                    "class": "Trụ kính cánh cửa",
                    "class_uuid": "khung-kinh-canh-cua-truoc-trai-KMtJpH",
                    "location": "Trái - Trước",
                    "score": 0.83660888671875,
                    "box": [
                        0.81875,
                        0,
                        0.9994791666666667,
                        0.2
                    ],
                    "mask_path": "vG4wVxBeWvLF5MFGMAfq9.png",
                    "is_part": true,
                    "damages": [
                        {
                            "class": "Trầy, xước",
                            "class_uuid": "yfMzer07THdYoCI1SM2LN",
                            "location": "",
                            "score": 1,
                            "box": [
                                0.2171875,
                                0.07685185185185185,
                                0.9989583333333333,
                                0.9425925925925925
                            ],
                            "mask_path": "favy1yqepBr_JM8tAJm2v.png",
                            "is_part": false,
                            "overlap_rate": 0.00047147571877818216,
                            "claimId": 1,
                            "imageId": "4808",
							"isMaskDuplicate": false,
                            "mask_url": "{{s3Url}}",
                            "damage_type_name": "Trầy (xước)",
                            "damage_type_color": "#FFEC05"
                        },
		…..
                    ],
                    "car_part_name": "Khung kính cánh cửa trước trái",
                    "rawLocation": "Trái - Trước",
                    "car_part_color": "#21E0C1",
                    "mask_url": "{{s3Url}}"
                },
	…..
            ],
            "img_url": "{{s3Url}}"
        }
    ]
}






























3.11 APIs tích hợp Claim Me theo form data

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/claim-me/upload' \
--header 'Authorization: Bearer ${APIKEY}' \
--form '${fileImage}' \
--form 'externalSessionId="${externalId}"' \
--form 'directionSlug="45-trai-truoc-C1xM02"' \
--form 'isValidate="true"' \
--form 'location="Hai Bà Trưng, Hà Nội"' \
--form 'requestedTime="2026-06-09T08:20:29+07:00"' \
--form 'vehiclePartSlug="ma-bo-phan-den-gam"' \
--form 'vehiclePartName="Mã bộ phận đèn gầm"'
Method POST
API Url https://api.aicycle.ai/insurance/v2/claim-me/upload
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
img File ảnh xe Bắt buộc File n
claimFolderId Id Folder của AIcycle Optional Number 1,99999 123
externalSessionId Id folder (giấy chứng nhận) của đối tác Optional Text n folderId
directionSlug Slug góc chụp của ảnh Optional Text n truoc-sT9qgX
location Địa điểm chụp ảnh. Nếu truyền lên thì imgUrl trả ra sẽ có timemark kèm theo Optional Text n Hai Bà Trưng, Hà Nội
requestedTime Thời gian chụp ảnh. Nếu truyền lên thì imgUrl trả ra sẽ có timemark kèm theo Optional Text n 2026-06-09T08:20:29+07:00
vehiclePartSlug Mã bộ phận của khách hàng. Nếu truyền thì phải truyền kèm vehiclePartName; cả hai trường không được là chuỗi rỗng Optional Text 1,n ma-bo-phan-den-gam
vehiclePartName Tên bộ phận của khách hàng. Nếu truyền thì phải truyền kèm vehiclePartSlug; cả hai trường không được là chuỗi rỗng Optional Text 1,n Mã bộ phận đèn gầm

Các giá trị của directionSlug

directionName directionSlug
Trước truoc-sT9qgX
45° Phải - Trước 45-phai-truoc-UoYzs6
45° Trái - Trước 45-trai-truoc-C1xM02
Sau sau-htBwjB
45° Phải - Sau 45-phai-sau-fRzY3r
45° Trái - Sau 45-trai-sau-1q3G3J
Phải - Trước phai-truoc-eYWg1d
Trái - Trước trai-truoc-r6BEZd
Phải - Sau phai-sau-v1hAm6
Trái - Sau trai-sau-t8QgFO
Trái trai-MyuVUE
Phải phai-4wif2Z
Toàn cảnh hiện trường toan-canh-hien-truong-H5TLMZ

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "isPhotoValid": <Ảnh có hợp lệ hay không (Boolean)>,
    "traceId": <ID dùng khi liên hệ với AICycle (UUID)>,
    "errorCodeFromEngine": <Mã lỗi trả về từ AICycle Engine (Number)>,
    "message": <Message lỗi trả về từ AICycle Engine (String)>,
    "imageId": <ID của ảnh (Number)>,
    "result": [<Image>]
}







Chi tiết Object item Image

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
imgSize Kích thước ảnh Bắt buộc Array[number] n [1920, 1080]
imgUrl Link ảnh gốc Bắt buộc Text 1,255 {{s3Link}}
damages Các hỏng hóc của ảnh Bắt buộc Array[damage] n
carParts Các bộ phận của ảnh Bắt buộc Array[carPart] n
imgDrawUrl Link ảnh đã vẽ sẵn vết hỏng Bắt buộc Text 1,255 {{s3Link}}
extraInfor Các thông tin thêm của xe Bắt buộc Object n
imageQuality Chất lượng ảnh (độ sáng, độ lóa). Chỉ trả ra khi AICycle cấu hình cho đối tác Optional Object n {“brightness”: 72.87, “glare”: 19.59}

Chi tiết Object item carPart

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carPartKey Mã bộ phận Bắt buộc Text 1,255 den-gam-truoc-trai-d7WevY
position Vị trí bộ phận Bắt buộc Text 1,255 Trái - Trước
name Tên bộ phận Bắt buộc Text 1,255 Đèn gầm trước trái
maskUrl Url mask bộ phận Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_RESULT/EGfDHztL2Vffgc72cM1DG.png

Chi tiết Object item damage

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
name Tên hỏng hóc Bắt buộc Text 1,255 Trầy (xước)
maskUrl mask hỏng hóc Bắt buộc Text 1,255 …

Chi tiết Object item extraInfor

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
plateNumber Biển số xe Bắt buộc Text 1,255 30A 99999
carCompany Hãng xe Bắt buộc Text 1,255 PEUGEOT
carModel Hiệu xe Bắt buộc Text 1,255 3008
carShape Loại xe Bắt buộc Text 1,255 SUV_CROSSOVER
carColor Màu xe Bắt buộc Array[number] n [ 200,136,72]
imagePosition Loại ảnh Bắt buộc Text ENUM toan-canh-afh4l5
imageDirection Loại ảnh Bắt buộc Text ENUM 45-phai-truoc-UoYzs6

Chi tiết Object item imageQuality

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
brightness Điểm độ sáng của ảnh. Điểm < 33 được đánh giá là ảnh tối Bắt buộc Number n 72.87
glare Điểm độ lóa của ảnh. Điểm > 18 được đánh giá là ảnh lóa Bắt buộc Number n 19.59

Các giá trị của imageDirection

name slug
Trước truoc-sT9qgX
45° Phải - Trước 45-phai-truoc-UoYzs6
45° Trái - Trước 45-trai-truoc-C1xM02
Sau sau-htBwjB
45° Phải - Sau 45-phai-sau-fRzY3r
45° Trái - Sau 45-trai-sau-1q3G3J
Phải - Trước phai-truoc-eYWg1d
Trái - Trước trai-truoc-r6BEZd
Phải - Sau phai-sau-v1hAm6
Trái - Sau trai-sau-t8QgFO

Các giá trị của imagePosition

name slug
Toàn cảnh toan-canh-afh4l5
Trung cảnh trung-canh-0s8mnb
Cận cảnh can-canh-czu5jp

Chi tiết Bảng Mã lỗi cùng httpStatus trả về của errorCodeFromEngine

Chú thích

Với những lỗi có level là error sẽ chỉ trả ra mã lỗi và message lỗi, những lỗi level warning sẽ trả ra mã lỗi, message, và car_part, car_damages như bình thường

Mã lỗi HTTP Status Response body Level lỗi
0 200 Ảnh hợp lệ
37143 400 {"errorCodeFromEngine": 37143, "message": "Không thể nhận diện ô tô trong ảnh. Vui lòng chụp lại"} Error
40412 400 {"errorCodeFromEngine": 40412, "message": "Ảnh chụp bị mờ. Vui lòng chụp lại"} Error
32324 400 {"errorCodeFromEngine": 32324, "message": "Không download được ảnh"} Error
23212 200 {"errorCodeFromEngine": 23212, "message": "Ảnh chụp bị tối"} Warning
84680 400 {"errorCodeFromEngine": 84680, "message": "Ảnh chụp qua màn hình. Vui lòng chụp lại"} Error
47565 400 {"errorCodeFromEngine": 47565, "message": "Trả ra error của engine"} Error
67219 400 {"errorCodeFromEngine": 67219, "message": "Không thể nhận diện ô tô trong ảnh. Vui lòng chụp lại"} Error
77704 200 {"errorCodeFromEngine": 77704, "message": "Ảnh chụp bị lóa"} Warning
50676 400 {"errorCodeFromEngine": 50676, "message": "Ảnh không đúng góc chụp. Vui lòng chụp lại"} Error
378224 400 {"errorCodeFromEngine": 378224, "message": "Ảnh không phải xe tải"} Error
178434 400 {"errorCodeFromEngine": 178434, "message": "Ảnh không phải xe con"} Error
38312 200 {"errorCodeFromEngine": 38312, "message": "Cảnh báo ảnh đầu trong hồ sơ phải là ảnh có biển số"} Warning
22155 200 {"errorCodeFromEngine": 22155, "message": "Ảnh không cùng 1 xe"} Warning
41074 200 {"errorCodeFromEngine": 41074, "message": "Warning validate hãng xe, hiệu xe, biển số xe"} Warning
95889 400 {"errorCodeFromEngine": 95889, "message": "Ảnh không cùng 1 xe"} Error
87143 400 {"errorCodeFromEngine": 87143, "message": "Ảnh đầu trong hồ sơ phải là ảnh có biển số"} Error
11267 400 {"errorCodeFromEngine": 11267, "message": "Lỗi validate hãng xe, hiệu xe, biển số xe"} Error

d. Ví dụ đầu ra

{
    "status": "success",
    "isPhotoValid": true,
    "traceId": "80540cf80585486f63432dcdf680fd20",
    "errorCodeFromEngine": 0,
    "message": "",
    "imageId": 4808,
    "result": [
        {
            "imgSize": [1920, 1080],
            "imageUrl": {{s3Link}},
            "imageDrawUrl": {{s3Link}}
            "imageQuality": {
                "brightness": 72.87,
                "glare": 19.59
            },
            "damages": [
                {
                    "name": "Móp, bẹp(thụng)",
                    "damageKey": "mop-bep-jtep4m",
                    "location": "",
                    "score": 1,
                    "box": [ 0.34, 0.14, 0.79,0.77],
                    "maskPath": "nfU_HFiSOi4wEkP1ycUwv.png",
                    "isPart": false,
                    "maskUrl": "{{s3Url}}"
                },
                ...
            ],
            "carParts": [
                {
                    "name": "Trụ kính cánh cửa",
                    "carPartKey": "khung-kinh-canh-cua-truoc-trai-KMtJpH",
                    "position": "Trái - Trước",
                    "score": 0.83660888671875,
                    "box": [
                        0.81875,
                        0,
                        0.9994791666666667,
                        0.2
                    ],
                    "maskPath": "vG4wVxBeWvLF5MFGMAfq9.png",
                    "isPart": true,
                    "damages": [
                        {
                            "name": "Trầy, xước",
                            "damageKey": "yfMzer07THdYoCI1SM2LN",
							   "score": 1,
                            "box": [
                                0.2171875,
                                0.07685185185185185,
                                0.9989583333333333,
                                0.9425925925925925
                            ],
                            "maskPath": "favy1yqepBr_JM8tAJm2v.png",
                            "isPart": false,
                            "overlapRate": 0.00047147571877818216,
                            "maskUrl": "{{s3Url}}",
                        },
                        ...
                    ],
                },
                ...
            ]
        }
    ]
}






















3.12 APIs tích hợp Buy Me theo form data

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/buy-me/upload' \
--header 'Authorization: Bearer ${APIKEY}' \
--form '${fileImage}' \
--form 'externalSessionId="${externalId}"' \
--form 'directionSlug="45-trai-truoc-C1xM02"' \
--form 'isValidate="true"' \
--form 'location="Hai Bà Trưng, Hà Nội"' \
--form 'requestedTime="2026-06-09T08:20:29+07:00"'
Method POST
API Url https://api.aicycle.ai/insurance/v2/buy-me/upload
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
img File ảnh xe Bắt buộc File n
claimFolderId Id Folder của AIcycle Optional Number 1,99999 123
externalSessionId Id folder (giấy chứng nhận) của đối tác Optional Text n folderId
directionSlug Slug Hướng ảnh Optional (bắt buộc nếu bật flag isValidate) Text 1,255 45-trai-truoc-C1xM02
isValidate Flag bật tắt validate góc chụp Optional Boolean n true
carCompany Mã (tên) hãng xe của khách hàng cần validate Optional (bắt buộc nếu khách hàng yêu cầu validate hãng, hiệu, biển số) Text 1,255 KIA
carModel Mã (tên) hiệu xe của khách hàng cần validate Optional (bắt buộc nếu khách hàng yêu cầu validate hãng, hiệu, biển số) Text 1,255 Morning
licensePlate Biển số của khách hàng cần validate Optional (bắt buộc nếu khách hàng yêu cầu validate hãng, hiệu, biển số) Text 1,255 30A99999
hasLicensePlate Flag đánh dấu folder hiện tại là folder có biển hay không biển số Optional Boolean n True
location Địa điểm chụp ảnh. Nếu truyền lên thì imgUrl trả ra sẽ có timemark kèm theo Optional Text n Hai Bà Trưng, Hà Nội
requestedTime Thời gian chụp ảnh. Nếu truyền lên thì imgUrl trả ra sẽ có timemark kèm theo Optional Text n 2026-06-09T08:20:29+07:00
externalUsedCar Lưu lại thông tin folder hiện tại là xe cũ hay mới phục vụ cho việc làm báo cáo Optional Text ENUM(old, new) new

Các giá trị của directionSlug

directionName directionSlug
Trước truoc-sT9qgX
45° Phải - Trước 45-phai-truoc-UoYzs6
45° Trái - Trước 45-trai-truoc-C1xM02
Sau sau-htBwjB
45° Phải - Sau 45-phai-sau-fRzY3r
45° Trái - Sau 45-trai-sau-1q3G3J
Phải phai-4wif2Z
Trái trai-MyuVUE
Tem đăng kiểm tem-dang-kiem-LC81Ar
Taplo tap-lo-H4SHs1
Số khung so-khung-qmqAsM
Đăng kiểm xe dang-kiem-xe-82YjAa

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "isPhotoValid": <Ảnh có hợp lệ hay không (Boolean)>,
    "traceId": <ID dùng khi liên hệ với AICycle (UUID)>,
    "errorCodeFromEngine": <Mã lỗi trả về từ AICycle Engine (Number)>,
    "message": <Message lỗi trả về từ AICycle Engine (String)>,
    "imageId": <ID của ảnh (Number)>,
    "result": [<Image>],
    "stateFolderCode": <Trạng thái của folder hiện tại (có cùng 1 xe hay không) (Number)>
    "stateFolderMessage": <Trạng thái của folder hiện tại (có cùng 1 xe hay không) (String)>
}









Chi tiết Object item Image

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
imgSize Kích thước ảnh Bắt buộc Array[number] n [1920, 1080]
imgUrl Link ảnh gốc Bắt buộc Text 1,255 {{s3Link}}
damages Các hỏng hóc của ảnh Bắt buộc Array[damage] n
carParts Các bộ phận của ảnh Bắt buộc Array[carPart] n
imgDrawUrl Link ảnh đã vẽ sẵn vết hỏng Bắt buộc Text 1,255 {{s3Link}}
extraInfor Các thông tin thêm của xe Bắt buộc Object n

Chi tiết Object item carPart

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carPartKey Mã bộ phận Bắt buộc Text 1,255 den-gam-truoc-trai-d7WevY
position Vị trí bộ phận Bắt buộc Text 1,255 Trái - Trước
name Tên bộ phận Bắt buộc Text 1,255 Đèn gầm trước trái
maskUrl Url mask bộ phận Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_RESULT/EGfDHztL2Vffgc72cM1DG.png

Chi tiết Object item damage

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
name Tên hỏng hóc Bắt buộc Text 1,255 Trầy (xước)
maskUrl mask hỏng hóc Bắt buộc Text 1,255 …

Chi tiết Object item extraInfor

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
plateNumber Biển số xe Bắt buộc Text 1,255 30A 99999
carCompany Hãng xe Bắt buộc Text 1,255 PEUGEOT
carModel Hiệu xe Bắt buộc Text 1,255 3008
carShape Loại xe Bắt buộc Text 1,255 SUV_CROSSOVER
carColor Màu xe Bắt buộc Array[number] n [ 200,136,72]
imagePosition Loại ảnh Bắt buộc Text ENUM toan-canh-afh4l5

Các giá trị của imagePosition

name slug
Toàn cảnh toan-canh-afh4l5
Trung cảnh trung-canh-0s8mnb
Cận cảnh can-canh-czu5jp

Chi tiết Bảng Mã lỗi cùng httpStatus trả về của errorCodeFromEngine

Chú thích Với những lỗi có level là error sẽ chỉ trả ra mã lỗi và message lỗi, những lỗi level warning sẽ trả ra mã lỗi, message, và car_part, car_damages như bình thường

Mã lỗi HTTP Status Response body Level lỗi
0 200 Ảnh hợp lệ
37143 400 {"errorCodeFromEngine": 37143, "message": "Không thể nhận diện ô tô trong ảnh. Vui lòng chụp lại"} Error
40412 400 {"errorCodeFromEngine": 40412, "message": "Ảnh chụp bị mờ. Vui lòng chụp lại"} Error
32324 400 {"errorCodeFromEngine": 32324, "message": "Không download được ảnh"} Error
23212 200 {"errorCodeFromEngine": 23212, "message": "Ảnh chụp bị tối"} Warning
84680 400 {"errorCodeFromEngine": 84680, "message": "Ảnh chụp qua màn hình. Vui lòng chụp lại"} Error
47565 500 {"errorCodeFromEngine": 47565, "message": "Trả ra error của engine"} Error
67219 400 {"errorCodeFromEngine": 67219, "message": "Không thể nhận diện ô tô trong ảnh. Vui lòng chụp lại"} Error
77704 200 {"errorCodeFromEngine": 77704, "message": "Ảnh chụp bị lóa"} Warning
50676 400 {"errorCodeFromEngine": 50676, "message": "Ảnh không đúng góc chụp. Vui lòng chụp lại"} Error
10012 408 {"errorCodeFromEngine": 10012, "message": "Request Timeout"} Error
4343 400 {"errorCodeFromEngine": 4343, "message": "Ảnh không phải tem đăng kiểm"} Error
1588 400 {"errorCodeFromEngine": 1588, "message": "Ảnh không phải taplo"} Error
38312 200 {"errorCodeFromEngine": 38312, "message": "Cảnh báo ảnh đầu trong hồ sơ phải là ảnh có biển số"} Warning
22155 200 {"errorCodeFromEngine": 22155, "message": "Ảnh không cùng 1 xe"} Warning
41074 200 {"errorCodeFromEngine": 41074, "message": "Warning validate hãng xe, hiệu xe, biển số xe"} Warning
95889 400 {"errorCodeFromEngine": 95889, "message": "Ảnh không cùng 1 xe"} Error
87143 400 {"errorCodeFromEngine": 87143, "message": "Ảnh đầu trong hồ sơ phải là ảnh có biển số"} Error
11267 400 {"errorCodeFromEngine": 11267, "message": "Lỗi validate hãng xe, hiệu xe, biển số xe"} Error

Chi tiết Bảng Mã và message của stateFolderCode

stateFolderCode message
1 chỉ có 1 ảnh trong folder
3 các ảnh trong folder thuộc cùng một xe
4 các ảnh trong folder không thuộc cùng một xe
12 Hồ sơ có thể có ảnh không đảm bảo chất lượng. Khách hàng đã up ${numOfImageErr}. Vui lòng check lại hồ sơ.
13 Hồ sơ có thể được chụp trong không gian tối, khách hàng đã up ${numOfImageErr} ảnh tối. Vui lòng check lại hồ sơ.
14 Hồ sơ có thể có ảnh mờ, khách hàng đã up ${numOfImageErr} ảnh mờ. Vui lòng check lại hồ sơ.
15 Hồ sơ có thể có ảnh lóa, khách hàng đã up ${numOfImageErr} ảnh lóa. Vui lòng check lại hồ sơ.
16 Hồ sơ có dấu hiệu gian lận, khách hàng đã up ${numOfImageErr} ảnh chụp qua màn hình. Vui lòng check lại hồ sơ.
17 Folder hiện tại chưa có ảnh xe

d. Ví dụ đầu ra

{
    "status": "success",
    "isPhotoValid": true,
    "traceId": "80540cf80585486f63432dcdf680fd20",
    "errorCodeFromEngine": 0,
    "message": "",
    "imageId": 4808,
    "stateFolderCode": 3,
    "stateFolderMessage": "Các ảnh cùng một xe",
    "result": {
            "imgSize": [1920, 1080],
            "imageUrl": {{s3Link}},
            "imageDrawUrl": {{s3Link}},
            "extraInfor": {
              "imageDirection": "45-phai-truoc-UoYzs6",
              "additionalCornerInfor": "45° Phải - Trước",
              "imagePosition": "toan-canh-afh4l5",
              "plateNumber": "30F 04872",
              "chassisNumber": null,
              "carCompany": "PEUGEOT",
              "carModel": "3008",
              "carShape": "SUV_CROSSOVER",
              "carColor": [
                  200,
                  136,
                  72
              ]
            }, 
            "damages": [
                {
                    "name": "Móp, bẹp(thụng)",
                    "damageKey": "mop-bep-jtep4m",
                    "location": "",
                    "score": 1,
                    "box": [ 0.34, 0.14, 0.79,0.77],
                    "maskPath": "nfU_HFiSOi4wEkP1ycUwv.png",
                    "isPart": false,
                    "maskUrl": "{{s3Url}}"
                },
                ...
            ],
            "carParts": [
                {
                    "name": "Trụ kính cánh cửa",
                    "carPartKey": "khung-kinh-canh-cua-truoc-trai-KMtJpH",
                    "position": "Trái - Trước",
                    "score": 0.83660888671875,
                    "box": [
                        0.81875,
                        0,
                        0.9994791666666667,
                        0.2
                    ],
                    "maskPath": "vG4wVxBeWvLF5MFGMAfq9.png",
                    "isPart": true,
                    "damages": [
                        {
                            "name": "Trầy, xước",
                            "damageKey": "yfMzer07THdYoCI1SM2LN",
    
                            "score": 1,
                            "box": [
                                0.2171875,
                                0.07685185185185185,
                                0.9989583333333333,
                                0.9425925925925925
                            ],
                            "maskPath": "favy1yqepBr_JM8tAJm2v.png",
                            "isPart": false,
                            "overlapRate": 0.00047147571877818216,
                            "maskUrl": "{{s3Url}}",
                        },
                        ...
                    ],
					          },
                ...
            ]
        }
}






































































e. Chi tiết đầu ra với ảnh góc tem đăng kiểm

{
    "status": <Trạng thái của Request (String)>,
    "errorCodeFromEngine": <Mã lỗi trả về từ AICycle Engine (Number)>,
    "message": <Message lỗi trả về từ AICycle Engine (String)>,
    "stampImageId": <ID của ảnh tem đăng kiểm (Number)>,
    "result": {
      "imgUrl": <Url ảnh tem đăng kiểm (String)>,
      "stampId": <Id của ảnh tem đăng kiểm (String)>,
      "licensePlate": <Biển số xe của tem đăng kiểm (String)>,
      "expiredMonth": <Ngày hết hạn theo tháng (String)>,
      "expiredDate: <Ngày hết hạn theo ngày (String)>
    },
    "stateFolderCode": <Trạng thái của folder hiện tại (có cùng 1 xe hay không) (Number)>
    "stateFolderMessage": <Trạng thái của folder hiện tại (có cùng 1 xe hay không) (String)>
}






f. Chi tiết đầu ra với ảnh taplo


{
    "status": <Trạng thái của Request (String)>,
    "errorCodeFromEngine": <Mã lỗi trả về từ AICycle Engine (Number)>,
    "message": <Message lỗi trả về từ AICycle Engine (String)>,
    "taploImageId": <ID của ảnh taplo (Number)>,
    "result": {
      "imgUrl": <Url ảnh taplo (String)>,
      "taploIconInfo": [
        {
          "iconName": <Tên icon mà AI đọc được (String)>,
          "iconBoundingBox": <Bounding Box của Icon hiện tại (Array<Number>)>
        }
      ]
    }
}










3.13: API lấy kết quả Hồ sơ (nhóm theo ảnh) V2

a. Thông tin cơ bản

Ví dụ

curl --location --request GET 'https://api.aicycle.ai/insurance/v2/claimfolders/{externalSessionId}/external-image-result' \
--header 'authorization: Bearer $$API_KEY$$' \
--data-raw ''
Method GET
API Url https://api.aicycle.ai/insurance/v2/claimfolders/{externalSessionId}/external-image-result
API Headers { "Authorization": "Bearer $$apiKey$$" }

b. Chi tiết đầu vào

Loại đầu vào: Params

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
externalSessionId Id của giấy chứng nhận (folder của khách hàng) Bắt buộc Text 1,255 folder1

c. Chi tiết đầu ra

{
    "results": {
        images: [<Image>]
    }
}




Chi tiết Object item Image

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
url Link ảnh Bắt buộc Text 1,255 {{imgUrl}}
imageSize Kích thước ảnh Bắt buộc Array[number] n [1920,1080]
directionName Góc chụp Bắt buộc Text 1,255 Trước
imageRangeName Loại ảnh Bắt buộc Text 1,255 Toàn cảnh
location Nơi ảnh được chụp Bắt buộc TEXT 1,255 Duy Tân, Cầu Giấy, Hà Nội
requestedTime Thời gian chụp ảnh Bắt buộc TEXT 1,255 2023-03-24 03:28:29.414232 +00:00
uploadedTime Thời gian ảnh được upload lên hệ thống Bắt buộc TEXT 1,255 2023-03-24 03:28:29.414232 +00:00
uploadLocation Nơi upload ảnh để thực hiện claim Bắt buộc TEXT 1,255 Hai Bà Trưng, Hà Nội
damageInfo Chi tiết hỏng hóc Bắt buộc Array[damageInfo] n []
imageDrawUrl Ảnh vẽ sẵn vết hỏng Bắt buộc Text 1, 255 {{s3Link}}

Chi tiết Object item damageInfo

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehiclePartName Tên bộ phận Bắt buộc TEXT 1,255 Ba đờ sốc trước
price Giá bộ phận Bắt buộc Number 1,9999 1000000
location Vị trí bộ phận Bắt buộc TEXT 1,255 Trước
damageDetail Chi tiết hỏng hóc của bộ phận Bắt buộc Array[damageDetail] n []

Chi tiết Object item damageDetail

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
url Link mask hỏng hóc Bắt buộc TEXT 1,255 {{maskUrl}}
damageTypeName Loại hỏng hóc Bắt buộc TEXT 1,255 Trầy (xước)
damagePercentage Phần trăm hỏng hóc Bắt buộc Number 1,9999 0.08
paintPercentage Phần trăm sơn Bắt buộc Number 0,1 1
dentedLevel Mức độ gò Bắt buộc TEXT ENUM(slight, moderate, severe) slight

d. Ví dụ đầu ra

{
    "result": {
        "images": [
            {
                "imageId": 16532,
                "imageName": "1679373021917.jpg",
                "filePath": "INSURANCE/1679373021956/1679373021917.jpg",
                "url": "{{imageUrl}}",
                "imageDrawUrl": "{{imageUrl}}",
                "imageSize": [
                    1920,
                    1080
                ],
                "directionName": "45° Trái - Sau",
                "imageRangeName": "Toàn cảnh",
                "timeProcess": 1.693,
                "timeAppUpload": 1.501,
                "requestedTime": "2023-03-24T03:28:29.414Z",
                "uploadedTime": "2023-03-27T03:04:53.001Z",
                "uploadLocation": "Quận Cầu Giấy, Hà Nội",
                "location": "Duy Tân, Cầu Giấy, Hà Nội",
                "errorType": null,
                "errorNote": null,
                "traceId": "265e70b629c05b353b1968693a4ca051",
                "damageInfo": [
                    {
                        "vehiclePartName": "Pa vô lê trái",
                        "vehiclePartExcelId": "pavole-trai-tEm7AB",
                        "price": 450000,
                        "laborCost": 0,
                        "totalCost": 450000,
                        "area": 70,
                        "location": "Trái",
                        "repairPlan": "Sửa chữa",
                        "damageDetail": [
                            {
                                "filePath": "fxVIBETAr_Buc1h6ngzC4.png",
                                "url": "{{maskUrl}}",
                                "damageTypeName": "Trầy (xước)",
                                "damageTypeColor": "#FFEC05",
                                "damageUuid": "yfMzer07THdYoCI1SM2LN",
                                "boxes": [
                                    0.3125,
                                    0.6731481481481482,
                                    0.32135416666666666,
                                    0.6953703703703704
                                ],
                                "damageArea": 0.6255235966733421,
                                "damagePercentage": 0.008936051381047744,
                                "paintPercentage": 1,
                                "dentedLevel": "slight"
                            }
                        ]
                    }
                ]
            }
     ]
   }
 }       






















3.14: API lấy kết quả Hồ sơ (nhóm theo bộ phận) V2

a. Thông tin cơ bản

Ví dụ

curl --location --request GET 'https://api.aicycle.ai/insurance/v2/claimfolders/${externalSessionId}/external-segment-result' \
--header 'authorization: Bearer $$API_KEY$$' \
--data-raw ''
Method GET
API Url https://api.aicycle.ai/insurance/v2/claimfolders/{externalSessionId}/external-segment-result
API Headers { "Authorization": "Bearer $$apiKey$$" }

b. Chi tiết đầu vào

Loại đầu vào: Params

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
externalSessionId Id hồ sơ (giấy chứng nhận) của khách hàng Bắt buộc Text 1,255 folder1

c. Chi tiết đầu ra

{
    ${VehiclePart}
}

Chi tiết Object item VehiclePart

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehiclePartExcelId Mã bộ phận Bắt buộc Text 1,255 ba-do-soc-truoc-WUBZvD
vehiclePartName Tên bộ phận Bắt buộc Text 1,255 Ba đờ sốc trước
vehiclePartDirectionSlug Mã vị trí bộ phận Bắt buộc Text 1,255 45-phai-sau-fRzY3r
vehiclePartDirectionName Tên vị trí bộ phận Bắt buộc Text 1,255 45° Phải - Sau
location Vị trí bộ phận Bắt buộc Text 1,255 Trước
damages Chi tiết hỏng hóc Bắt buộc Array[damage] n []
images Ảnh Bắt buộc Array[image] n []
painPercentage Phần trăm sơn của bộ phận Bắt buộc number 0,1 1
dentedLevel Mức độ gò Bắt buộc Text ENUM(slight, moderate, severe) slight
paintLevel Mức độ sơn Bắt buộc Text ENUM(slight, moderate, severe) slight
repairPlan Kết luận phục hồi Bắt buộc Text ENUM(paint, paintAndRestore, replace, terminate) paint
dentedLevelExternal Mức độ gò theo mã mapping với khách hàng Bắt buộc Text … …
paintPercentageExternal Mức độ sơn theo mã mapping với khách hàng Bắt buộc Text … …
punctureLevelExternal Mức độ thủng, rách theo mã mapping với khách hàng Bắt buộc Text … …
editedDamages Danh sách mã hỏng hóc và phương án sửa chữa đã được người dùng cập nhật Optional Array[editedDamage] n []

Chi tiết Object item editedDamage

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
damageCode Mã tổn thất Bắt buộc Text 1,255 MaHongHoc1
repairMethodCode Mã phương án sửa chữa Bắt buộc Text 1,255 PhuongAn1

Chi tiết Object item damage

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
damageTypeName Tên hỏng hóc Bắt buộc Text 1,255 Trầy (xước)
damagePercentage Phần trăm hỏng hóc Bắt buộc Number 0,1 0.05
damageArea Diện tích hỏng hóc Bắt buộc Number 0,1 0.05

Chi tiết Object item image

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
imageUrl Url ảnh Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_RESULT/EGfDHztL2Vffgc72cM1DG.png
imageDrawUrl Url ảnh đã vẽ sẵn mask vết hỏng Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_RESULT/EGfDHztL2Vffgc72cM1DG.png
imageRange Loại ảnh Bắt buộc Text 1,255 Toàn cảnh
location Nơi ảnh được chụp Bắt buộc TEXT 1,255 Duy Tân, Cầu Giấy, Hà Nội
requestedTime Thời gian chụp ảnh Bắt buộc TEXT 1,255 2023-03-24 03:28:29.414232 +00:00
uploadedTime Thời gian ảnh được upload lên hệ thống Bắt buộc TEXT 1,255 2023-03-24 03:28:29.414232 +00:00
uploadLocation Nơi upload ảnh để thực hiện claim Bắt buộc TEXT 1,255 Hai Bà Trưng, Hà Nội
damageMasks Chi tiết hỏng hóc của ảnh Bắt buộc Array[damageMask] n []
isNewImageMapping Ảnh cận cảnh vừa được nhận diện vết hỏng thông qua mapping với các ảnh context xung quanh. Chỉ trả về true ở lần gọi API đầu tiên ngay sau khi ảnh được mapping thành công và có hỏng hóc, các lần gọi sau và các ảnh khác trả về false. Trường này chỉ xuất hiện với tổ chức được bật tính năng mapping ảnh cận cảnh với ảnh context Optional Boolean true, false false
isNeedSyncVehiclePart Ảnh cần đồng bộ lại bộ phận. Khi hồ sơ chưa đủ thông tin để xác định xe 1 cửa hoặc xe bán tải, API upload ảnh tạm ẩn các bộ phận dễ nhầm lẫn (cánh cửa, các bộ phận đặc thù của xe bán tải). Khi hồ sơ đã được xác định, nếu bộ phận hỏng hóc của ảnh trong kết quả này khác với bộ phận đã trả ở API upload, trường này trả về true để khách hàng cập nhật lại bộ phận của ảnh theo kết quả này. Chỉ trả về true ở lần gọi API đầu tiên sau khi phát hiện khác biệt, các lần gọi sau trả về false. Trường này chỉ xuất hiện với tổ chức được bật tính năng nhận diện xe 1 cửa / xe bán tải Optional Boolean true, false false

Chi tiết Object item damageMask

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
damageTypeName Loại hỏng hóc Bắt buộc Text 1,255 Trầy (xước)
maskUrl Url mask hỏng hóc Bắt buộc Text 1,255 https://dyta7vmv7sqle.cloudfront.net/INSURANCE_RESULT/EGfDHztL2Vffgc72cM1DG.png

d. Ví dụ đầu ra

{
    [
        {
            "vehiclePartExcelId": "ba-do-soc-truoc-WUBZvD",
            "vehiclePartName": "Ba đờ sốc trước",
            "vehiclePartDirectionSlug": "45-phai-sau-fRzY3r",
            "vehiclePartDirectionName": "45° Phải - Sau",
            "location": "Trước",
            "createdDate": "2022/10/24",
            "damages": [
                {
                    "damageTypeName": "Trầy (xước)",
                    "damagePercentage": 0.0419343353811561,
                    "damageArea": 0.419343353811561,
                    "damageTypeColor": "#FFEC05"
                }
            ],
            "images": [
                {
                    "imageId": 10579,
                    "filePath": "INSURANCE_CLAIM/1652252930377/image_picker7865199709592835107.jpg",
                    "imageUrl": "https://s3-sgn09.fptcloud.com/aicycle/INSURANCE_CLAIM/1652252930377/image_picker7865199709592835107.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=0080fa5f9d06c7ad85c7%2F20221024%2Fsgn09%2Fs3%2Faws4_request&X-Amz-Date=20221024T105823Z&X-Amz-Expires=7200&X-Amz-Signature=1e0ad191019668c5e77af28aa301f00f3d5f22a98882a1024660da2b9d946897&X-Amz-SignedHeaders=host",
                    "imageDrawUrl": "https://s3-sgn09.fptcloud.com/aicycle/INSURANCE_CLAIM/1652252930377/image_picker7865199709592835107.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=0080fa5f9d06c7ad85c7%2F20221024%2Fsgn09%2Fs3%2Faws4_request&X-Amz-Date=20221024T105823Z&X-Amz-Expires=7200&X-Amz-Signature=1e0ad191019668c5e77af28aa301f00f3d5f22a98882a1024660da2b9d946897&X-Amz-SignedHeaders=host",
                    "imageRange": "Toàn cảnh",
                    "damageExist": true,
                    "errorType": null,
                    "errorNote": null,
                    "location": "Duy Tân, Cầu Giấy, Hà Nội",
                    "requestedTime": "2023-03-24T03:28:29.414Z",
                    "uploadedTime": "2023-03-27T03:04:53.001Z",
                    "uploadLocation": "Quận Cầu Giấy, Hà Nội",
                    "timeProcess": 2.678,
                    "damageMasks": [
                        {
                            "maskPath": "8EskO3gPp1DYO00BOcBPq.png",
                            "maskUrl": "https://s3-sgn09.fptcloud.com/aicycle/INSURANCE_RESULT/8EskO3gPp1DYO00BOcBPq.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=0080fa5f9d06c7ad85c7%2F20221024%2Fsgn09%2Fs3%2Faws4_request&X-Amz-Date=20221024T105823Z&X-Amz-Expires=7200&X-Amz-Signature=d531e05207a16858319bf560331cb684e20e728abd84c516c4d2918d5139dbef&X-Amz-SignedHeaders=host",
                            "vehiclePartName": "Ba đờ sốc trước",
                            "damageTypeUuid": "yfMzer07THdYoCI1SM2LN",
                            "damageTypeName": "Trầy (xước)",
                            "damageTypeColor": "#FFEC05",
                            "boxes": [
                                0,
                                0,
                                1,
                                1
                            ],
                            "isPart": false,
                            "userCreated": false
                        }
                    ],
                    "isNewImageMapping": false,
                    "isNeedSyncVehiclePart": false
                }
            ],
            "price": 1000000,
            "laborCost": 0,
            "totalCost": 1000000,
            "area": 10,
            "repairPlan": "Sửa chữa",
            "dentedLevel": "slight",
            "paintLevel": "slight",
            "painPercentage": 1,
            "editedDamages": [
                {
                    "damageCode": "MaHongHoc1",
                    "repairMethodCode": "PhuongAn1"
                },
                {
                    "damageCode": "MaHongHoc2",
                    "repairMethodCode": "PhuongAn2"
                }
            ]
        }
    ]
}






















3.15: API verify hồ sơ

a. Thông tin cơ bản

Ví dụ

curl --location --request GET 'https://api.aicycle.ai/insurance/insurance/checkCar/${claimId}' \
--header 'authorization: Bearer $$API_KEY$$'
Method GET
API Url https://api.aicycle.ai/insurance/insurance/checkCar/${claimId}
API Headers { "Authorization": "Bearer $$apiKey$$" }

b. Chi tiết đầu vào

Loại đầu vào: Params

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
claimId Id hồ sơ do AICycle trả ra Bắt buộc Number 1,99999 123

c. Chi tiết đầu ra

{
  "state": <Number>(Mã trạng thái của hồ sơ),
  "message": <String>(Message thông báo trạng thái của hồ sơ)
}

Các giá trị của state và message

stateId message
0 trạng thái mặc định (các ảnh thuộc cùng một xe)
1 chỉ có 1 ảnh trong folder
2 có ít nhất 1 ảnh trong folder chụp không đúng góc
3 các ảnh trong folder thuộc cùng một xe
4 các ảnh trong folder không thuộc cùng một xe
5 không nhận diện được biển số nào trong folder
6 thư mục ảnh rỗng
12 Hồ sơ có thể có ảnh không đảm bảo chất lượng. Khách hàng đã up ${numOfImageErr}. Vui lòng check lại hồ sơ.
13 Hồ sơ có thể được chụp trong không gian tối, khách hàng đã up ${numOfImageErr} ảnh tối. Vui lòng check lại hồ sơ.
14 Hồ sơ có thể có ảnh mờ, khách hàng đã up ${numOfImageErr} ảnh mờ. Vui lòng check lại hồ sơ.
15 Hồ sơ có thể có ảnh lóa, khách hàng đã up ${numOfImageErr} ảnh lóa. Vui lòng check lại hồ sơ.
16 Hồ sơ có dấu hiệu gian lận, khách hàng đã up ${numOfImageErr} ảnh chụp qua màn hình. Vui lòng check lại hồ sơ.

d. Ví dụ đầu ra

{
    "state": 16,
    "message": "Hồ sơ có dấu hiệu gian lận, khách hàng đã up 2 ảnh chụp qua màn hình. Vui lòng check lại hồ sơ."
}

3.16: API kiểm tra các ảnh trong hồ sơ theo id hồ sơ của khách hàng

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/v2/claimfolders/check-folder-external
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
externalSessionId Id Hồ sơ (giấy chứng nhận) của khách hàng Bắt buộc Text 1,255 HoSo1
licensePlate Biển số xe của folder Optional Text 1,255 30A-99999
carCompany Hãng xe của folder Optional Text 1,255 VINFAST
carModel Hiệu xe của folder Optional Text 1,255 VF6

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
state trạng thái của folder Bắt buộc Number 1,999999 1
message thông báo chi tiết về trạng thái của folder Bắt buộc Text 1,255 Các ảnh thuộc cùng một xe
plateNumber biển số xe của folder hiện tại Optional (chỉ trả ra khi folder ở trạng thái cùng 1 xe) Text 1,255 30A 99999
listImageInValid list id của các ảnh không hợp lệ Optional (chỉ trả ra khi folder ở trạng thái không cùng 1 xe) Array n [1,2,3]
carCompany Hãng xe của folder Optional (chỉ trả ra khi folder ở trạng thái cùng 1 xe) Text 1,255 VINFAST
carModel Hiệu xe của folder Optional (chỉ trả ra khi folder ở trạng thái cùng 1 xe) Text 1,255 VF6

d. Chi tiết các state

Loại đầu ra: Response body

state Mô tả
1 chỉ có 1 ảnh trong folder
3 các ảnh trong folder thuộc cùng một xe
4 các ảnh trong folder không thuộc cùng một xe
5 Hồ sơ chưa xác định được các ảnh có cùng 1 xe hay không

e. Ví dụ đầu ra

{
    "state": 3,
    "message": "Các ảnh cùng một xe",
    "listImageInValid": [],
    "plateNumber": "30A 99999",
    "carCompany": "HYUNDAI",
    "carModel": "ACCENT"
} 

f. Ví dụ curl

curl --location 'https://api.aicycle.ai/insurance/v2/claimfolders/check-folder-external' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--data '{
    "externalSessionId": "Hoso1",
    "licensePlate": "30A-9999"
}'

3.17: API tích hợp Buy Me - Upload ảnh đăng kiểm xe

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/v2/buy-me/vehicle-inspection/upload
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body (form-data)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
img File ảnh đăng kiểm xe Bắt buộc File n
externalSessionId Id folder (giấy chứng nhận) của đối tác Optional Text n Hoso1
carCompany Mã (tên) hãng xe của khách hàng cần validate Optional Text 1,255 TOYOTA
carModel Mã (tên) hiệu xe của khách hàng cần validate Optional Text 1,255 VIOS
isValidate Flag bật tắt validate hãng xe, hiệu xe Optional Boolean n true

c. Chi tiết đầu ra

{
    "errorCodeFromEngine": <Mã lỗi trả về từ AICycle Engine (Number)>,
    "errorMessage": <Message lỗi (String)>,
    "claimId": <ID hồ sơ AIcycle (Number)>,
    "vehicleInspectionOcrId": <ID kết quả OCR đăng kiểm (Number)>,
    "carCompany": <Hãng xe nhận diện được (String)>,
    "carModel": <Hiệu xe nhận diện được (String)>,
    "result": {
        "imgUrl": <Link ảnh đăng kiểm (String)>,
        "predictedCarInfo": <Thông tin OCR đăng kiểm - tham khảo cấu trúc response mục 2.9>
    },
    "errorLevel": <Mức độ kết quả: "success" | "warning" | "error" (String)>
}







Chi tiết Bảng Mã lỗi cùng httpStatus trả về của errorCodeFromEngine

Chú thích

Với những lỗi có level là error sẽ chỉ trả ra mã lỗi và message lỗi, những lỗi level warning sẽ trả ra mã lỗi, message, và thông tin xe như bình thường

Mã lỗi HTTP Status Response body Level lỗi
0 200 Ảnh hợp lệ
22155 200 {"errorCodeFromEngine": 22155, "message": "Ảnh không cùng 1 xe"} Warning
95889 400 {"errorCodeFromEngine": 95889, "message": "Ảnh không cùng 1 xe"} Error

d. Ví dụ đầu ra

{
    "errorCodeFromEngine": 0,
    "errorMessage": "",
    "claimId": 114041,
    "vehicleInspectionOcrId": 4102,
    "carCompany": "TOYOTA",
    "carModel": "VIOS",
    "result": {
        "imgUrl": "{{imgUrl}}",
        "predictedCarInfo": {
            "vehicleType": "car",
            "registrationNumber": "14A-037.78",
            "inspectionNumber": "1401D-041799",
            "typeValue": "ô tô con",
            "markValue": "TOYOTA",
            "modelCode": "VIOS NCP93LBEMRKU",
            "engineNumber": "1NZ-Y443766",
            "chassisNumber": "RL4BT9232C9517264",
            "manufacturedYearCountry": "2012, Việt Nam",
            "wheelFormula": "4x2",
            "typeOfFuel": "Xăng",
            "engineDisplacement": "1497",
            "seriNumber": "DA 1318080",
            "docNumber": "8839744555",
            "isValidDocument": true,
            "carCompany": "TOYOTA",
            "carModel": "VIOS",
            "carVersion": null,
            "manufactureYear": "2012",
            "suggestedVersions": [
                {
                    "codebookName": "TOYOTA VIOS LIMO",
                    "carCompany": "TOYOTA",
                    "carModel": "VIOS",
                    "carVersion": "LIMO",
                    "manufactureYear": 2012,
                    "carType": "SEDAN",
                    "score": 0.8667
                },
                {
                    "codebookName": "TOYOTA VIOS 1.5G AT",
                    "carCompany": "TOYOTA",
                    "carModel": "VIOS",
                    "carVersion": "1.5G AT",
                    "manufactureYear": 2012,
                    "carType": "SEDAN",
                    "score": 0.4157
                }
            ]
        }
    },
    "errorLevel": "success"
}






















f. Ví dụ curl

curl --location 'https://api.aicycle.ai/insurance/v2/buy-me/vehicle-inspection/upload' \
--header 'Authorization: Bearer $$API_KEY$$' \
--form 'img=@"${fileImage}"' \
--form 'externalSessionId="${externalId}"' \
--form 'carCompany="TOYOTA"' \
--form 'carModel="VIOS"' \
--form 'isValidate="true"'

3.18: API tích hợp Buy Me - Lấy ảnh theo góc chụp

a. Thông tin cơ bản

Method GET
API Url https://api.aicycle.ai/insurance/v2/claimfolders/directional-images
API Headers { "Authorization": "Bearer $API_KEY$" }

b. Chi tiết đầu vào

Loại đầu vào: Query params

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
direction Slug góc chụp (xem bảng bên dưới). Nếu không truyền, API sẽ trả về tất cả ảnh có trong hồ sơ Optional Text 1,255 45-trai-truoc-C1xM02
externalSessionId Id folder của đối tác Optional Text n Hoso1

Các giá trị của direction

directionName directionSlug
Trước truoc-sT9qgX
45° Phải - Trước 45-phai-truoc-UoYzs6
45° Trái - Trước 45-trai-truoc-C1xM02
Sau sau-htBwjB
45° Phải - Sau 45-phai-sau-fRzY3r
45° Trái - Sau 45-trai-sau-1q3G3J
Phải phai-4wif2Z
Trái trai-MyuVUE
Tem đăng kiểm tem-dang-kiem-LC81Ar
Taplo tap-lo-H4SHs1
Số khung so-khung-qmqAsM
Đăng kiểm xe dang-kiem-xe-82YjAa

c. Chi tiết đầu ra

{
    "directionalImages": [<Image>],
    "damageInDirection": [<DamageInDirection>],
    "hasDamageImage": true,
    "hasWarningImage": true
}









Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
directionalImages Danh sách các ảnh theo góc chụp Bắt buộc Array[Image] n
damageInDirection Danh sách tổn thất có trong góc chụp Tùy chọn Array[DamageInDirection] n
hasDamageImage Góc chụp hiện tại có ảnh tổn thất không (chỉ trả ra khi truyền góc chụp direction) Tùy chọn Boolean n true
hasWarningImage Góc chụp hiện tại có ảnh bị lỗi không (chỉ trả ra khi truyền góc chụp direction) Tùy chọn Boolean n true

Chi tiết Object item Image

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
imageId ID của ảnh Bắt buộc Number n 771342
imageUrl Link ảnh Bắt buộc Text 1,255 {{s3Link}}
directionSlug Slug góc chụp Bắt buộc Text 1,255 45-trai-truoc-C1xM02
positionSlug Slug vị trí chụp Tùy chọn Text 1,255 toan-canh-afh4l5

Chi tiết Object item DamageInDirection

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehiclePartExcelId Mã bộ phận xe (Excel ID) Bắt buộc Text 1,255 MaBoPhan
vehiclePartName Tên bộ phận xe Bắt buộc Text 1,255 Tên bộ phận
damages Danh sách các tổn thất Bắt buộc Array[Object] n
images Danh sách ảnh chứa tổn thất Bắt buộc Array[Object] n

Chi tiết Object item trong damages của DamageInDirection

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
damageSlug Mã loại tổn thất Bắt buộc Text 1,255 MaTonThat
damageName Tên loại tổn thất Bắt buộc Text 1,255 Tên tổn thất

Chi tiết Object item trong images của DamageInDirection

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
imageId ID của ảnh tổn thất Bắt buộc Number n 771340
imageUrl Link ảnh tổn thất Bắt buộc Text 1,255 {{s3Link}}

d. Ví dụ đầu ra

Khi không truyền tham số direction:

{
    "directionalImages": [
        {
            "imageId": 771342,
            "imageUrl": "{{s3Link}}",
            "directionSlug": "45-trai-truoc-C1xM02",
            "positionSlug": "toan-canh-afh4l5"
        }
    ]
}

Khi truyền tham số direction:

{
    "directionalImages": [
        {
            "imageId": 771342,
            "imageUrl": "{{s3Link}}",
            "positionSlug": "toan-canh-afh4l5"
        }
    ],
    "damageInDirection": [
        {
            "vehiclePartExcelId": "MaBoPhan",
            "vehiclePartName": "Tên bộ phận",
            "damages": [
                {
                    "damageSlug": "MaTonThat",
                    "damageName": "Tên tổn thất"
                }
            ],
            "images": [
                {
                    "imageId": 771340,
                    "imageUrl": "{{s3Link}}"
                },
                {
                    "imageId": 771342,
                    "imageUrl": "{{s3Link}}"
                },
                {
                    "imageId": 771341,
                    "imageUrl": "{{s3Link}}"
                }
            ]
        },
        {
            "vehiclePartExcelId": "MaBoPhan",
            "vehiclePartName": "Tên bộ phận",
            "damages": [
                {
                    "damageSlug": "MaTonThat",
                    "damageName": "Tên tổn thất"
                },
                {
                    "damageSlug": "MaTonThat",
                    "damageName": "Tên tổn thất"
                }
            ],
            "images": [
                {
                    "imageId": 771340,
                    "imageUrl": "{{s3Link}}"
                },
                {
                    "imageId": 771341,
                    "imageUrl": "{{s3Link}}"
                },
                {
                    "imageId": 771342,
                    "imageUrl": "{{s3link}}"
                }
            ]
        }
    ],
    "hasDamageImage": true,
    "hasWarningImage": false
}

f. Ví dụ curl

curl --location 'https://api.aicycle.ai/insurance/v2/claimfolders/directional-images?direction=45-trai-truoc-C1xM02&externalSessionId=Hoso1' \
--header 'Authorization: Bearer $API_KEY$'

3.19: API tích hợp Buy Me - Lấy thông tin xe

a. Thông tin cơ bản

Method GET
API Url https://api.aicycle.ai/insurance/v2/claimfolders/car-info
API Headers { "Authorization": "Bearer $API_KEY$" }

b. Chi tiết đầu vào

Loại đầu vào: Query params

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
externalSessionId Id folder của đối tác Optional Text n Hoso1

c. Chi tiết đầu ra

{
    "carCompany": <Hãng xe (String)>,
    "carModel": <Hiệu xe (String)>,
    "carColor": <Màu xe theo mã RGB (Array[number])>,
    "plateNumber": <Biển số xe (String)>,
    "vinNumber": <Số khung xe (String)>,
    "odo": <Số km đồng hồ (Number)>,
    "folderCheatWariningMessage": <Cảnh báo gian lận (String)>,
    "predictedCarInfo": <Thông tin OCR đăng kiểm xe - tham khảo mục 2.9>,
    "cheatImages": <Danh sách ảnh lỗi/gian lận (Array[Object])>,
    "folderCheatCodes": <Danh sách mã lỗi gian lận của folder (Array[Object])>,
    "hasDamageImage": < Folder có ảnh tổn thất hay không (Boolean)>
}









Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompany Hãng xe Bắt buộc Text 1,255 KIA
carModel Hiệu xe Bắt buộc Text 1,255 MORNING
carColor Màu xe theo mã RGB Bắt buộc Array[number] n [162, 168, 160]
plateNumber Biển số xe Bắt buộc Text 1,255 30E 96544
vinNumber Số khung xe Bắt buộc Text 1,255 RL4BT123456789
odo Số km đồng hồ Bắt buộc Number n 63907
folderCheatWariningMessage Cảnh báo gian lận Tùy chọn Text 1,255 Hồ sơ có thể được chụp trong không gian tối…
predictedCarInfo Thông tin OCR đăng kiểm xe Bắt buộc Object n Tham khảo mục 2.9
cheatImages Danh sách ảnh lỗi Bắt buộc Array[Object] n Xem chi tiết ví dụ đầu ra bên dưới
folderCheatCodes Danh sách mã lỗi của folder Bắt buộc Array[Object] n Xem chi tiết danh sách mã lỗi tại mục e
hasDamageImage Folder có ảnh tổn thất hay không Bắt buộc Boolean n true

d. Ví dụ đầu ra

{
    "carCompany": "KIA",
    "carModel": "MORNING",
    "plateNumber": "30E 96544",
    "carColor": [
        147,
        148,
        138
    ],
    "vinNumber": null,
    "odo": null,
    "predictedCarInfo": null,
    "folderCheatWariningMessage": "Thông tin xe nhận diện khác với thông tin khai báo. Hãy kiểm tra lại để đảm bảo không có gian lận",
    "cheatImages": [
        {
            "imageId": 771325,
            "status": "error",
            "presignedUrl": "{{s3Link}}",
            "errorMessage": "Ảnh chụp qua màn hình. Vui lòng chụp lại",
            "errorCode": 84680
        }
    ],
    "folderCheatCodes": [
        {
            "errorCode": 41074,
            "errorMessage": "Ảnh không đúng với thông tin gửi lên"
        },
        {
            "errorCode": 84680,
            "errorMessage": "Ảnh chụp qua màn hình"
        },
        {
            "errorCode": 21115,
            "errorMessage": "Ảnh thiếu bộ phận"
        }
    ],
    "hasDamageImage": true
}

e. Phụ lục: Danh sách mã lỗi của Folder

Dưới đây là danh sách toàn bộ các mã lỗi của folder (trả về trong mảng folderCheatCodes):

Mã lỗi Ý nghĩa / Thông báo lỗi
95889 Ảnh không cùng 1 xe
41074 Ảnh không đúng với thông tin gửi lên (trả ra trong trường hợp org config loại lỗi là warning)
22155 Ảnh không cùng 1 xe (trả ra trong trường hợp org config loại lỗi là warning)
84680 Ảnh chụp qua màn hình
37143 Ảnh không phải xe
40412 Ảnh chụp bị mờ
77704 Ảnh chụp bị loá
11267 Ảnh không đúng với thông tin gửi lên
23212 Ảnh chụp bị tối
21115 Ảnh thiếu bộ phận

f. Ví dụ curl

curl --location 'https://api.aicycle.ai/insurance/v2/claimfolders/car-info?externalSessionId=Hoso1' \
--header 'Authorization: Bearer $API_KEY$'

3.20: API tích hợp Buy Me - Validate ảnh trong hồ sơ

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/v2/claimfolders/directional-images/validate
API Headers { "Authorization": "Bearer $API_KEY$", "Content-Type": "application/json" }

b. Chi tiết đầu vào

Loại đầu vào: Body (JSON)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
externalSessionId Id folder của đối tác Bắt buộc Text n HoSo1

c. Chi tiết đầu ra

API trả về kết quả kiểm tra xem hồ sơ đã chụp đủ ảnh theo các góc yêu cầu hay chưa.

d. Ví dụ đầu ra

{
    "message": "Bạn chưa chụp ảnh góc toàn cảnh đầu xe. Vui lòng đứng chính giữa, lùi lại 1.5m và chụp trọn vẹn đầu xe",
    "name": "BadRequestError",
    "status": 400,
    "traceId": "123"
}

f. Ví dụ curl

curl --location 'https://api.aicycle.ai/insurance/v2/claimfolders/directional-images/validate' \
--header 'Authorization: Bearer $API_KEY$' \
--header 'Content-Type: application/json' \
--data '{
    "externalSessionId": "Hoso1"
}'

3.21: API tích hợp Buy Me - Xoá ảnh theo ID

a. Thông tin cơ bản

Method DELETE
API Url https://api.aicycle.ai/insurance/claimimages/{id}
API Headers { "Authorization": "Bearer $API_KEY$", "Content-Type": "application/json" }

b. Chi tiết đầu vào

Path param

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id ID của ảnh cần xoá Bắt buộc Number n 3132

Query params

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
direction Slug góc chụp (xem bảng bên dưới). Nếu không truyền, API sẽ xoá ảnh xe. Muốn xoá các loại ảnh khác (đăng kiểm, số khung, …) cần truyền thêm góc chụp tương ứng Optional Text 1,255 dang-kiem-xe-82YjAa

Các giá trị của direction

directionName directionSlug
Trước truoc-sT9qgX
45° Phải - Trước 45-phai-truoc-UoYzs6
45° Trái - Trước 45-trai-truoc-C1xM02
Sau sau-htBwjB
45° Phải - Sau 45-phai-sau-fRzY3r
45° Trái - Sau 45-trai-sau-1q3G3J
Phải phai-4wif2Z
Trái trai-MyuVUE
Tem đăng kiểm tem-dang-kiem-LC81Ar
Taplo tap-lo-H4SHs1
Số khung so-khung-qmqAsM
Đăng kiểm xe dang-kiem-xe-82YjAa

c. Chi tiết đầu ra

API trả về HTTP 204 No Content khi xoá thành công, không có nội dung trong response body.

f. Ví dụ curl

curl --location --request DELETE 'https://api.aicycle.ai/insurance/claimimages/3132?direction=dang-kiem-xe-82YjAa' \
--header 'Authorization: Bearer $API_KEY$' \
--header 'Content-Type: application/json'

3.22: API tích hợp Buy Me - Xoá nhiều ảnh

a. Thông tin cơ bản

Method DELETE
API Url https://api.aicycle.ai/insurance/claimimages/bulk
API Headers { "Authorization": "Bearer $API_KEY$", "Content-Type": "application/json" }

b. Chi tiết đầu vào

Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
images Danh sách các ảnh cần xoá Bắt buộc Array n

Chi tiết item trong mảng images

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id ID của ảnh cần xoá Bắt buộc Number n 770432
direction Slug góc chụp (xem bảng mục 3.21). Nếu không truyền, API sẽ xoá ảnh xe. Muốn xoá các loại ảnh khác (đăng kiểm, số khung, …) cần truyền thêm góc chụp tương ứng Optional Text 1,255 dang-kiem-xe-82YjAa

c. Chi tiết đầu ra

API trả về HTTP 204 No Content khi xoá thành công, không có nội dung trong response body.

d. Ví dụ curl

curl --location --request DELETE 'https://api.aicycle.ai/insurance/claimimages/bulk' \
--header 'Authorization: Bearer $API_KEY$' \
--header 'Content-Type: application/json' \
--data '{
    "images": [
        {
            "id": 770432
        },
        {
            "id": 522,
            "direction": "dang-kiem-xe-82YjAa"
        },
        {
            "id": 125,
            "direction": "so-khung-qmqAsM"
        },
        {
            "id": 243,
            "direction": "tem-dang-kiem-LC81Ar"
        },
        {
            "id": 188,
            "direction": "tap-lo-H4SHs1"
        }
    ]
}'

3.23: API tích hợp Buy Me/Claim Me - Xoá vết hỏng của bộ phận

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/v2/claimfolders/{externalSessionId}/vehicle-parts/remove-damages
API Headers { "Authorization": "Bearer $API_KEY$", "Content-Type": "application/json" }

b. Chi tiết đầu vào

Loại đầu vào: Body & Params

Chi tiết Params:

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
externalSessionId Mã hồ sơ/folder của khách hàng Bắt buộc Text 1,255 HoSoKhachHang1

Chi tiết Body:

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
deleteSlug Danh sách thông tin bộ phận và vết hỏng cần xoá Bắt buộc Array[deleteSlugItem] n

Chi tiết Object deleteSlugItem

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehiclePartSlug Mã định danh bộ phận xe cần xoá tổn thất Bắt buộc Text 1,255 MaBoPhan
vehiclePartName Tên bộ phận xe cần xoá tổn thất. Dùng để phân biệt các bộ phận có cùng vehiclePartSlug nhưng khác tên. Optional Text 1,255 Cản trước
damageSlug Danh sách mã tổn thất cần xoá của bộ phận tương ứng Bắt buộc Array[Text] n [“MaHongHoc”]

c. Chi tiết đầu ra

API trả về HTTP 204 OK khi xoá thành công.

d. Ví dụ curl

curl --location 'https://api.aicycle.ai/insurance/v2/claimfolders/HoSoKhachHang1/vehicle-parts/remove-damages' \
--header 'Authorization: Bearer $API_KEY$' \
--header 'Content-Type: application/json' \
--data '{
    "deleteSlug": [
        {
            "vehiclePartSlug": "MaBoPhan",
            "vehiclePartName": "Cản trước",
            "damageSlug": [
                "MaHongHoc"
            ]
        }
    ]
}
'

3.24: API chỉnh sửa tổn thất của bộ phận

Lưu ý: Sau khi chỉnh sửa thành công bằng API này, vui lòng kiểm tra lại trường editedDamages trong kết quả trả về của API 3.14.

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/v2/claimfolders/{externalSessionId}/external-segment-result
API Headers { "Authorization": "Bearer $API_KEY$", "Content-Type": "application/json" }

b. Chi tiết đầu vào

Loại đầu vào: Body & Params

Chi tiết Params:

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
externalSessionId Mã hồ sơ/folder của khách hàng Bắt buộc Text 1,255 MaHoSo

Chi tiết Body:

Body là một mảng (Array) các đối tượng (Object) chứa thông tin cần cập nhật.

Chi tiết từng Object trong mảng:

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
partSlug Mã bộ phận Bắt buộc Text 1,255 MaBoPhan
editedDamages Danh sách mã hỏng hóc (tổn thất) và phương án sửa chữa muốn update cho hạng mục Bắt buộc Array[Object] n [{"damageCode": "MaHongHoc1", "repairMethodCode": "PhuongAn1"}]

Chi tiết từng Object trong mảng editedDamages:

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
damageCode Mã tổn thất Bắt buộc Text 1,255 MaHongHoc1
repairMethodCode Mã phương án sửa chữa Bắt buộc Text 1,255 PhuongAn1

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
externalSessionId Mã hồ sơ Bắt buộc Text 1,255 MaHoSo
{
    "externalSessionId": "MaHoSo"
}

d. Ví dụ curl

curl --location --request POST 'https://api.aicycle.ai/insurance/v2/claimfolders/VBIClaimMe74/external-segment-result' \
--header 'Authorization: Bearer $API_KEY$' \
--header 'Content-Type: application/json' \
--data '[
    {
        "partSlug": "MaBoPhan",
        "editedDamages": [
            {
                "damageCode": "MaHongHoc1",
                "repairMethodCode": "PhuongAn1"
            },
            {
                "damageCode": "MaHongHoc2",
                "repairMethodCode": "PhuongAn2"
            }
        ]
    }
]'

3.25: API nhận diện màu biển số xe

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/vehicle/license-plate-color' \
--header 'Authorization: Bearer ${APIKEY}' \
--form 'img=@"${fileImage1}"' \
--form 'img=@"${fileImage2}"' \
--form 'externalSessionId="${externalId}"'
Method POST
API Url https://api.aicycle.ai/insurance/v2/vehicle/license-plate-color
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body (form data)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
img File ảnh xe. Tối đa 3 ảnh Bắt buộc File 1,3
externalSessionId Mã hồ sơ của đối tác Optional Text n MaHoSo

c. Chi tiết đầu ra

{
    "results": [<Result>]
}







Danh sách results có thứ tự tương ứng với thứ tự các ảnh đã upload.

Chi tiết Object item Result

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
imageUrl Link ảnh Bắt buộc Text 1,255 {{s3Link}}
color Màu biển số xe. Trả null khi ảnh có lỗi Bắt buộc Text n white
errorCode Mã lỗi, 0 nếu ảnh xử lý thành công Bắt buộc Number n 0
errorMessage Nội dung lỗi, rỗng nếu ảnh xử lý thành công Bắt buộc Text n

Các giá trị của color

color Màu biển số
blue Xanh
red Đỏ
white Trắng
yellow Vàng

Các mã lỗi errorCode

errorCode errorMessage
37143 Không xác nhận được xe
37144 Không phát hiện biển số xe
32324 Không download được ảnh

Mã HTTP trả về

d. Ví dụ đầu ra

{
    "results": [
        {
            "imageUrl": "https://dyta7vmv7sqle.cloudfront.net/INSURANCE_IMAGES/LICENSE_PLATE_COLOR/plate-1.jpg",
            "color": "white",
            "errorCode": 0,
            "errorMessage": ""
        },
        {
            "imageUrl": "https://dyta7vmv7sqle.cloudfront.net/INSURANCE_IMAGES/LICENSE_PLATE_COLOR/plate-2.jpg",
            "color": null,
            "errorCode": 37144,
            "errorMessage": "Không phát hiện biển số xe"
        }
    ]
}

4. APIs tích hợp OCR

4.1 API OCR căn cước công dân

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/ocr/identification-card' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--data '{
    "frontFilePath": "OCR_IMAGES/front-img-1.jpg",
    "rearFilePath": "OCR_IMAGES/rear-img-2.jpg"
}'
Method POST
API Url https://api.aicycle.ai/insurance/v2/ocr/identification-card
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
frontFilePath Path ảnh mặt trước cccd trên s3 (lấy từ kết quả trả về của API get imageUrl ở mục 3.3) Bắt buộc Text 1,255 OCR_IMAGES/front-image-1.jpg
rearFilePath Path ảnh mặt sau cccd trên s3 (lấy từ kết quả trả về của API get imageUrl ở mục 3.3) Bắt buộc Text 1,255 OCR_IMAGES/rear-image-1.jpg

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "frontImgUrl": <Url ảnh mặt trước cccd (String)>,
    "rearImgUrl": <Url ảnh mặt sau cccd (String)>,
    "cardNumber": <Mã số định danh (String)>,
    "fullName": <Họ và tên (String)>,
    "dob": <Ngày, tháng, năm sinh (String)>,
    "gender": <Giới tính (String)>,
    "nationality": <Quốc tịch (String)>,
    "homeTown": <Quê quán (String)>,
    "duration":  <Ngày hết hạn (String)>,
    "placeOfResidence": <Nơi cấp (String)>,
    "identifyingCharacteristics": <Đặc điểm nhận dạng (String)>,
    "dateIssuance": <Ngày cấp (String)>
}






d. Ví dụ đầu ra


{
    "status": "success",
    "frontImgUrl": "{{s3Url}}",
    "rearImgUrl": "{{s3Url}}",
    "problem": "",
    "isValidDocument": true,
    "cardNumber": "0123456789012",
    "fullName": "Nguyễn Văn A",
    "dob": "01/02/2003",
    "gender": "Nam",
    "nationality": "Việt Nam",
    "homeTown": "Làng Nhì, Trạm Tàu, Yên Bái",
    "duration": "01/02/2003",
    "placeOfResidence": "Thôn Láng Nhĩ Làng Nhì Tram Tầu, Yên Bái",
    "identifyingCharacteristics": "Sẹo chấm C:1cm trên sau đầu lông mày trái",
    "dateIssuance": "01/02/2003"
}










4.2 API OCR đăng kiểm xe

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/ocr/vehicle-inspection' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--data '{
    "filePath": "OCR_IMAGES/img-2.jpg",
}'
Method POST
API Url https://api.aicycle.ai/insurance/v2/ocr/vehicle-inspection
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
filePath Path ảnh đăng kiểm trên s3 (lấy từ kết quả trả về của API get imageUrl ở mục 3.3) Bắt buộc Text 1,255 OCR_IMAGES/image-2.jpg

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "imgUrl": <Url ảnh đăng kiểm (String)>,
    "registrationNumber": <Biển đăng ký (String)>,
    "inspectionNumber": <Số quản lý  (String)>,
    "typeValue": <Loại xe  (String)>,
    "markValue": <Nhãn hiệu (String)>,
    "modelCode": <Số loại (String)>,
    "engineNumber": <Số máy (String)>,
    "chassisNumber":  <Số khung (String)>,
    "manufacturedYearCountry": <Năm, nơi sản xuất (String)>,
    "wheelFormula": <Công thức bánh xe (String)>,
    "typeOfFuel": <Loại nhiên liệu (String)>,
    "engineDisplacement": <Dung tích động cơ (String)>
}






d. Ví dụ đầu ra


{
    "status": "success",
    "imgUrl": "{{s3Url}}",
    "problem": "",
    "isValidDocument": true,
    "registrationNumber": "01A-012.34",
    "inspectionNumber": "01A-012.34",
    "typeValue": "ô tô con",
    "modelCode": "VIOS123456",
    "engineNumber": "1AB-CDEF",
    "chassisNumber": "ABCD123456",
    "manufacturedYearCountry": "2012,Việt Nam",
    "wheelFormula": "4x2",
    "typeOfFuel": "Xăng",
    "engineDisplacement": "1000 (cm3)"
}










4.3 API OCR giấy phép lái xe

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/ocr/driving-license' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--data '{
    "filePath": "OCR_IMAGES/img-3.jpg",
}'
Method POST
API Url https://api.aicycle.ai/insurance/v2/ocr/driving-license
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
filePath Path ảnh giấy phép lái xe trên s3 (lấy từ kết quả trả về của API get imageUrl ở mục 3.3) Bắt buộc Text 1,255 OCR_IMAGES/image-3.jpg

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "imgUrl": <Url ảnh đăng kiểm (String)>,
    "cardNumber": <Số thẻ (String)>,
    "fullName": <Họ và tên  (String)>,
    "dob": <Ngày, tháng , năm sinh  (String)>,
    "nationality": <Quốc tịch (String)>,
    "placeOfResidence": <Nơi cư trú (String)>,
    "placeIssuance": <Nơi cấp (String)>,
    "dateIssuance":  <Ngày cấp (String)>,
    "rank": <Hạng (String)>,
    "duration": <Ngày hết hạn (String)>,
}







{
    "status": "success",
    "imgUrl": "{{s3Url}}",
    "problem": "",
    "isValidDocument": true,
    "cardNumber": "0123456789",
    "fullName": "Nguyễn Văn A",
    "dob": "01/02/2003",
    "nationality": "VIỆT NAM",
    "placeOfResidence": "Số 1, đường Nguyễn Văn A, Q.Đống Đa, Hà Nội",
    "placeIssuance": "Hà Nội",
    "dateIssuance": "01/01/2000",
    "rank": "C",
    "duration": "01/01/2000"
}











4.4 API OCR đăng ký xe

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/ocr/vehicle-registration' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--data '{
    "filePath": "OCR_IMAGES/img-3.jpg",
}'
Method POST
API Url https://api.aicycle.ai/insurance/v2/ocr/vehicle-registration
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
filePath Path ảnh đăng ký xe trên s3 (lấy từ kết quả trả về của API get imageUrl ở mục 3.3) Bắt buộc Text 1,255 OCR_IMAGES/image-3.jpg

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "imgUrl": <Url ảnh đăng ký xe (String)>,
    "name": <Họ và tên (String)>,
    "address": <Địa chỉ  (String)>,
    "modelCode": <Số loại (String)>,
    "brand": <Hãng xe (String)>,
    "engine": <Động cơ (String)>,
    "chassis": <Số khung (String)>,
    "color":  <Màu xe (String)>,
    "plate": <Biển số (String)>,
    "place": <Nơi cấp (String)>,
    "date": <Ngày cấp (String)>
}






d. Ví dụ đầu ra


{
    "status": "success",
    "imgUrl": "{{s3Url}}",
    "problem": "",
    "isValidDocument": true,
    "name": "Nguyễn Văn A",
    "address": "TDP Dộc, Tây Mỗ, Nam Từ Liêm, HIN",
    "modelCode": "VIOS",
    "brand": "TOYOTA",
    "engine": "ABC123456",
    "chassis": "12345678",
    "color": "Đen",
    "plate": "30E-111.11",
    "place": "Hà Nội",
    "date": "01/01/2011"
}










4.5 API OCR căn cước công dân (form-data)

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/ocr/identification-card/upload' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--form 'frontImg=@"$imgFilePathInLocalMachine"' \
--form 'rearImg=@"$imgFilePathInLocalMachine"'
Method POST
API Url https://api.aicycle.ai/insurance/v2/ocr/identification-card/upload
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Form Data

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
frontImg Ảnh mặt trước cccd Bắt buộc File n
rearImg Ảnh mặt sau cccd Bắt buộc File n

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "frontImgUrl": <Url ảnh mặt trước cccd (String)>,
    "rearImgUrl": <Url ảnh mặt sau cccd (String)>,
    "cardNumber": <Mã số định danh (String)>,
    "fullName": <Họ và tên (String)>,
    "dob": <Ngày, tháng, năm sinh (String)>,
    "gender": <Giới tính (String)>,
    "nationality": <Quốc tịch (String)>,
    "homeTown": <Quê quán (String)>,
    "duration":  <Ngày hết hạn (String)>,
    "placeOfResidence": <Nơi cấp (String)>,
    "identifyingCharacteristics": <Đặc điểm nhận dạng (String)>,
    "dateIssuance": <Ngày cấp (String)>
}






d. Ví dụ đầu ra


{
    "status": "success",
    "frontImgUrl": "{{s3Url}}",
    "rearImgUrl": "{{s3Url}}",
    "problem": "",
    "isValidDocument": true,
    "cardNumber": "0123456789012",
    "fullName": "Nguyễn Văn A",
    "dob": "01/02/2003",
    "gender": "Nam",
    "nationality": "Việt Nam",
    "homeTown": "Làng Nhì, Trạm Tàu, Yên Bái",
    "duration": "01/02/2003",
    "placeOfResidence": "Thôn Láng Nhĩ Làng Nhì Tram Tầu, Yên Bái",
    "identifyingCharacteristics": "Sẹo chấm C:1cm trên sau đầu lông mày trái",
    "dateIssuance": "01/02/2003"
}










4.6 API OCR đăng kiểm xe (form-data)

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/ocr/vehicle-inspection/upload' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--form 'img=@"$imgFilePathInLocalMachine"'
Method POST
API Url https://api.aicycle.ai/insurance/v2/ocr/vehicle-inspection/upload
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Form Data

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
img Ảnh đăng kiểm Bắt buộc File n

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "imgUrl": <Url ảnh đăng kiểm (String)>,
    "registrationNumber": <Biển đăng ký (String)>,
    "inspectionNumber": <Số quản lý  (String)>,
    "typeValue": <Loại xe  (String)>,
    "markValue": <Nhãn hiệu (String)>,
    "modelCode": <Số loại (String)>,
    "engineNumber": <Số máy (String)>,
    "chassisNumber":  <Số khung (String)>,
    "manufacturedYearCountry": <Năm, nơi sản xuất (String)>,
    "wheelFormula": <Công thức bánh xe (String)>,
    "typeOfFuel": <Loại nhiên liệu (String)>,
    "engineDisplacement": <Dung tích động cơ (String)>
}






d. Ví dụ đầu ra


{
    "status": "success",
    "imgUrl": "{{s3Url}}",
    "problem": "",
    "isValidDocument": true,
    "registrationNumber": "01A-012.34",
    "inspectionNumber": "01A-012.34",
    "typeValue": "ô tô con",
    "modelCode": "VIOS123456",
    "engineNumber": "1AB-CDEF",
    "chassisNumber": "ABCD123456",
    "manufacturedYearCountry": "2012,Việt Nam",
    "wheelFormula": "4x2",
    "typeOfFuel": "Xăng",
    "engineDisplacement": "1000 (cm3)"
}










4.7 API OCR giấy phép lái xe (form-data)

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/ocr/driving-license/upload' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--form 'img=@"$imgFilePathInLocalMachine"''
Method POST
API Url https://api.aicycle.ai/insurance/v2/ocr/driving-license/upload
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Form Data

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
img Ảnh giấy phép lái xe Bắt buộc File n

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "imgUrl": <Url ảnh đăng kiểm (String)>,
    "cardNumber": <Số thẻ (String)>,
    "fullName": <Họ và tên  (String)>,
    "dob": <Ngày, tháng , năm sinh  (String)>,
    "nationality": <Quốc tịch (String)>,
    "placeOfResidence": <Nơi cư trú (String)>,
    "placeIssuance": <Nơi cấp (String)>,
    "dateIssuance":  <Ngày cấp (String)>,
    "rank": <Hạng (String)>,
    "duration": <Ngày hết hạn (String)>,
}





d. Ví dụ đầu ra


{
    "status": "success",
    "imgUrl": "{{s3Url}}",
    "problem": "",
    "isValidDocument": true,
    "cardNumber": "0123456789",
    "fullName": "Nguyễn Văn A",
    "dob": "01/02/2003",
    "nationality": "VIỆT NAM",
    "placeOfResidence": "Số 1, đường Nguyễn Văn A, Q.Đống Đa, Hà Nội",
    "placeIssuance": "Hà Nội",
    "dateIssuance": "01/01/2000",
    "rank": "C",
    "duration": "01/01/2000"
}









4.8 API OCR đăng ký xe (form-data)

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/v2/ocr/vehicle-registration/upload' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--form 'img=@"$imgFilePathInLocalMachine"''
Method POST
API Url https://api.aicycle.ai/insurance/v2/ocr/vehicle-registration/upload
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Form Data

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
img Ảnh đăng ký xe Bắt buộc File n

c. Chi tiết đầu ra

{
    "status": <Trạng thái của Request (String)>,
    "imgUrl": <Url ảnh đăng ký xe (String)>,
    "name": <Họ và tên (String)>,
    "address": <Địa chỉ  (String)>,
    "modelCode": <Số loại (String)>,
    "brand": <Hãng xe (String)>,
    "engine": <Động cơ (String)>,
    "chassis": <Số khung (String)>,
    "color":  <Màu xe (String)>,
    "plate": <Biển số (String)>,
    "place": <Nơi cấp (String)>,
    "date": <Ngày cấp (String)>
}






d. Ví dụ đầu ra


{
    "status": "success",
    "imgUrl": "{{s3Url}}",
    "problem": "",
    "isValidDocument": true,
    "name": "Nguyễn Văn A",
    "address": "TDP Dộc, Tây Mỗ, Nam Từ Liêm, HIN",
    "modelCode": "VIOS",
    "brand": "TOYOTA",
    "engine": "ABC123456",
    "chassis": "12345678",
    "color": "Đen",
    "plate": "30E-111.11",
    "place": "Hà Nội",
    "date": "01/01/2011"
}










4.9 Các API cho định giá xe tải

4.9.1 API lấy list hãng xe

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/vehicles/${vehicleTypeKey}/company' \
--header 'Authorization: Bearer ${API_KEY}' \
--header 'Content-Type: application/json'
Method GET
API Url https://api.aicycle.ai/insurance/vehicles/${vehicleTypeKey}/company
API Headers { "Authorization": "Bearer ${API_KEY}" }

Các giá trị của vehicleTypeKey

vehicleTypeName vehicleTypeKey
Xe chở hàng hóa truck
Xe chuyên dụng specialized
Xe khách coach

b. Chi tiết đầu vào

Loại đầu vào: Query String

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehicleTypeKey Key loại xe Optional Text 1,255 truck
limit Giới hạn số bản ghi trả ra Optional Number 1,99999 30
offset Bỏ qua số bản ghi Optional Number 1,99999 30
companyName Tìm kiếm tên hãng xe Optional Text 1,255 CHENGLONG
orderBy Sort hãng xe Optional Text 1,255 ?orderBy=companyName DESC

c. Chi tiết đầu ra

{
    "count": <Số lượng data trả ra>,
    "limit": <Giới hạn data trả ra>,
    "offset": <Số lượng bản ghi bỏ qua>,
    "records": <Array(truckCompanyObj)>
}





Chi tiết Object item truckCompanyObj

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
companyKey Key hãng xe Bắt buộc Text 1,255 chenglong
companyName Tên hãng xe Bắt buộc Text 1,255 CHENGLONG

4.9.2 API lấy list hiệu xe, phiên bản

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/vehicles/${vehicleTypeKey}/versions' \
--header 'Authorization: Bearer ${API_KEY}' \
--header 'Content-Type: application/json'
Method GET
API Url https://api.aicycle.ai/insurance/vehicles/${vehicleTypeKey}/versions
API Headers { "Authorization": "Bearer ${API_KEY}" }

Các giá trị của vehicleTypeKey

vehicleTypeName vehicleTypeKey
Xe chở hàng hóa truck
Xe chuyên dụng specialized
Xe khách coach

b. Chi tiết đầu vào

Loại đầu vào: Query String

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehicleTypeKey Key loại xe Optional Text 1,255 truck
limit Giới hạn số bản ghi trả ra Optional Number 1,99999 30
offset Bỏ qua số bản ghi Optional Number 1,99999 30
companyName Flag dùng để filter hiệu xe theo hãng xe Optional Text 1,255 CHENGLONG
versionName Flag dùng để tìm kiếm tên hiệu xe, phiên bản Optional Text 1,255 340HP 10X4
orderBy Sort hiệu xe, phiên bản Optional Text 1,255 ?orderBy=versionName DESC

c. Chi tiết đầu ra

{
    "count": <Số lượng data trả ra>,
    "limit": <Giới hạn data trả ra>,
    "offset": <Số lượng bản ghi bỏ qua>,
    "records": <Array(truckVersionObj)>
}





Chi tiết Object item truckVersionObj

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
versionKey Key hiệu xe Bắt buộc Text 1,255 180hp-4x2-thung-vuong
versionName Tên hiệu xe Bắt buộc Text 1,255 180HP 4X2 THÙNG VUÔNG

4.9.3 API lấy các thông tin số loại, mã thùng,… từ hãng, hiệu xe

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/vehicles/${vehicleTypeKey}/codebooks' \
--header 'Authorization: Bearer ${API_KEY}' \
--header 'Content-Type: application/json'
Method GET
API Url https://api.aicycle.ai/insurance/vehicles/${vehicleTypeKey}/codebooks
API Headers { "Authorization": "Bearer ${API_KEY}" }

Các giá trị của vehicleTypeKey

vehicleTypeName vehicleTypeKey
Xe chở hàng hóa truck
Xe chuyên dụng specialized
Xe khách coach

b. Chi tiết đầu vào

Loại đầu vào: Query String

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
vehicleTypeKey Key loại xe Optional Text 1,255 truck
limit Giới hạn số bản ghi trả ra Optional Number 1,99999 30
offset Bỏ qua số bản ghi Optional Number 1,99999 30
companyKey Flag dùng để filter số loại,… theo hãng xe Optional Text 1,255 chenglong
versionKey Flag dùng để filter số loại,… theo hiệu xe, phiên bản Optional Text 1,255 340hp-10x4
orderBy Sort hiệu xe, phiên bản Optional Text 1,255 ?orderBy=modelCode DESC

c. Chi tiết đầu ra

{
    "count": <Số lượng data trả ra>,
    "limit": <Giới hạn data trả ra>,
    "offset": <Số lượng bản ghi bỏ qua>,
    "records": <Array(truckModelCodeObj)>
}





Chi tiết Object item truckModelCodeObj

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
barrelTypeKey Key loại thùng Bắt buộc Text 1,255 chassis
barrelTypeName Tên loại thùng Bắt buộc Text 1,255 Chassis
carTypeKey Key loại xe Bắt buộc Text 1,255 xe-tai
carTypeName Tên loại xe Bắt buộc Text 1,255 Xe tải
barrelTypeKey Key loại thùng Bắt buộc Text 1,255 chassis
modelCode Số loại Bắt buộc Text 1,255 LZ1340PELT
payload Tải trọng Bắt buộc Number 1,99999 22450

4.9.4 API lấy thông tin thùng xe

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/vehicles/barrel' \
--header 'Authorization: Bearer ${API_KEY}' \
--header 'Content-Type: application/json'
Method GET
API Url https://api.aicycle.ai/insurance/vehicles/barrel
API Headers { "Authorization": "Bearer ${API_KEY}" }

b. Chi tiết đầu vào

Loại đầu vào: Query String

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
isAll Flag lấy loại thùng, true là lấy tất cả các thùng, false là chỉ lấy ra loại thùng có giá Optional Boolean n true
limit Giới hạn số bản ghi trả ra Optional Number 1,99999 30
offset Bỏ qua số bản ghi Optional Number 1,99999 30

c. Chi tiết đầu ra

{
    "count": <Số lượng data trả ra>,
    "limit": <Giới hạn data trả ra>,
    "offset": <Số lượng bản ghi bỏ qua>,
    "records": <Array(truckBarrelObj)>
}





Chi tiết Object item truckBarrelObj

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
key Key thùng Bắt buộc Text 1,255 thung-lung-dai-2m2
name Tên thùng Bắt buộc Text 1,255 Thùng Lửng dài 2m2
price Giá thùng Bắt buộc Number 1,99999 40000000
size Size thùng Bắt buộc Text 1,255 dài 2m2

4.9.5 API định giá xe tải

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/vehicles/barrel' \
--header 'Authorization: Bearer ${API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
  "vehicleTypeKey":"truck",
  "companyName":"chenglong",
  "versionName":"340hp-10x4",
  "modelCode":"LZ1340PELT",
  "manufactureYear":"2024",
  "barrelTypeKey":"thung-lung-dai-5m1"
}'
Method POST
API Url https://api.aicycle.ai/insurance/valuation/v3/truck-valuate
API Headers { "Authorization": "Bearer ${API_KEY}" }

b. Chi tiết đầu vào

Loại đầu vào: Request Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
barrelTypeKey Key thùng (lấy từ API 4.9.4) Bắt buộc Text 1,255 thung-lung-dai-5m1
companyName Key hãng xe (lấy từ API 4.9.1) Bắt buộc Text 1,255 chenglong
manufactureYear Năm sản xuất (hỗ trợ từ năm 2000 đến hiện tại) Bắt buộc Text 1,255 2024
modelCode Số loại (lấy từ API 4.9.3) Bắt buộc Text 1,255 LZ1340PELT
vehicleTypeKey Loại xe (truch, coach, specialized) Bắt buộc Text 1,255 truck
versionName Key hiệu xe, phiên bản (lấy từ API 4.9.2) Bắt buộc Text 1,255 340hp-10x4

c. Chi tiết đầu ra

{
    "barrelTypeKey": <Mã thùng>,
    "companyName": <Mã hãng>,
    "manufactureYear": <năm sản xuất>,
    "maxPrice": <Max Price>,
    "minPrice": <Min Price>,
    "modelCode": <Số loại>,
    "price": <Giá trị xe>,
    "vehicleTypeKey": <Mã loại xe>,
    "versionName": <Mã hiệu xe, phiên bản>
}






4.10 API OCR số khung (chassis number) theo form data

a. Thông tin cơ bản

Method POST
API Url https://api.aicycle.ai/insurance/v2/ocr/chassis-number/upload
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Form data

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
img File ảnh số khung cần OCR Bắt buộc File - so_khung.jpeg
externalSessionId ID hồ sơ của khách hàng (nếu có) Tùy chọn Text 1,255 HoSo1

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Kiểu dữ liệu Ví dụ
vinImageId Id của ảnh số khung Number 85
message Thông báo lỗi (nếu có) Text ""
errorCodeFromEngine Mã lỗi từ engine OCR Number 0
errorLevel Trạng thái xử lý Text “success”
result.imgUrl URL ảnh số khung đã upload Text “https://…”
result.vinNumber Số khung đọc được từ ảnh Text “RN2BN4AA6KM023003”
result.carCompanyFromVinNumber Hãng xe đọc được từ ảnh số Vin Text “MAZDA”
result.carModelFromVinNumber Hiệu xe đọc được từ ảnh số Vin Text “3”

d. Chi tiết errorCodeFromEngine

errorCodeFromEngine Mô tả
0 Request thành công
47665 Không đọc được số khung từ ảnh

e. Ví dụ đầu ra

{
    "vinImageId": 85,
    "message": "",
    "errorCodeFromEngine": 0,
    "result": {
        "imgUrl": "${imgUrl}",
        "vinNumber": "RN2BN4AA6KM023003",
        "carCompanyFromVinNumber": "MAZDA",
        "carModelFromVinNumber": "3"
    },
    "errorLevel": "success"
}

f. Ví dụ curl

curl --location 'https://api.aicycle.ai/insurance/v2/ocr/chassis-number/upload' \
--header 'Authorization: Bearer $$API_KEY$$' \
--form 'img=@"/path/to/so_khung.jpeg"'

4.11 API OCR giấy phép lái xe (form-data v1)

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/api/v1/ocr/driving-license' \
--header 'Authorization: Bearer $$API_KEY$$' \
--form 'images=@"$imgFilePathInLocalMachine1"' \
--form 'images=@"$imgFilePathInLocalMachine2"' \
--form 'externalSessionId="HoSo1"'
Method POST
API Url https://api.aicycle.ai/insurance/api/v1/ocr/driving-license
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Form Data

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
images Mảng ảnh giấy phép lái xe (tối đa 2 ảnh mặt trước và mặt sau) Bắt buộc File Tối đa 2
externalSessionId Mã hồ sơ của khách hàng Optional Text 1,255 HoSo1

c. Chi tiết đầu ra

{
    "success": <Trạng thái của Request (Boolean)>,
    "dataContainerKey": <Mã lưu kết quả của lần gọi (String)>,
    "data": [
        {
            "isFront": <Là mặt trước (Boolean)>,
            "documentType": <Loại tài liệu (String)>,
            "imageUrl": <Url ảnh S3 presigned (String)>,
            "details": {
                "loai_vb": <Mã loại văn bản, luôn là bang_lai (String)>,
                "name": <Họ và tên (String)>,
                "dob": <Ngày sinh, định dạng DD/MM/YYYY (String)>,
                "address": <Nơi cư trú (String)>,
                "nationality": <Quốc tịch (String)>,
                "address_town": <Nơi cấp (String)>,
                "id": <Số giấy phép lái xe (String)>,
                "class": <Hạng giấy phép lái xe (String)>,
                "issue_date": <Ngày cấp, định dạng DD/MM/YYYY (String)>,
                "due_date": <Ngày hết hạn, định dạng DD/MM/YYYY (String)>,
                "seat_place": <Số chỗ ngồi tối đa được phép điều khiển, suy ra từ hạng và ngày cấp (Number)>,
                "authorized_total_mass": <Trọng tải tối đa được phép điều khiển, suy ra từ hạng và ngày cấp (Number)>
            }
        }
    ]
}






Trường không đọc được trả null. Khi lỗi, response có dạng { "success": false, "errorCode": "...", "message": "...", "details": null } (ví dụ INVALID_INPUT, INVALID_DOCUMENT_TYPE).

d. Ví dụ đầu ra


{
    "success": true,
    "dataContainerKey": "20260723142221780",
    "data": [
        {
            "isFront": true,
            "documentType": "DRIVING_LICENSE",
            "imageUrl": "https://s3.amazonaws.com/...",
            "details": {
                "loai_vb": "bang_lai",
                "name": "NGUYỄN VĂN A",
                "dob": "01/01/1990",
                "address": "Hà Nội",
                "nationality": "VIỆT NAM",
                "address_town": "Sở GTVT Hà Nội",
                "id": "010123456789",
                "class": "B2",
                "issue_date": "01/01/2020",
                "due_date": "01/01/2030",
                "seat_place": 9,
                "authorized_total_mass": 3500
            }
        }
    ]
}










4.12 API OCR đăng ký xe (form-data v1)

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/api/v1/ocr/vehicle-registration' \
--header 'Authorization: Bearer $$API_KEY$$' \
--form 'images=@"$imgFilePathInLocalMachine1"' \
--form 'images=@"$imgFilePathInLocalMachine2"' \
--form 'externalSessionId="HoSo1"'
Method POST
API Url https://api.aicycle.ai/insurance/api/v1/ocr/vehicle-registration
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Form Data

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
images Mảng ảnh đăng ký xe (tối đa 2 ảnh mặt trước và mặt sau) Bắt buộc File Tối đa 2
externalSessionId Mã hồ sơ của khách hàng Optional Text 1,255 HoSo1

c. Chi tiết đầu ra

{
    "success": <Trạng thái của Request (Boolean)>,
    "dataContainerKey": <Mã lưu kết quả của lần gọi (String)>,
    "data": [
        {
            "isFront": <Là mặt trước (Boolean)>,
            "documentType": <Loại tài liệu (String)>,
            "imageUrl": <Url ảnh S3 presigned (String)>,
            "details": {
                "loai_vb": <Mã loại văn bản, luôn là dang_ky (String)>,
                "name": <Tên chủ xe (String)>,
                "address": <Địa chỉ chủ xe (String)>,
                "plate": <Biển số (String)>,
                "brand": <Nhãn hiệu (String)>,
                "model": <Số loại (String)>,
                "loai_xe": <Loại xe (String)>,
                "color": <Màu sơn (String)>,
                "chassis": <Số khung (String)>,
                "engine": <Số máy (String)>,
                "capacity": <Dung tích (Number)>,
                "sit": <Số chỗ ngồi (Number)>,
                "id": <Số giấy đăng ký (String)>,
                "first_issue_date": <Ngày đăng ký lần đầu, định dạng DD/MM/YYYY (String)>,
                "issued_at": <Nơi cấp (String)>
            }
        }
    ]
}






Trường không đọc được trả null. Khi lỗi, response có dạng { "success": false, "errorCode": "...", "message": "...", "details": null }.

d. Ví dụ đầu ra


{
    "success": true,
    "dataContainerKey": "20260723142221781",
    "data": [
        {
            "isFront": false,
            "documentType": "VEHICLE_REGISTRATION",
            "imageUrl": "https://s3.amazonaws.com/...",
            "details": {
                "loai_vb": "dang_ky",
                "name": "NGUYỄN VĂN A",
                "address": "Hà Nội",
                "plate": "30A-123.45",
                "brand": "TOYOTA",
                "model": "VIOS",
                "loai_xe": "Ô tô con",
                "color": "Trắng",
                "chassis": "RLC123456789",
                "engine": "1ND123456",
                "capacity": 1496,
                "sit": 5,
                "id": "123456",
                "first_issue_date": "01/01/2020",
                "issued_at": "Phòng CSGT Hà Nội"
            }
        }
    ]
}










4.13 API OCR đăng kiểm xe (form-data v1)

a. Thông tin cơ bản

Ví dụ gửi ảnh

curl --location 'https://api.aicycle.ai/insurance/api/v1/ocr/vehicle-inspection' \
--header 'Authorization: Bearer $$API_KEY$$' \
--form 'images=@"$imgFilePathInLocalMachine1"' \
--form 'images=@"$imgFilePathInLocalMachine2"' \
--form 'externalSessionId="HoSo1"'

Ví dụ gửi link đăng kiểm điện tử

curl --location 'https://api.aicycle.ai/insurance/api/v1/ocr/vehicle-inspection' \
--header 'Authorization: Bearer $$API_KEY$$' \
--form 'links="https://gcndangkiem.vr.org.vn/chi-tiet?data=QmceBNfG70irYpbV8U9Muw&type=1"' \
--form 'externalSessionId="HoSo1"'
Method POST
API Url https://api.aicycle.ai/insurance/api/v1/ocr/vehicle-inspection
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Form Data

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
images Mảng ảnh đăng kiểm xe (tối đa 2 ảnh mặt trước và mặt sau). Bắt buộc nếu không gửi links Bắt buộc (nếu không có links) File Tối đa 2
links Link đăng kiểm điện tử (link lấy từ mã QR). Bắt buộc nếu không gửi images. Không gửi cùng lúc với images Bắt buộc (nếu không có images) Text Tối đa 1 https://dangkiem.link
externalSessionId Mã hồ sơ của khách hàng Optional Text 1,255 HoSo1

Khi gửi links, hệ thống tải file PDF giấy chứng nhận từ trang đăng kiểm điện tử; imageUrl trong response là Url presigned của file PDF này. Nếu không tải được PDF, imageUrl là chính link đã gửi.

c. Chi tiết đầu ra

{
    "success": <Trạng thái của Request (Boolean)>,
    "dataContainerKey": <Mã lưu kết quả của lần gọi (String)>,
    "data": [
        {
            "isFront": <Là mặt trước (Boolean)>,
            "documentType": <Loại tài liệu (String)>,
            "documentFormat": <Mẫu đăng kiểm: ELECTRONIC (gửi links) hoặc PAPER (gửi images) (String)>,
            "imageUrl": <Url ảnh S3 presigned; nếu dùng links là Url presigned file PDF, hoặc link đã gửi khi không tải được PDF (String)>,
            "details": {
                "loai_vb": <Mã loại văn bản, luôn là dang_kiem (String)>,
                "registration_number": <Biển số (String)>,
                "chassis_number": <Số khung (String)>,
                "engine_number": <Số máy (String)>,
                "mark": <Nhãn hiệu (String)>,
                "model_code": <Số loại (String)>,
                "type": <Loại phương tiện (String)>,
                "manufactured_year": <Năm sản xuất (Number)>,
                "seat_place": <Số chỗ ngồi (Number)>,
                "commercial_use": <Xe kinh doanh vận tải (Boolean)>,
                "design_total_mass": <Khối lượng toàn bộ theo thiết kế (Number)>,
                "authorized_total_mass": <Khối lượng toàn bộ cho phép tham gia giao thông (Number)>,
                "seri": <Số seri giấy chứng nhận, mặt sau (String)>,
                "seri_front": <Số seri mặt trước (String)>,
                "so_quan_ly": <Số quản lý (String)>,
                "regis_date": <Ngày kiểm định, định dạng DD/MM/YYYY (String)>,
                "valid_until": <Có hiệu lực đến, định dạng DD/MM/YYYY (String)>
            }
        }
    ]
}






documentFormat cho biết mẫu đăng kiểm theo cách gửi dữ liệu: ELECTRONIC khi gửi links (kể cả khi không tải được PDF), PAPER khi gửi images. Trường này chỉ có khi documentType là VEHICLE_INSPECTION.

Trường không đọc được trả null. Khi lỗi, response có dạng { "success": false, "errorCode": "...", "message": "...", "details": null }. Với links, errorCode = INVALID_INPUT khi gửi quá 1 link hoặc gửi cả images và links.

d. Ví dụ đầu ra


{
    "success": true,
    "dataContainerKey": "20260723142221782",
    "data": [
        {
            "isFront": false,
            "documentType": "VEHICLE_INSPECTION",
            "documentFormat": "PAPER",
            "imageUrl": "https://s3.amazonaws.com/.../rear.jpg",
            "details": {
                "loai_vb": "dang_kiem",
                "registration_number": "30A-123.45",
                "chassis_number": "RLC123456789",
                "engine_number": "1ND123456",
                "mark": "TOYOTA",
                "model_code": "VIOS",
                "type": "Ô tô con",
                "manufactured_year": 2020,
                "seat_place": 5,
                "commercial_use": false,
                "design_total_mass": 1700,
                "authorized_total_mass": 1700,
                "seri": "KC 9876543",
                "seri_front": null,
                "so_quan_ly": "1234-5678",
                "regis_date": "01/01/2024",
                "valid_until": "01/01/2025"
            }
        }
    ]
}










Ví dụ khi gửi links

{
    "success": true,
    "dataContainerKey": "20260723142221783",
    "data": [
        {
            "isFront": true,
            "documentType": "VEHICLE_INSPECTION",
            "documentFormat": "ELECTRONIC",
            "imageUrl": "https://s3.amazonaws.com/.../vehicle-inspection.pdf?X-Amz-...",
            "details": {
                "loai_vb": "dang_kiem",
                "registration_number": "30A-123.45",
                ...
            }
        }
    ]
}

4.14 API phân tích giấy tờ OCR (form-data v1)

a. Thông tin cơ bản

API nhận một hoặc nhiều ảnh của giấy tờ bất kỳ và tự động nhận diện loại giấy tờ để thực hiện OCR. Hiện hỗ trợ giấy phép lái xe, đăng ký xe và đăng kiểm xe.

Ví dụ

curl --request POST \
--url 'https://api.aicycle.ai/insurance/api/v1/ocr/document-analyses' \
--header 'Authorization: Bearer $$API_KEY$$' \
--form 'images=@"$imgFilePathInLocalMachine1"' \
--form 'images=@"$imgFilePathInLocalMachine2"' \
--form 'externalSessionId="externalSessionId"'
Method POST
API Url https://api.aicycle.ai/insurance/api/v1/ocr/document-analyses
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Form Data

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
images Mảng ảnh giấy tờ cần phân tích OCR (tối đa 2 ảnh) Bắt buộc File Tối đa 2
externalSessionId Mã hồ sơ của khách hàng Optional Text 1,255 externalSessionId

c. Chi tiết đầu ra

Response có success, dataContainerKey và data (mảng) như các mục 4.11 đến 4.13. Mỗi phần tử của data có cấu trúc theo loại giấy tờ mà hệ thống nhận diện:

Loại giấy tờ nhận diện documentType Cấu trúc response tham khảo
Giấy phép lái xe DRIVING_LICENSE Mục 4.11
Đăng ký xe VEHICLE_REGISTRATION Mục 4.12
Đăng kiểm xe VEHICLE_INSPECTION Mục 4.13
Loại giấy tờ không hỗ trợ Không có Phần tử chỉ gồm imageUrl, errorCode = UNSUPPORTED_DOCUMENT và message

Nếu tất cả ảnh đều là loại giấy tờ không hỗ trợ, API trả HTTP 400 với errorCode = UNSUPPORTED_DOCUMENT.

d. Ví dụ đầu ra


{
    "success": true,
    "dataContainerKey": "20260723142221783",
    "data": [
        {
            "isFront": true,
            "documentType": "DRIVING_LICENSE",
            "imageUrl": "https://s3.amazonaws.com/...",
            "details": { "loai_vb": "bang_lai", "name": "NGUYỄN VĂN A", "class": "B2" }
        },
        {
            "imageUrl": "https://s3.amazonaws.com/...",
            "errorCode": "UNSUPPORTED_DOCUMENT",
            "message": "Loại giấy tờ không được hỗ trợ"
        }
    ]
}

4.15 API xuất báo cáo OCR tổng hợp

a. Thông tin cơ bản

API xuất file Excel báo cáo OCR tổng hợp theo khoảng thời gian yêu cầu. Nếu không truyền startTime và endTime, hệ thống sẽ xuất báo cáo của ngày hiện tại.

Ví dụ

curl --location 'https://prod.api.aicycle.ai/insurance/api/v1/ocr/report-exports' \
--header 'Authorization: Bearer $$API_KEY$$' \
--header 'Content-Type: application/json' \
--data '{
    "startTime": "2026-08-11 00:00:00",
    "endTime": "2026-08-11 23:59:59"
}'
Method POST
API Url https://prod.api.aicycle.ai/insurance/api/v1/ocr/report-exports
API Headers { "Authorization": "Bearer $$API_KEY$$", "Content-Type": "application/json" }

b. Chi tiết đầu vào

Loại đầu vào: JSON Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Định dạng Ví dụ
startTime Thời điểm bắt đầu lấy dữ liệu báo cáo. Khi không truyền cả startTime và endTime, hệ thống mặc định lấy từ đầu ngày hiện tại. Tùy chọn Text YYYY-MM-DD hoặc YYYY-MM-DD HH:mm:ss 2026-08-11 00:00:00
endTime Thời điểm kết thúc lấy dữ liệu báo cáo. Khi không truyền cả startTime và endTime, hệ thống mặc định lấy đến cuối ngày hiện tại. Với định dạng YYYY-MM-DD, hệ thống hiểu là cuối ngày đó. Tùy chọn Text YYYY-MM-DD hoặc YYYY-MM-DD HH:mm:ss 2026-08-11 23:59:59

Để xuất báo cáo trong một ngày cụ thể, có thể truyền cả hai tham số ở định dạng YYYY-MM-DD.

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Kiểu dữ liệu Ví dụ
reportFileUrl Đường link có thời hạn để tải file Excel báo cáo OCR tổng hợp. Text fileUrl

d. Ví dụ đầu ra

{
    "reportFileUrl": "${fileUrl}"
}

4.16 API OCR hoá đơn (form-data v1)

a. Thông tin cơ bản

API nhận từ 1 đến 3 file hoá đơn (ảnh, PDF hoặc XML) và trả về thông tin hoá đơn được nhận diện cho từng file.

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/api/v1/ocr/invoice' \
--header 'Authorization: Bearer $$API_KEY$$' \
--form 'invoices=@"$invoiceFilePathInLocalMachine1"' \
--form 'invoices=@"$invoiceFilePathInLocalMachine2"' \
--form 'externalSessionId="externalSessionId"'
Method POST
API Url https://api.aicycle.ai/insurance/api/v1/ocr/invoice
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Form Data

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
invoices Mảng file hoá đơn. Định dạng hỗ trợ: jpg, jpeg, png, pdf, xml. Mỗi file có dung lượng từ 1KB đến 7MB Bắt buộc File 1,3
externalSessionId ID phiên làm việc của đối tác Optional Text 1,255 externalSessionId

c. Chi tiết đầu ra

{
    "success": <Trạng thái của Request (Boolean)>,
    "data": [
        {
            "documentType": <Loại tài liệu, luôn là INVOICE (String)>,
            "imageUrls": <Danh sách url S3 presigned của các file upload, theo thứ tự upload (Array[String])>,
            "details": {
                "id": <Số hóa đơn (String)>,
                "series": <Ký hiệu (String)>,
                "date": <Ngày chứng từ (String)>,
                "taxCode": <Mã số thuế nhà cung cấp (String)>,
                "vatRate": <Thuế suất GTGT (String)>,
                "vatAmount": <Tiền thuế GTGT (String)>,
                "totalPayment": <Tổng tiền trên hóa đơn (String)>,
                "invoiceCode": <Mã tra cứu (String)>,
                "searchOnWebsite": <Link tra cứu (String)>
            }
        }
    ]
}






Chi tiết Object item details (trường nào không nhận diện được sẽ trả null)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Số hóa đơn Bắt buộc Text | null 00003908
series Ký hiệu Bắt buộc Text | null 1C26TTX
date Ngày chứng từ Bắt buộc Text | null 03/08/2026
taxCode Mã số thuế nhà cung cấp Bắt buộc Text | null 0109274721
vatRate Thuế suất GTGT Bắt buộc Text | null 8%
vatAmount Tiền thuế GTGT Bắt buộc Text | null 111.200
totalPayment Tổng tiền trên hóa đơn Bắt buộc Text | null 1.501.200
invoiceCode Mã tra cứu Bắt buộc Text | null
searchOnWebsite Link tra cứu Bắt buộc Text | null

Lưu ý:

d. Ví dụ đầu ra


{
    "success": true,
    "data": [
        {
            "documentType": "INVOICE",
            "imageUrls": [
                "https://s3.amazonaws.com/.../invoice.pdf",
                "https://s3.amazonaws.com/.../photo.jpg"
            ],
            "details": {
                "id": "00003908",
                "series": "1C26TTX",
                "date": "03/08/2026",
                "taxCode": "0109274721",
                "vatRate": "8%",
                "vatAmount": "111.200",
                "totalPayment": "1.501.200",
                "invoiceCode": null,
                "searchOnWebsite": null
            }
        }
    ]
}










e. Chi tiết lỗi đầu ra

HTTP Code errorCode Trường hợp Ví dụ message
400 INVALID_INPUT Không gửi file hoá đơn Không tìm thấy file hoá đơn
400 (không có) File sai định dạng, vượt quá 3 file, file nhỏ hơn 1KB hoặc lớn hơn 7MB Pls upload image (jpeg, jpg, png), pdf or xml only
400 INVALID_DOCUMENT_TYPE Tất cả các file đều không phải hoá đơn hoặc không nhận diện được Sai loại giấy tờ
400 INVOICE_MISMATCH Các file tải lên không thuộc cùng 1 hoá đơn Vui lòng tải lên các giấy tờ của 1 hóa đơn
401 Thiếu hoặc sai API Key Unauthorized
403 API Key không có quyền sử dụng API Forbidden
408 INVALID_DOCUMENT_TYPE Quá thời gian xử lý Engine Timeout
500 INVALID_DOCUMENT_TYPE Lỗi hệ thống từ phía AICycle Có lỗi xảy ra khi gọi AICycle API

Ví dụ lỗi

{
    "success": false,
    "errorCode": "INVALID_DOCUMENT_TYPE",
    "message": "Sai loại giấy tờ",
    "details": null
}

Với lỗi do các file tải lên không thuộc cùng 1 hoá đơn:

{
    "success": false,
    "errorCode": "INVOICE_MISMATCH",
    "message": "Vui lòng tải lên các giấy tờ của 1 hóa đơn",
    "details": null
}

Với lỗi do file upload không hợp lệ (sai định dạng, quá số lượng, sai dung lượng), response chỉ gồm trường message:

{
    "message": "Pls upload image (jpeg, jpg, png), pdf or xml only"
}

5. APIs tích hợp partMe (phụ tùng)

5.1 Đồng bộ mã, giá phụ tùng (gửi data sang khách hàng lưu trữ)

a. Thông tin cơ bản

Đây là flow đồng bộ giữa AICycle và khách hàng theo cách khách hàng sẽ mở các đầu API để AICycle gửi data sang, khách hàng sẽ lưu trữ data và tự định giá phụ tùng dựa trên dữ liệu của AICycle.

Sync data picture

b. Chi tiết schema của AICycle gửi sang khách hàng

Loại đầu vào: JSON Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompany Hãng xe Bắt buộc Text 1, 255 TOYOTA
carModel Hiệu xe Bắt buộc Text 1,255 VIOS
carVersion Phiên bản Bắt buộc Text 1,255 1.5E AT
manufactureYear Năm sản xuất Bắt buộc Number 1,99999 2025
originName Xuất xứ Bắt buộc Text 1,255 Nhập khẩu
standardPartName Tên phụ tùng chuẩn của AICycle Bắt buộc Text 1,255 Cụm đèn pha trái
equivalentPartNames Tên phụ tùng hiện tại của khách hàng Bắt buộc Array[text] n [Cụm đèn pha L, Cụm đèn pha lái,…]
partPrice Giá phụ tùng Bắt buộc Number 1,99999 4257000
garaName Tên gara Bắt buộc Text 1, 255 CÔNG TY TNHH TOYOTA HƯNG THỊNH PHÁT THÁI BÌNH
approvalDate Ngày phê duyệt Bắt buộc Text 1, 255 2024-05-30 10:35:00
province Tỉnh thành Bắt buộc Text 1, 255 Tỉnh Thái Bình
region Khu vực Bắt buộc Text 1, 255 Miền Bắc

5.2: API định giá phụ tùng (sử dụng CodeBook hãng hiệu và phiên bản của AICycle) (deprecated)

5.2.1: API lấy thông tin xuất xứ

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/part-me/origins' \
--header 'Authorization: Bearer <API Key>' \
Method GET
API Url https://api.aicycle.ai/insurance/part-me/origins
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Id xuất xứ Optional Number 1,9999 1
key Key xuất xứ Optional Text 1,255 lrtn
name Tên xuất xứ Optional Text 1,255 LRTN
limit Giới hạn số lượng Optional Number 1,9999 30
offset Index start Optional Number 1,9999 0

c. Chi tiết đầu ra

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
count Số lượng record Bắt buộc Number 1,9999 2
limit Giới hạn số lượng Bắt buộc Number 1,9999 30
offset Index start Bắt buộc Number 1,9999 0
records Danh sách xuất xứ Bắt buộc Array[origin] n []

Chi tiết Object item origin

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Id xuất xứ Bắt buộc Number 1,9999 1
key Key xuất xứ Bắt buộc Text 1,255 lrtn
name Tên xuất xứ Bắt buộc Text 1,255 LRTN

d. Ví dụ đầu ra

{
    "count": 2,
    "limit": 30,
    "offset": 0,
    "records": [
        {
            "id": 2,
            "key": "lrtn",
            "name": "LRTN"
        },
        {
            "id": 1,
            "key": "nk",
            "name": "NK"
        }
    ]
}















5.2.2: API lấy thông tin khu vực

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/part-me/regions' \
--header 'Authorization: Bearer <API Key>' \
Method GET
API Url https://api.aicycle.ai/insurance/part-me/regions
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Id khu vực Optional Text 1,255 uuid-region
slug Key khu vực Optional Text 1,255 mienbac
name Tên khu vực Optional Text 1,255 Miền Bắc
provinceId Id tỉnh Optional Text 1,255 uuid-tinh
limit Giới hạn số lượng Optional Number 1,9999 30
offset Index start Optional Number 1,9999 0

c. Chi tiết đầu ra

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
count Số lượng record Bắt buộc Number 1,9999 1
limit Giới hạn số lượng Bắt buộc Number 1,9999 30
offset Index start Bắt buộc Number 1,9999 0
records Danh sách khu vực Bắt buộc Array[region] n []

Chi tiết Object item region

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Id khu vực Bắt buộc Text 1,255 uuid-region
slug Key khu vực Bắt buộc Text 1,255 miennam
name Tên khu vực Bắt buộc Text 1,255 Miền Nam

Ví dụ đầu ra

{
    "count": 1,
    "limit": 30,
    "offset": 0,
    "records": [
        {
            "id": "7ba25bde-a2f0-4772-a0ac-9c771894e9a2",
            "name": "Miền Nam",
            "slug": "miennam"
        }
    ]
}











5.2.3: API lấy thông tin tỉnh

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/part-me/provinces' \
--header 'Authorization: Bearer <API Key>' \
Method GET
API Url https://api.aicycle.ai/insurance/part-me/provinces
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Id tỉnh Optional Text 1,255 uuid-province
slug Key tỉnh Optional Text 1,255 mienbac
name Tên tỉnh Optional Text 1,255 Miền Bắc
regionId Id khu vực Optional Text 1,255 uuid-region
limit Giới hạn số lượng Optional Number 1,9999 30
offset Index start Optional Number 1,9999 0

c. Chi tiết đầu ra

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
count Số lượng record Bắt buộc Number 1,9999 1
limit Giới hạn số lượng Bắt buộc Number 1,9999 30
offset Index start Bắt buộc Number 1,9999 0
records Danh sách khu vực Bắt buộc Array[province] n []

Chi tiết Object item province

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Id tỉnh Bắt buộc Text 1,255 uuid-province
slug Key tỉnh Bắt buộc Text 1,255 tinhtayninh
name Tên tỉnh Bắt buộc Text 1,255 Tỉnh Tây Ninh

d. Ví dụ đầu ra

{
    "count": 1,
    "limit": 30,
    "offset": 0,
    "records": [
        {
            "id": "d67d1988-57da-41d1-8b7d-b4186a1bd3b8",
            "name": "Tỉnh Tây Ninh",
            "slug": "tinhtayninh"
        }
    ]
}











5.2.4: API lấy thông tin nhóm phụ tùng

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/part-me/groups' \
--header 'Authorization: Bearer <API Key>' \
Method GET
API Url https://api.aicycle.ai/insurance/part-me/groups
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Id nhóm phụ tùng Optional Text 1,255 uuid-group
slug Key nhóm phụ tùng Optional Text 1,255 mienbac
name Tên nhóm phụ tùng Optional Text 1,255 Miền Bắc
limit Giới hạn số lượng Optional Number 1,9999 30
offset Index start Optional Number 1,9999 0

c. Chi tiết đầu ra

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
count Số lượng record Bắt buộc Number 1,9999 1
limit Giới hạn số lượng Bắt buộc Number 1,9999 30
offset Index start Bắt buộc Number 1,9999 0
records Danh sách khu vực Bắt buộc Array[group] n []

Chi tiết Object item group

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Id nhóm phụ tùng Bắt buộc Text 1,255 uuid-group
slug Key nhóm phụ tùng Bắt buộc Text 1,255 hethongkhunggamtruyenluc
name Tên nhóm phụ tùng Bắt buộc Text 1,255 Hệ thống khung gầm, truyền lực

d. Ví dụ đầu ra

{
    "count": 1,
    "limit": 30,
    "offset": 0,
    "records": [
        {
            "id": "65edef9d-abfc-4264-9369-0e252e6cafdd",
            "name": "Hệ thống khung gầm, truyền lực",
            "slug": "hethongkhunggamtruyenluc"
        }
    ]
}











5.2.5: API lấy thông tin codebook phụ tùng

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/part-me/codebooks' \
--header 'Authorization: Bearer <API Key>' \
Method GET
API Url https://api.aicycle.ai/insurance/part-me/codebooks
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Id tỉnh Optional Text 1,255 uuid-codebook
slug Key tỉnh Optional Text 1,255 mienbac
name Tên tỉnh Optional Text 1,255 Miền Bắc
partCodebookGroupId Id nhóm phụ tùng Optional Text 1,255 uuid-group
limit Giới hạn số lượng Optional Number 1,9999 30
offset Index start Optional Number 1,9999 0

c. Chi tiết đầu ra

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
count Số lượng record Bắt buộc Number 1,9999 1
limit Giới hạn số lượng Bắt buộc Number 1,9999 30
offset Index start Bắt buộc Number 1,9999 0
records Danh sách khu vực Bắt buộc Array[codebook] n []

Chi tiết Object item codebook

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
id Id codebook Bắt buộc Text 1,255 uuid-codebook
partCodebookSlug Key codebook Bắt buộc Text 1,255 ketgiannongdieuhoa
partCodebookName Tên codebook Bắt buộc Text 1,255 Két giàn nóng điều hòa
partCodebookGroupName Tên nhóm codebook Bắt buộc Text 1,255 Hệ thống khung gầm, truyền lực

d. Ví dụ đầu ra

{
    "count": 1,
    "limit": 30,
    "offset": 0,
    "records": [
        {
            "id": "222b2d19-5eab-4728-ae22-3e6a4b9cd395",
            "partCodebookName": "Két giàn nóng điều hòa",
            "partCodebookSlug": "ketgiannongdieuhoa",
            "partCodebookGroupName": "Hệ thống khung gầm, truyền lực"
        }
    ]
}











5.2.6: API lấy giá phụ tùng

a. Thông tin cơ bản

Ví dụ

curl --location 'https://api.aicycle.ai/insurance/valuation/car-part-valuate' \
--header 'Authorization: Bearer <API Key>' \
--header 'Content-Type: application/json' \
--data '{
    "carCompanyId": "ca3aee80-f81c-41fb-9b74-ce6f9fdb996e",
    "carModelId": "7a15f4c0-8b57-4e1a-ae06-587b75ffef39",
    "carVersionId": "7d801069-87b0-4d35-b38c-314c69257b8e",
    "year": 2022,
    "partCodebookId": "ac0cdab2-8f52-4f0c-9b83-3b62925e09ef",
    "regionId": "7ba25bde-a2f0-4772-a0ac-9c771894e9a2",
    "provinceId": "d67d1988-57da-41d1-8b7d-b4186a1bd3b8",
    "originId": 2,
    "isAuthentic": true
}'
Method POST
API Url https://api.aicycle.ai/insurance/valuation/car-part-valuate
API Headers { "Authorization": "Bearer $$API_KEY$$" }

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompanyId Id hãng xe Bắt buộc Text 1,255 uuid-hang-xe
carModelId Id hiệu xe Bắt buộc Text 1,255 uuid-hieu-xe
carVersionId Id phiên bản xe Bắt buộc Text 1,255 uuid-phien-ban-xe
partCodebookId Id codebook phụ tùng Bắt buộc Text 1,255 uuid-codebook-phu-tung
year Năm sản xuất Bắt buộc Number 1,9999 2020
regionId Id khu vực Optional Text 1,255 uuid-khu-vuc
provinceId Id tỉnh trong khu vực Optional Text 1,255 uuid-tinh
originId Id xuất xứ Optional Number 1,9999 1
isAuthentic Có là chính hãng không Optional Boolean n true

c. Chi tiết đầu ra

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompanyName Tên hãng xe Bắt buộc Text 1,255 TOYOTA
carModelName Tên hiệu xe Bắt buộc Text 1,255 VIOS
carVersionName Tên phiên bản xe Bắt buộc Text 1,255 1.5G CVT
year Năm sản xuất Bắt buộc Number 1,9999 2022
partCodebookName Tên codebook phụ tùng Bắt buộc Text 1,255 Cản trước (bđx trước)
partCodebookGoup Tên nhóm codebook phụ tùng Bắt buộc Text 1,255 Thân vỏ xe
regionName Tên khu vực Bắt buộc Text 1,255 Miền Nam
provinceName Tên tỉnh trong khu vực Bắt buộc Text 1,255 Tỉnh Tây Ninh
originName Tên xuất xứ Bắt buộc Text 1,255 LRTN
garageName Tên garage sửa chữa Bắt buộc Text 1,255 CÔNG TY TNHH TOYOTA HƯNG THỊNH PHÁT TÂY NINH
minPrice Giá min của phụ tùng Bắt buộc Number 1,999999999 3160600
maxPrice Giá max của phụ tùng Bắt buộc Number 1,999999999 3180600
price Giá trị của phụ tùng Bắt buộc Number 1,999999999 3170600
histories Danh sách lịch sử giá của tổ chức Bắt buộc Array[partCodebookPriceHistory] n []

Chi tiết Object item partCodebookPriceHistory

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
carCompanyName Tên hãng xe Bắt buộc Text 1,255 TOYOTA
carModelName Tên hiệu xe Bắt buộc Text 1,255 VIOS
carVersionName Tên phiên bản xe Bắt buộc Text 1,255 1.5G CVT
year Năm sản xuất Bắt buộc Number 1,9999 2020
partCodebookName Tên codebook phụ tùng Bắt buộc Text 1,255 Cản trước (bđx trước)
partCustomerName Tên codebook phụ tùng khách hàng Bắt buộc Text 1,255 01XOC.00049
partCodebookGoup Tên nhóm codebook phụ tùng Bắt buộc Text 1,255 Thân vỏ xe
regionName Tên khu vực Bắt buộc Text 1,255 Miền Nam
provinceName Tên tỉnh trong khu vực Bắt buộc Text 1,255 Tỉnh Tây Ninh
originName Tên xuất xứ Bắt buộc Text 1,255 LRTN
garageName Tên garage sửa chữa Bắt buộc Text 1,255 CÔNG TY TNHH TOYOTA HƯNG THỊNH PHÁT TÂY NINH
minPrice Giá min của phụ tùng Bắt buộc Number 1,999999999 3160600
maxPrice Giá max của phụ tùng Bắt buộc Number 1,999999999 3180600
price Giá trị của phụ tùng Bắt buộc Number 1,999999999 3170600

d. Ví dụ đầu ra

{
    "carCompanyName": "TOYOTA",
    "carModelName": "VIOS",
    "carVersionName": "1.5G CVT",
    "year": 2022,
    "partCodebookName": "Cản trước (bđx trước)",
    "partCodebookGoup": "Thân vỏ xe",
    "regionName": "Miền Nam",
    "provinceName": "Tỉnh Tây Ninh",
    "originName": "LRTN",
    "garageName": null,
    "price": 3170600,
    "minPrice": 3160600,
    "maxPrice": 3180600,
    "histories": [
        {
            "carCompanyName": "TOYOTA",
            "carModelName": "VIOS",
            "carVersionName": "1.5G CVT",
            "year": 2022,
            "partCodebookName": "Cản trước (bđx trước)",
            "partCustomerName": "01XOC.00049",
            "partCodebookGoup": "Thân vỏ xe",
            "regionName": "Miền Nam",
            "provinceName": "Tỉnh Tây Ninh",
            "originName": "LRTN",
            "garageName": null,
            "price": 3170600,
            "minPrice": 3160600,
            "maxPrice": 3180600
        }
    ]
}
















6. APIs tích hợp AICycle Agents

Phần này mô tả các API cần thiết để tích hợp và hiển thị chatbot của AICycle Agents trên ứng dụng của đối tác.

Sync data picture

a. Thông tin cơ bản

API này được sử dụng để khởi tạo một phiên làm việc và lấy đường dẫn (URL) duy nhất của chatbot để nhúng vào ứng dụng của bạn thông qua thẻ iframe.

Trường Giá trị
Method POST
API URL https://api.aicycle.ai/admin/api/v1/integrations/initiate
API Headers Authorization: Bearer <API_KEY>; X-Customer-Token: <Token dùng để gọi API nội bộ của bạn>; Content-Type: application/json

Ví dụ cURL

curl --location 'https://api.aicycle.ai/admin/api/v1/integrations/initiate' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'X-Customer-Token: <Token dùng để gọi API nội bộ của bạn>' \
--header 'Content-Type: application/json' \
--data '{
    "userId": "user-id-123",
    "userName": "userName"
}'

b. Chi tiết đầu vào

Loại đầu vào: Body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
userId Id của người dùng cuối Bắt buộc Text 1,255 51dd13ef-8def-4aee-b09e-64c7a118a1bf
userName Tên người dùng cuối Optional Text 1,255 User Name

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
iframeUrl Đường dẫn truy cập vào AICycle Agents Bắt buộc Text 1,255 https://agent-insurance.aicycle.ai/chat-loader?token={{token}}

d. Ví dụ đầu ra

{
    "iframeUrl": "https://agent-insurance.aicycle.ai/chat-loader?token={{token}}
}




6.2 API eKYC Verify Face (Upload)

a. Thông tin cơ bản

API này được sử dụng để tải lên và xác thực khuôn mặt từ ảnh chân dung và giấy tờ tùy thân (Căn cước công dân, Giấy khai sinh). Nó hỗ trợ xác thực cho cả trường hợp người lớn và trẻ em.

Trường Giá trị
Method POST
API URL https://api.aicycle.ai/insurance-agent/api/v1/ekyc/verify-face/upload
API Headers Authorization: Bearer <API Key>; Content-Type: multipart/form-data

Ví dụ cURL trường hợp người lớn:

curl --location 'https://api.aicycle.ai/insurance-agent/api/v1/ekyc/verify-face/upload' \
--header 'Authorization: Bearer <API Key>' \
--form 'portraitImage=@"/path/to/portrait.jpg"' \
--form 'idCardImage=@"/path/to/idcard.jpg"' \
--form 'isChild="false"'

Ví dụ cURL trường hợp trẻ em:

curl --location 'https://api.aicycle.ai/insurance-agent/api/v1/ekyc/verify-face/upload' \
--header 'Authorization: Bearer <API Key>' \
--form 'portraitImage=@"/path/to/portrait.jpg"' \
--form 'idCardImage=@"/path/to/idcard.jpg"' \
--form 'isChild="true"' \
--form 'birthCertificateImage=@"/path/to/birthcertificate.jpg"'

b. Chi tiết đầu vào

Loại đầu vào: Form Data (multipart/form-data)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
portraitImage Hình ảnh chân dung Bắt buộc File n /path/to/portrait.jpg
idCardImage Hình ảnh Căn cước công dân Bắt buộc File n /path/to/idcard.jpg
isChild Cờ xác định có phải đối tượng trẻ em hay không Bắt buộc Text n “false”, “true”
birthCertificateImage Hình ảnh Giấy khai sinh (Bắt buộc nếu isChild=“true”) Theo điều kiện File n /path/to/birthcertificate.jpg

c. Chi tiết đầu ra

Loại đầu ra: Response body

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
portraitImageUrl Đường dẫn ảnh chân dung đã tải lên Bắt buộc Text 1,255 URL
idCardImageUrl Đường dẫn ảnh CCCD đã tải lên Bắt buộc Text 1,255 URL
birthCertificateUrl Đường dẫn ảnh Giấy khai sinh đã tải lên Optional Text 1,255 URL
similarityScore Điểm số tương đồng xác thực Bắt buộc Number 0,1 0.98
matched Kết quả xác thực khuôn mặt (khớp hay không) Bắt buộc Boolean n true
idCardInfo Thông tin OCR trích xuất từ CCCD Optional Object n {}
birthCertificateInfo Thông tin OCR trích xuất từ Giấy khai sinh (chỉ có trong case trẻ em) Optional Object n {}
related Mối quan hệ giữa giấy tờ tùy thân (nếu có kiểm tra chéo) Optional Boolean n true

Chi tiết Object idCardInfo

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
fullName Họ tên trên CCCD Optional Text 1,255 NGUYỄN VĂN A
dateOfBirth Ngày sinh trên CCCD Optional Text 1,255 01/01/1990
nationalIdNumber Số CCCD Optional Text 1,255 001090123456

Chi tiết Object birthCertificateInfo

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
childFullName Họ tên trẻ em trên Giấy khai sinh Optional Text 1,255 NGUYỄN VĂN B
fatherFullName Họ tên cha trên Giấy khai sinh Optional Text 1,255 NGUYỄN VĂN A
motherFullName Họ tên mẹ trên Giấy khai sinh Optional Text 1,255 TRẦN THỊ C

d. Ví dụ đầu ra

Case người lớn:

{
  "portraitImageUrl": "string",
  "idCardImageUrl": "string",
  "birthCertificateUrl": "string",
  "similarityScore": 0.98,
  "matched": true,
  "idCardInfo": {
    "fullName": "string",
    "dateOfBirth": "string",
    "nationalIdNumber": "string"
  }
}

Case trẻ em:

{
  "portraitImageUrl": "string",
  "idCardImageUrl": "string",
  "birthCertificateUrl": "string",
  "similarityScore": 0.98,
  "matched": true,
  "idCardInfo": {
    "fullName": "string",
    "dateOfBirth": "string",
    "nationalIdNumber": "string"
  },
  "birthCertificateInfo": {
    "childFullName": "string",
    "fatherFullName": "string",
    "motherFullName": "string"
  },
  "related": true
}










6.3 Document Extraction / OCR API

a. Thông tin cơ bản

API này được sử dụng để bóc tách thông tin (OCR) từ các loại giấy tờ, chứng từ thu thập được. Dữ liệu trích xuất trả về có cấu trúc linh hoạt (dynamic) tùy thuộc vào từng loại chứng từ.

Trường Giá trị
Method POST
API URL https://stage.api.aicycle.ai/insurance-agent/api/v1/integration/ocr/extract
API Headers Authorization: Bearer <API Key>; Content-Type: multipart/form-data

Ví dụ cURL:

curl --location 'https://stage.api.aicycle.ai/insurance-agent/api/v1/integration/ocr/extract' \
--header 'Authorization: Bearer <API Key>' \
--form 'files=@"/path/to/document.pdf"' \
--form 'benefitCode="outpatient_care"'

b. Chi tiết đầu vào

Loại đầu vào: Form Data (multipart/form-data)

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
files File chứng từ cần bóc tách (PDF, ảnh, v.v.) Bắt buộc File n /path/to/document.pdf
benefitCode Mã quyền lợi bảo hiểm tương ứng Optional Text 1,255 outpatient_care

c. Chi tiết đầu ra

Loại đầu ra: Response body

Mảng chứa kết quả bóc tách từ các file đã upload.

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
url Đường dẫn file lưu trữ trên S3 Bắt buộc Text 1,1000 URL
originalName Tên file gốc tải lên Bắt buộc Text 1,255 chung-tu-ho-so-3.pdf
documents Danh sách các loại chứng từ nhận diện được trong file Bắt buộc Array[document] n []

Chi tiết Object document

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
documentCode Mã loại chứng từ Bắt buộc Text 1,255 claim_form
documentName Tên loại chứng từ Bắt buộc Text 1,255 Giấy yêu cầu bồi thường
startPage Trang bắt đầu của chứng từ (nếu là PDF) Bắt buộc Number 1,9999 1
endPage Trang kết thúc của chứng từ Bắt buộc Number 1,9999 2
extractedData Danh sách dữ liệu bóc tách được tùy theo loại chứng từ Bắt buộc Array[extractedField] n []

Chi tiết Object extractedField

Đây là object có cấu trúc động. Giá trị của trường value sẽ phụ thuộc vào trường dataType.

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
fieldKey Mã trường dữ liệu Bắt buộc Text 1,255 total_claimed_amount
fieldName Tên trường dữ liệu Bắt buộc Text 1,255 Chi phí y tế được yêu cầu
dataType Kiểu dữ liệu của value (string, number, boolean, date, array) Bắt buộc Text 1,50 number
value Giá trị bóc tách được. Nếu dataType = array, trường này chứa một mảng các row. Bắt buộc Mixed n 150000
isValid Đánh dấu dữ liệu OCR có hợp lệ không Bắt buộc Boolean n true
aiWarning Đánh dấu cảnh báo từ AI (mờ, nhòe, nghi ngờ sai lệch, v.v.) Bắt buộc Boolean n false
errorMessage Thông báo lỗi cụ thể (nếu có) Optional Text n null
childSchema Cấu trúc các cột áp dụng cho value nêú dataType = array Optional Array[childField] n []

Chi tiết Object childField (Chỉ có khi dataType là array)

Cấu trúc này quy định các cột (column) của bảng dữ liệu bên trong mảng.

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
fieldKey Mã cột dữ liệu Bắt buộc Text 1,255 unitPrice
fieldName Tên cột dữ liệu Bắt buộc Text 1,255 Đơn giá
dataType Kiểu dữ liệu của giá trị trong cột (string, number, boolean, date) Bắt buộc Text 1,50 number

d. Mã Lỗi (Error Handling)

Hệ thống trả về các mã lỗi sau nếu có lỗi xảy ra:

Mã lỗi (HTTP Status) Tên lỗi Mô tả
400 Bad Request Lỗi do Payload / Validation hoặc file upload không hợp lệ (không đúng định dạng, file quá lớn, …).
401 / 403 Unauthorized / Forbidden Lỗi do xác thực (Auth), token hết hạn hoặc không có quyền truy cập.
500+ Internal Server Error Lỗi xuất phát từ hệ thống hoặc nền tảng OCR Engine xử lý thất bại.
504 Gateway Timeout Quá thời gian chờ phản hồi do file lớn hoặc OCR xử lý quá lâu.

e. Ví dụ đầu ra

Dưới đây là một phần ví dụ thể hiện dữ liệu với các kiểu dataType khác nhau (bao gồm cả chuỗi, số, boolean, date và mảng bảng biểu).

[
    {
        "url": "https://ai-insurance.s3.ap-southeast-1.amazonaws.com/AGENTIC/OCR/DYNAMIC/2026-03-19/...pdf",
        "originalName": "chung-tu-ho-so-3.pdf",
        "documents": [
            {
                "documentCode": "claim_form",
                "documentName": "Giấy yêu cầu bồi thường",
                "startPage": 1,
                "endPage": 2,
                "extractedData": [
                    {
                        "fieldKey": "document_title",
                        "fieldName": "Loại chứng từ",
                        "dataType": "string",
                        "value": "GIẤY YÊU CẦU BỒI THƯỜNG BẢO HIỂM SỨC KHỎE",
                        "isValid": true,
                        "aiWarning": false,
                        "errorMessage": null
                    },
                    {
                        "fieldKey": "total_claimed_amount",
                        "fieldName": "Chi phí y tế được yêu cầu",
                        "dataType": "number",
                        "value": 150000,
                        "isValid": true,
                        "aiWarning": false,
                        "errorMessage": null
                    },
                    {
                        "fieldKey": "has_insured_signature",
                        "fieldName": "Có chữ ký của Người được bảo hiểm",
                        "dataType": "boolean",
                        "value": true,
                        "isValid": true,
                        "aiWarning": false,
                        "errorMessage": null
                    },
                    {
                        "fieldKey": "incident_date",
                        "fieldName": "Ngày khám bệnh/ ngày xảy ra tai nạn",
                        "dataType": "date",
                        "value": "2026-02-25",
                        "isValid": true,
                        "aiWarning": false,
                        "errorMessage": null
                    }
                ]
            },
            {
                "documentCode": "vat_invoice",
                "documentName": "Hóa đơn GTGT",
                "startPage": 24,
                "endPage": 24,
                "extractedData": [
                    {
                        "fieldKey": "invoice_line_items",
                        "fieldName": "Chi tiết bảng hóa đơn",
                        "dataType": "array",
                        "value": [
                            {
                                "itemName": "Cạo vôi răng + Đánh bóng răng",
                                "unit": "Lần",
                                "quantity": 1,
                                "unitPrice": 150000,
                                "amount": 150000
                            }
                        ],
                        "isValid": true,
                        "aiWarning": false,
                        "errorMessage": null,
                        "childSchema": [
                            {
                                "dataType": "string",
                                "fieldKey": "itemName",
                                "fieldName": "Tên hàng hóa, dịch vụ"
                            },
                            {
                                "dataType": "string",
                                "fieldKey": "unit",
                                "fieldName": "Đơn vị tính"
                            },
                            {
                                "dataType": "number",
                                "fieldKey": "quantity",
                                "fieldName": "Số lượng"
                            },
                            {
                                "dataType": "number",
                                "fieldKey": "unitPrice",
                                "fieldName": "Đơn giá"
                            },
                            {
                                "dataType": "number",
                                "fieldKey": "amount",
                                "fieldName": "Thành tiền"
                            }
                        ]
                    }
                ]
            }
        ]
    }
]





6.4 API lấy danh sách quyền lợi bảo hiểm

a. Thông tin cơ bản

API này được sử dụng để lấy danh sách các quyền lợi bảo hiểm (benefits) hiện có trong hệ thống, kèm theo danh sách các loại tài liệu/chứng từ (document types) tương ứng được ánh xạ cho mỗi quyền lợi. Thông tin này giúp Client/Frontend hiển thị danh sách quyền lợi và gợi ý cho người dùng các chứng từ cần tải lên tương ứng.

Trường Giá trị
Method GET
API URL https://stage.api.aicycle.ai/insurance-agent/api/v1/ocr-categories/benefits
API Headers Authorization: Bearer <API Key>

Ví dụ cURL:

curl --location 'https://stage.api.aicycle.ai/insurance-agent/api/v1/ocr-categories/benefits' \
--header 'Authorization: Bearer <API Key>'

b. Chi tiết đầu vào

API này không yêu cầu tham số đầu vào.

c. Chi tiết đầu ra

Loại đầu ra: Response body

Mảng chứa các object đại diện cho quyền lợi bảo hiểm (benefit).

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
benefitId ID định danh của quyền lợi Bắt buộc Text 1,255 28ec95c8-43d1-48e2…
benefitCode Mã quyền lợi bảo hiểm Bắt buộc Text 1,255 outpatient_care
benefitName Tên quyền lợi bảo hiểm Bắt buộc Text 1,255 ĐIỀU TRỊ NGOẠI TRÚ
description Mô tả chi tiết quyền lợi Optional Text n Quyền lợi khám và điều trị ngoại trú
status Trạng thái (VD: active, inactive) Bắt buộc Text 1,50 active
mappedDocumentTypes Danh sách các loại chứng từ liên kết với quyền lợi này Bắt buộc Array[documentType] n []

Chi tiết Object documentType

Mô tả loại chứng từ được yêu cầu cung cấp đối với quyền lợi bảo hiểm tương ứng.

Tên Tham số Mô tả Bắt buộc Kiểu dữ liệu Min,Max Ví dụ
documentCode Mã loại chứng từ Bắt buộc Text 1,255 lab_test_order
documentName Tên loại chứng từ Bắt buộc Text 1,255 Phiếu chỉ định và kết quả cận lâm sàng
description Mô tả chi tiết loại chứng từ Optional Text n Báo cáo y tế, tóm tắt bệnh án…
isRequired Cờ xác định chứng từ này có bắt buộc bổ sung hay không Bắt buộc Boolean n true

d. Ví dụ đầu ra

Dưới đây là một phần ví dụ thể hiện dữ liệu của một quyền lợi bảo hiểm.

[
    {
        "benefitId": "28ec95c8-43d1-48e2-ab99-691e15d85d24",
        "benefitCode": "outpatient_care",
        "benefitName": "ĐIỀU TRỊ NGOẠI TRÚ",
        "description": "Quyền lợi khám và điều trị ngoại trú",
        "status": "active",
        "mappedDocumentTypes": [
            {
                "documentCode": "lab_test_order",
                "documentName": "Phiếu chỉ định và kết quả cận lâm sàng",
                "description": null,
                "isRequired": true
            },
            {
                "documentCode": "medical_report",
                "documentName": "Báo cáo y tế",
                "description": "Báo cáo y tế, tóm tắt bệnh án từ cơ sở y tế",
                "isRequired": false
            }
        ]
    }
]