APIs Related to Construction maintenance work order Management

Construction and maintenance work order management is to delegate the construction and maintenance work order to service providers via API and to complete the construction process on the service provider Saas.

API List

Request method	API	description
POST	/v1.0/osaas/projects/{project_id}/construction/order	API for Creating a Construction Work Order.
GET	/v1.0/osaas/construction/orders	API for Obtaining the List of Construction Work Orders.
GET	/v1.0/osaas/construction/orders/{order_id}	API for Obtaining Details of a Construction Work Order.
POST	/v1.0/osaas/projects/{project_id}/maintenance/order	API for Creating a Maintenance Work Order.
GET	/v1.0/osaas/maintenance/orders	API for Obtaining the List of Maintenance Work Orders.
GET	/v1.0/osaas/maintenance/orders/{order_id}	API for Obtaining Details of a Maintenance Work Order.

API for Creating a Construction Work Order

API Description

You can use this API to create a construction work order.

API Address

POST /v1.0/osaas/projects/{project_id}/construction/order

Request Parameters

Parameter	Type	Position	Description	Mandatory
project_id	String	URI	Unique ID of a project.	Yes
contractor_uid	String	BODY	Unique ID of a constructor.	Yes
room_ids	String[]	BODY	List of unique IDs of rooms.	Yes
zigbee_categories	Arrays	BODY	Zigbee category set.	No
wifi_categories	Arrays	BODY	Wi-Fi category set.	No

Parameters in zigbee_categories

Parameter	Type	Position	Description	Mandatory
quantity	Integer	BODY	Number of devices.	Yes
category	String	BODY	Product category.	Yes

Parameters in wifi_categories

Parameter	Type	Position	Description	Mandatory
quantity	Integer	BODY	Number of devices.	Yes
category	String	BODY	Product category.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	String	Unique ID of a work order.

Request Example

POST {url}/v1.0/osaas/projects/1233823965*******/construction/order

{
  "contractor_uid": "bay******fcDz",
  "room_ids": [
    "1160823965053******"
  ],
  "zigbee_categories": [
    {
      "quantity": 1,
      "category": "zig_cz"
    }
  ],
  "wifi_categories": [
    {
      "quantity": 1,
      "category": "wf_dj"
    }
  ]
}

Success Response Example

