Integration Process of Vehicle Services

This topic describes how to integrate with open capabilities of vehicle services.

Integration procedure

There are two types of devices, parking lot device and barrier gate.

To integrate with the open capabilities of vehicle services, you need to create a cloud project in the cloud development module of the Tuya IoT Development Platform.

1. Log in to the Tuya IoT Development Platform.
2. In the left-side navigation bar, click Cloud.
3. Click Create Cloud Project, fill in relevant information, and then select Custom as the development method.
4. Consult Tuya’s delivery personnel and get the configuration list required to integrate a parking lot of the specified brand. After the list is ready, provide it to the delivery personnel together with the project information.
5. The delivery personnel will create vehicle gateways, and provide you with information such as vehicle gateways and devices.

Data points of vehicle services

For more information, see General Capabilities in Public Area.

API description

Pass authorization

API name	API endpoint
Add Pass Authorization	POST:/v1.0/parking-control/{device_id}/pass-authorizations/{pass_authorization_id}
Update Pass Authorization	PUT:/v1.0/parking-control/{device_id}/pass-authorizations/{pass_authorization_id}
Delete Pass Authorization	DELETE:/v1.0/parking-control/{device_id}/pass-authorizations/{pass_authorization_id}

Visitor vehicle

API name	API endpoint
Add Visitor Vehicle	POST:/v1.0/parking-control/{device_id}/visitor-cars/{visitor_car_id}
Update Visitor Vehicle	PUT:/v1.0/parking-control/{device_id}/visitor-cars/{visitor_car_id}
Delete Visitor Vehicle	DELETE:/v1.0/parking-control/{device_id}/visitor-cars/{visitor_car_id}
Extend Accessible Period of Visitor Vehicle	PUT:/v1.0/parking-control/{device_id}/visitor-cars/{visitor_car_id}/delay

Special vehicle

API name	API endpoint
Add Special Vehicle	POST:/v1.0/parking-control/{device_id}/special-cars
Delete Special Vehicle	DELETE:/v1.0/parking-control/{device_id}/special-cars

Vehicle locking/unlocking

API name	API endpoint
Lock Vehicle	POST:/v1.0/parking-control/{device_id}/cars/lock
Unlock Vehicle	DELETE:/v1.0/parking-control/{device_id}/cars/unlock

Unlicensed vehicle

API name	API endpoint
Permit the Pass of Unlicensed Vehicle	POST:/v1.0/parking-control/{device_id}/unlicensed-cars/pass

Temporary vehicle

API name	API endpoint
Get Current Vehicle	GET:/v1.0/parking-control/{device_id}/cars/current
Generate Pending Order	POST:/v1.0/parking-control/{device_id}/orders/generate
Notify Payment Result	POST:/v1.0/parking-control/{device_id}/fees/{order_number}/pay

Barrier gate

API name	API endpoint
Control Barrier Gate	POST:/v1.0/parking-control/{device_id}/gates/control

Data synchronization

API name	API endpoint
Data Synchronization	POST:/v1.0/parking-control/{device_id}/records/sync

Event format of vehicle services

After you subscribe to the message service for a cloud development project, you will receive event messages from the associated parking lot devices.

• Subscribe to the message service
• For more information about integration with the message queue, see Message Queue.

Report general command result

API description

After a command is sent in an API request, the unique number of the command will be returned: sn. You will get the execution result of the command by checking Pulsar messages.

Parameters

Parameter	Type	Description	Required
bizCode	String	The business code of a specified event. The value is edgeCmdResult here.	Yes
devId	String	The ID of a specified device in the parking lot.	Yes
productKey	String	The product ID.	Yes
ts	Long	The time when a vehicle passes.	Yes
bizData	Object	The business data.	Yes

Description of bizData

Parameter	Type	Description	Required
sn	String	The ID of a specified command record.	Yes
processStatus	Integer	The execution status of a command. Valid values: 1: Sending 2: Sent 3: Success 4: Failure 5: Unknown	Yes
message	String	The description of the command execution. In case of a failure, an error message will be returned.	No
happenTime	Long	The time when the command is executed.	Yes
cmdBizType	String	The business type of the command.	No
data	Object	The result to be returned in the JSON format.	No

{
  "bizCode": "cmdIssueResult",
  "devId": "6c873a4652689079b7****",
  "productKey": "lowdwphf3oid****",
  "ts": 1653982851495,
  "uuid": "bay1622429214496****",
  "bizData": {
    "processStatus": 3,
    "data": "{}",
    "cmdBizType": "parking_result",
    "sn": "153154063487861****",
    "message": "",
    "happenTime": 1653982851470
  }
}

Report result of generating pending order

The result format of the outer parameter command is the same as the general result format. The data parameter in the content is as follows:

Description of data

