Integration Process of Vehicle Services

Last Updated on : 2023-06-15 05:26:50

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.
  • You can go to Cloud > Message Service to view documents about message subscriptions.
  • The messages are delivered based on the cloud project dimension. You can create projects and perform operations such as message and data isolation.

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.

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
}