{
  "result": "11298837765053******",
  "success": true,
  "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining the List of Construction Work Orders

API Description

You can use this API to obtain the list of construction work orders.

API Address

GET /v1.0/osaas/construction/orders

Request Parameters

Parameter	Type	Position	Description	Mandatory
page_no	Integer	URL	Page number.	No
page_size	Integer	URL	Number of records on a page, which is greater than 0 and less than 100.	No
project_id	String	URL	Unique ID of a project.	No
contractor_uid	String	URL	Unique ID of a constructor.	No
construction_status	String	URL	Construction status. The values are as follows: UNASSIGNED: unassigned PENDING_CONSTR UCTION: to be constructed IN_CONSTRUCTION: being constructed PENDING_ACCEPTANCE: to be accepted ACCEPTANCE_COMPLETE: accepted	No
construction_begin_begin_time	Long	URL	Start time when construction starts,which is a 13-digit timestamp.	No
construction_begin_end_time	Long	URL	End time when construction starts, which is a 13-digit timestamp.	No
construction_end_begin_time	Long	URL	Start time when construction ends, which is a 13-digit timestamp.	No
construction_end_end_time	Long	URL	End time when construction ends, which is a 13-digit timestamp.	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
total	Integer	Total number of records.
page_no	Integer	Page number.
page_size	Integer	Number of records on a page.
construction_orders	Arrays	List of construction work orders.

Parameters in result.construction_orders

Parameter	Type	Description
order_id	String	Unique ID of a construction work order.
contractor_name	String	Constructor name.
project_id	String	Project ID.
project_name	String	Project name
room_quantity	Integer	Number of rooms.
device_quantity	Integer	Number of devices.
construction_status	String	Construction status. The values are as follows: UNASSIGNED: unassigned PENDING_CONSTR UCTION: to be constructed IN_CONSTRUCTION: being constructed PENDING_ACCEPTANCE: to be accepted ACCEPTANCE_COMPLETE: accepted
begin_time	Long	Construction start time, which is a 13-digit timestamp.
end_time	Long	Construction end time, which is a 13-digit timestamp.

Request Example

GET {url}/v1.0/osaas/construction/orders

Success Response Example

{
  "result": {
    "total": 1,
    "page_no": 1,
    "page_size": 20,
    "construction_orders": [
      {
        "order_id": "12550217287xxxxxxxx",
        "contractor_name": "XXX 服务商",
        "project_id": "1233224487xxxxxxxx",
        "project_name": "测试项目",
        "room_quantity": 0,
        "device_quantity": 6,
        "construction_status": "ACCEPTANCE_COMPLETE",
        "begin_time": 1559707046000,
        "end_time": 1559707046000
      }
    ]
  },
  "success": true,
  "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining Details of a Construction Work Order

API Description

You can use this API to obtain details of a construction work order.

API Address

GET /v1.0/osaas/construction/orders/{order_id}

Request Parameters

Parameter	Type	Position	Description	Mandatory
order_id	String	URI	Unique ID of a work order.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
order_id	String	Unique ID of a construction work order.
contractor_name	String	Constructor name.
project_id	String	Project ID.
project_name	String	Project name.
construction_status	String	Construction status. The values are as follows: UNASSIGNED: unassigned PENDING_CONSTR UCTION: to be constructed IN_CONSTRUCTION: being constructed PENDING_ACCEPTANCE: to be accepted ACCEPTANCE_COMPLETE: accepted
begin_time	Long	Construction start time, which is a 13-digit timestamp.
end_time	Long	Construction end time, which is a 13-digit timestamp.
zigbee_categories	Arrays	Zigbee category set.
wifi_categories	Arrays	Wi-Fi category set.
room_ids	Arrays	List of unique IDs of rooms.

zigbee_categories、Parameters in wifi_categories

Parameter	Type	Description
quantity	Integer	Number of devices.
category	String	Product category.
name	String	Category name.

Parameters in room_device_relations

Parameter	Type	Description
room_id	String	Unique ID of a room.
device_ids	Arrays	List of unique IDs of devices.

Request Example

GET {url}/v1.0/osaas/construction/orders/12550217287******

Success Response Example

{
  "result": {
    "order_id": "12550217287******",
    "contractor_name": "****** Service provider",
    "project_id": "1233224487******",
    "project_name": "Test Project",
    "construction_status": "ACCEPTANCE_COMPLETE",
    "begin_time": 1559707046000,
    "end_time": 1559707046000,
    "zigbee_categories": [
      {
        "category": "wf_zig_wfcon",
        "quantity": 1
      }
    ],
    "wifi_categories": [
      {
        "category": "wf_dj",
        "name": "Light",
        "quantity": 1
      }
    ],
    "room_device_relations": [
      {
        "room_id": "1452678965053******",
        "device_ids": [
          "00122433******"
        ]
      }
    ]
  },
  "success": true,
  "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Creating a Maintenance Work Order

You can use this API to create a maintenance work order. Maintenance work orders cannot be created for infrared subdevices. If a maintenance work order is required for an infrared subdevice, you can select its parent device.

API Address

POST /v1.0/osaas/projects/{project_id}/maintenance/order

Request Parameters

Parameter	Type	Position	Description	Mandatory
project_id	String	URI	Unique ID of a project.	Yes
contractor_uid	String	BODY	Unique ID of a constructor.	Yes
room_device_relations	Arrays	BODY	List of room device relationships.	Yes

Parameters in room_device_relations

Parameter	Type	Position	Description	Mandatory
room_id	String	BODY	Unique ID of a room.	Yes
device_ids	Arrays	BODY	List of unique IDs of devices.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	String	Unique ID of a work order.

Request Example

POST {url}/v1.0/osaas/projects/123382396505312xxxxx/maintenance/order

{
  "contractor_uid": "bay*******fcDz",
  "room_device_relations": [
    {
      "room_id": "145267896505*******",
      "device_ids": [
        "00122433*******"
      ]
    }
  ]
}

Success Response Example

{
  "success": true,
  "result":"123*******",
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining the List of Maintenance Work Orders

API Description

You can use this API to obtain the list of maintenance work orders.

API Address

GET /v1.0/osaas/maintenance/orders

Request Parameters

Parameter	Type	Position	Description	Mandatory
page_no	Integer	URL	Page number.	No
page_size	Integer	URL	Number of records on a page, which is greater than 0 and less than 100.	No
project_id	String	URL	Unique ID of a project.	No
contractor_uid	String	URL	Unique ID of a constructor.	No
maintenance_status	String	URL	Maintenance status. The values are as follows: UNASSIGNED: unassigned PENDING_MAIN TENANCE: to be maintained IN_MAINTENANCE: being maintained PENDING_ACCE PTANCE: to be accepted ACCEPTANCE_ COMPLETE: accepted	No
maintenance_begin_begin_time	Long	URL	Start time when maintenance starts, which is a 13-digit timestamp.	No
maintenance_begin_end_time	Long	URL	End time when maintenance starts, which is a 13-digit timestamp.	No
maintenance_end_begin_time	Long	URL	Start time when maintenance ends, which is a 13-digit timestamp.	No
maintenance_end_end_time	Long	URL	End time when maintenance ends, which is a 13-digit timestamp.	No

Response Parameters

Parameter	Type	Description
code	Integer	Response Parameters
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
total	Integer	Total number of records.
page_no	Integer	Page number.
page_size	Integer	Number of records on a page.
maintenance_orders	Arrays	List of maintenance work orders.

Parameters in result.maintenance_orders

Parameter	Type	Description
order_id	String	Unique ID of a maintenance work order.
contractor_name	String	Constructor name.
project_id	String	Project ID.
project_name	String	Project name
room_quantity	Integer	Number of rooms.
device_quantity	Integer	Number of devices.
maintenance_status	String	Maintenance status. The values are as follows: UNASSIGNED: unassigned PENDING_MAINTENANCE: to be maintained IN_MAINTENANCE: being maintained PENDING_ACCEPTANCE: to be accepted ACCEPTANCE_COMPLETE: accepted
begin_time	Long	Maintenance start time, which is a 13-digit timestamp.
end_time	Long	Maintenance end time, which is a 13-digit

Request Example

GET {url}/v1.0/osaas/maintenance/orders

Success Response Example

{
  "result": {
    "total": 1,
    "page_no": 1,
    "page_size": 100,
    "maintenance_orders": [
      {
        "order_id": "12550217287******",
        "contractor_name": "*** Service provider",
        "project_id": "123322448******",
        "project_name": "Test project",
        "room_quantity": 0,
        "device_quantity": 6,
        "maintenance_status": "ACCEPTANCE_COMPLETE",
        "begin_time": 1559707046000,
        "end_time": 1559707046000
      }
    ]
  },
  "success": true,
  "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining Details of a Maintenance Work Order

API Description

API for Obtaining Details of a Maintenance Work Order.

API Address

GET /v1.0/osaas/maintenance/orders/{order_id}

Request Parameters

Parameter	Type	Position	Description	Mandatory
order_id	String	URI	Unique ID of a work order.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response Parameters
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
order_id	String	Unique ID of a maintenance work order.
contractor_name	String	Constructor name.
project_id	String	Project ID.
project_name	String	Project name
room_quantity	Integer	Number of rooms.
maintenance_status	String	Maintenance status. The values are as follows: UNASSIGNED: unassigned PENDING_MAINTENANCE: to be maintained IN_MAINTENANCE: being maintained PENDING_ACCEPTANCE: to be accepted ACCEPTANCE_COMPLETE: accepted
begin_time	Long	Maintenance start time, which is a 13-digit timestamp
end_time	Long	Maintenance end time, which is a 13-digit
room_device_relations	Arrays	timestamp. List of room device relationships.

Parameters in room_device_relations

Parameter	Type	Description
room_id	String	Unique ID of a room.
device_ids	Arrays	List of unique IDs of devices.

Request Example

GET {url}/v1.0/osaas/maintenance/orders/12550217287******

Success Response Example

{
  "result": {
    "order_id": "12550217287******",
    "contractor_name": "*** Service provider",
    "project_id": "1233224487******",
    "project_name": "Test project",
    "begin_time": 1559707046000,
    "end_time": 1559707046000,
    "maintenance_status": "ACCEPTANCE_COMPLETE",
    "room_device_relations": [
      {
        "room_id": "1452678965053******",
        "device_ids": [
          "00122433******"
        ]
      }
    ]
  },
  "success": true,
  "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

Error Code

The following are common business exceptions for this interface. For more exception errors, see Global Error Codes.

error code	explain
500	system error