Parameter	Type	Description	Required
gatewayId	String	The gateway ID.	Yes
orderNo	String	The order ID.	Yes
feeType	String	The payment type. 1: long-term payment 2: temporary parking 3: withholding payment 4: unlicensed vehicle 5: unknown	Yes
plateNo	String	The license plate number.	Yes
inParkingId	String	The inbound ID.	Yes
inboundTime	Long	The inbound time.	Yes
startTime	Long	The start time of billing.	Yes
elapsedTime	Long	The parking duration. Unit: minutes.	Yes
payableAmount	Integer	The payable amount. Unit: cent.	Yes
paidAmount	Integer	The paid amount. Unit: cent.	Yes
discountAmount	Integer	The discount amount. Unit: cent.	Yes

Example

{
    "bizCode":"cmdIssueResult",
    "devId":"6c5474318446ac99f3****",
    "productKey":"4dfsdq7a1akx****",
    "ts":165398417****,
    "uuid":"bay1622429214496****",
    "bizData":{
        "processStatus":3,
        "data":"{\"discountAmount\":0,\"elapsedTime\":0,\"feeType\":2,\"gatewayId\":\"6c667a3feaf3efed20****\",\"inboundTime\":1654027371000,\"orderNo\":\"BK220531160251618p2102318191****\",\"paidAmount\":0,\"payableAmount\":0,\"plateNo\":\"A12345\",\"projectId\":\"164941079****\",\"sn\":\"153154673898344****\",\"startTime\":1654027371000}",
        "cmdBizType":"parking_result",
        "sn":"153154673898344****",
        "message":"",
        "happenTime":1653984172360
    }
}

Report result of querying current vehicle

The result format of the outer parameter command is the same as the general result format. The data parameter in the content is as follows:

Description of data

Parameter	Type	Description	Required
gatewayId	String	The gateway ID.	Yes
plateNo	String	The license plate number.	Yes
captureTime	Long	The time when a snapshot was captured.	Yes

Data example

{
  "bizCode": "cmdIssueResult",
  "devId": "6c873a4652689079b7****",
  "productKey": "lowdwphf3oid****",
  "ts": 1653982851495,
  "uuid": "bay1622429214496****",
  "bizData": {
    "processStatus": 3,
    "data": "{\"captureTime\":1653968629556,\"gatewayId\":\"6c667a3feaf3efed20****\",\"plateNo\":\"A12346\",\"projectId\":\"164941079****\",\"sn\":\"153154063487861****\"}",
    "cmdBizType": "parking_result",
    "sn": "153154063487861****",
    "message": "",
    "happenTime": 1653982851470
  }
}

Report vehicle pass records

API description

When a vehicle enters or leaves the parking lot, a pass record will be automatically reported. There will be a certain delay in reporting the pass records of some parking lots.

Parameters

Parameter	Type	Description	Required
bizCode	String	The business code of a specified event. The value is parking_pass_record here.	Yes
devId	String	The ID of a specified barrier gate.	Yes
productKey	String	The product ID.	Yes
ts	Long	The time when an event occurs.	Yes
bizData	Object	The business data.	Yes

Description of bizData

Parameter	Type	Description	Required
gatewayId	String	The gateway ID.	Yes
eventId	String	The ID of a reported event.	Yes
plateNo	String	The license plate number.	Yes
captureTime	Long	The time when a snapshot was captured.	Yes
passTime	Long	The time when a vehicle passes.	Yes
passDirection	String	The passing direction. Valid values: 1: enter 2: exit	Yes
openState	Integer	The working status of a specified barrier gate. Valid values: 1: normal 2: anomaly	Yes
inParkingId	String	The inbound ID of a specified vehicle.	Yes
imageUrl	String	The URL of a specified captured image.	No
plateDimension	Integer	The license plate of a specified vehicle. Valid values: 1: temporary parking 2: unlicensed 3: monthly payment 4: allowlist 6: purchased parking space 99: others	Yes
feeDimension	Integer	The payment of a specified vehicle. Valid values: 1: paid 2: free	Yes
passDimension	Integer	The release of a specified vehicle. Valid values: 1: manual 2: remote 3: automatic 4: anomaly	Yes
parkingLotId	String	The ID of a specified parking lot.	Yes
operatorId	String	The ID of a specified operator.	No
operatorName	String	The name of a specified operator.	No
remark	String	The remarks.	No

Example

{
  "bizCode": "parking_pass_record",
  "bizData": {
    "passDirection":1,
    "imageId":"4738da756fa3d9e9d28f5b128b3f****",
    "plantNo":"B3C3A3",
    "openState":1,
    "inParkingId":"DCI8fajYxIxYgOHh4m****",
    "passTime":1627267019000,
    "feeDimension":1,
    "type":"",
    "deviceId":"bc691cd7636de3b4ddcc87960748****",
    "plateDimension":1,
    "eventId":"f5050b19a4dc496b95f0ca0e3e56****",
    "projectId":"7fb88e7ae93a042f0aa37ea709a9****",
    "gatewayId":"6c17135068e42989cf****",
    "passDimension":3,
    "operatorId":"123***",
    "operatorName":"Jane***"
  },
  "devId": "6ce23ee0de009667c0****",
  "productKey": "hipg3mmwafxc****",
  "ts": 1637292665405
}

Report payment record of temporary vehicle

API description

After the order of a temporary vehicle is paid up, the parking lot will report a payment record.

Parameters

Parameter	Type	Description	Required
bizCode	String	The business code of a specified event. The value is parking_fee here.	Yes
devId	String	The ID of a specified device in the parking lot.	Yes
productKey	String	The product ID.	Yes
ts	Long	The time when an event occurs.	Yes
bizData	Object	The business data.	Yes

Description of bizData

Parameter	Type	Description	Required
gatewayId	String	The gateway ID.	Yes
eventId	String	The ID of a reported event.	Yes
feeType	Integer	The payment type. 1: long-term payment 2: temporary parking 3: withholding payment 4: unlicensed vehicle 5: unknown	Yes
beginTime	Long	The start time.	Yes
endTime	Long	The end time.	Yes
payTime	Long	The payment time.	Yes
payMode	Integer	The payment method. Valid values: 1: Alipay 2: WeChat 3: bank card 4: cash 5: others	Yes
chargeTotal	Long	The total receivable amount.	Yes
discountAmount	Long	The discount amount.	Yes
fee	Long	The received amount.	Yes
inParkingId	String	The inbound ID of a specified vehicle.	Yes
orderNo	String	The order ID.	Yes

Example

{
  "bizCode":"parking_fee",
  "bizData":{
    "beginTime":1653530742000,
    "chargeTotal":1000,
    "discountAmount":100,
    "endTime":1653617142000,
    "eventId":"12345",
    "fee":900,
    "feeType":2,
    "gatewayId":"6c667a3feaf3efed20****",
    "inParkingId":"6c5474318446ac99f3****",
    "orderNo":"12345",
    "payMode":1,
    "payTime":1653617142000
  },
  "devId":"6c5474318446ac99f3****",
  "productKey":"4dfsdq7a1akx****",
  "ts":165363832****,
  "uuid":"bay1622429214496****"
}

Report license plate correction record

API description

In some special scenarios, such as dark light and easily confused plate numbers, a license plate recognition error might occur in a parking lot. In this case, the parking lot staff needs to manually correct the license plate number. After correction, the parking lot will report the correction record.

Parameters

Parameter	Type	Description	Required
bizCode	String	The business code of a specified event. The value is parking_plate_correction here.	Yes
devId	String	The ID of a specified device in the parking lot.	Yes
productKey	String	The product ID.	Yes
ts	Long	The time when an event occurs.	Yes
bizData	Object	The business data.	Yes

Description of bizData

Parameter	Type	Description	Required
gatewayId	String	The gateway ID.	Yes
eventId	String	The ID of a reported event.	Yes
originalPlateNo	String	The original license plate number.	Yes
newPlateNo	String	The new license plate number.	Yes
modifyTime	Long	The time when it is modified.	Yes
inParkingId	String	The inbound ID.	Yes
operatorId	String	The ID of a specified operator.	No
operatorName	String	The name of a specified operator.	No
remark	String	The remarks.	No

Example

{
  "bizCode": "parking_plate_correction",
  "bizData": {
    "gatewayId":"002dj00118fe34d9****",
    "eventId":"159169336****",
    "originalPlateNo":"A1***5",
    "newPlateNo":"A1***6",
    "inParkingId":"123***",
    "modifyTime":1233,
    "operatorId":"123***",
    "operatorName":"Jane***"
  },
  "devId": "6ce23ee0de009667c0****",
  "productKey": "hipg3mmwafxc****",
  "ts": 1637292665405
}

Report parking lot information

API description

A parking lot reports its basic information, the total number of parking spaces, and the number of parking spaces already used.

Parameters

Parameter	Type	Description	Required
bizCode	String	The business code of a specified event. The value is parking_lot_info here.	Yes
devId	String	The ID of a specified device in the parking lot.	Yes
productKey	String	The product ID.	Yes
ts	Long	The time when an event occurs.	Yes
bizData	Object	The business data.	Yes

Description of bizData

Parameter	Type	Description	Required
gatewayId	String	The gateway ID.	Yes
eventId	String	The ID of a reported event.	Yes
parkingId	String	The ID of a specified parking lot.	Yes
parkingName	String	The name of a specified parking lot.	Yes
totalSpaceNum	Integer	The total number of parking spaces.	Yes
usedSpaceNum	Integer	The number of parking spaces already used.	Yes

Example

{
  "bizCode": "parking_lot_info",
  "bizData": {
    "gatewayId":"002dj00118fe34d9****",
    "eventId":"159169336****",
    "parkingId":"123***",
    "parkingName":"Test Parking Lot",
    "inParkingId":"123***",
    "totalSpaceNum":1000,
    "usedSpaceNum":20
  },
  "devId": "6ce23ee0de009667c0****",
  "productKey": "hipg3mmwafxc****",
  "ts": 1637292665405
}