> For the complete documentation index, see [llms.txt](https://docs.hanchuess.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hanchuess.com/home/customer-lifecycle/onboarding.md).

# Onboarding

Once a user has given us permission to manage the devices on their account, partner ought to invoke assets list and registration enpoint provided by Hanchu, which device(s) needed to be selected for control. We will do this via your endpoints that we've defined below.

## List devices

## GET /{orgId}/v1/devices

> This endpoint enables customers to determine which device they would like to register.

```json
{"openapi":"3.0.4","info":{"title":"HanchuESS Connect API","version":"2.0.4"},"tags":[{"name":"Customer-Lifecycle"}],"servers":[{"url":"https://idaas-sandbox.hanchuess.com/portal"}],"security":[{"OAuth2Auth":["all"]}],"components":{"securitySchemes":{"OAuth2Auth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://idaas-sandbox.hanchuess.com/portal/oauth/token","scopes":{"all":"all privileges"}},"authorizationCode":{"authorizationUrl":"https://idaas-sandbox.hanchuess.com/portal/oauth/authorize","tokenUrl":"https://idaas-sandbox.hanchuess.com/portal/oauth/token","scopes":{"all":"all privileges"}}}}},"schemas":{"DeviceList":{"type":"object","properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/Device"}}}},"Device":{"type":"object","properties":{"assetId":{"type":"string","description":"Serial number"},"make":{"type":"string","description":"The manufacturer name of the inverter"},"model":{"type":"string","description":"The model name of the inverter"},"maximumImportPower":{"type":"number","minimum":1,"maximum":99999,"description":"Inverter max import power"},"maximumExportPower":{"type":"number","minimum":1,"maximum":99999,"description":"Inverter max export power"},"batteries":{"type":"array","description":"Empty array of batteries","items":{"$ref":"#/components/schemas/BatteryArray"}},"solarArrays":{"type":"array","items":{"$ref":"#/components/schemas/SolarArray"}}},"required":["assetId","make","model","maximumImportPower","batteries","solarArrays"]},"BatteryArray":{"type":"object","properties":{"make":{"type":"string","description":"The manufacturer name of the battery"},"model":{"type":"string","description":"The model name of the battery"},"usableCapacity":{"type":"number","minimum":1,"maximum":999999,"description":"The usable capacity for the battery in watt hours (Wh)"},"cycleLimit":{"type":"number","minimum":1,"maximum":999,"description":"Limit on battery cycles"},"maximumChargePower":{"type":"number","minimum":1,"maximum":99999,"description":"The maximum limit for which the device can charge in watts (W)"},"maximumDischargePower":{"type":"number","minimum":1,"maximum":99999,"description":"The maximum limit for which the device can discharge in watts (W)"},"gridImportRestricted":{"type":"boolean","description":"Whether import to the grid is restricted"},"gridExportRestricted":{"type":"boolean","description":"Whether export to the grid is restricted"}},"required":["make","model","usableCapacity","maximumChargePower"]},"SolarArray":{"type":"object","properties":{"maximumPower":{"type":"number","minimum":1,"maximum":999999,"description":"The maximum solar power in watts (W)"},"orientation":{"type":"string","description":"Solar orientation","enum":["n","ne","e","se","s","sw","w","nw"]},"tilt":{"type":"number","minimum":0,"maximum":90,"description":"Tilt of a solar array in degrees"},"independentlyControlled":{"type":"boolean","description":"Whether a solar array is monitored via a CT clamp"}},"required":["maximumPower"]},"Bad_Request":{"type":"object","properties":{"errno":{"type":"string"},"msg":{"type":"string"},"data":{"type":"string"}},"required":["errno","msg","data"]},"Unauthorized":{"type":"object","properties":{"errno":{"type":"string"},"msg":{"type":"string"},"data":{"type":"object","properties":{"token":{"type":"string","description":"Access token"}},"required":["token"]}},"required":["errno","msg","data"]},"Error":{"type":"object","properties":{"errno":{"type":"string"},"msg":{"type":"string"},"data":{"type":"object"}},"required":["errno","msg","data"]}}},"paths":{"/{orgId}/v1/devices":{"get":{"tags":["Customer-Lifecycle"],"description":"This endpoint enables customers to determine which device they would like to register.","operationId":"getDevices","parameters":[{"name":"orgId","in":"path","description":"Organization id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation was successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceList"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bad_Request"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"default":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Register device

## POST /{orgId}/v1/devices

> Once partner have called the register endpoint, we will configure backend to to send any telemetry data or events relating to that device, and to be able to receive any control signals.

```json
{"openapi":"3.0.4","info":{"title":"HanchuESS Connect API","version":"2.0.4"},"tags":[{"name":"Customer-Lifecycle"}],"servers":[{"url":"https://idaas-sandbox.hanchuess.com/portal"}],"paths":{"/{orgId}/v1/devices":{"post":{"tags":["Customer-Lifecycle"],"description":"Once partner have called the register endpoint, we will configure backend to to send any telemetry data or events relating to that device, and to be able to receive any control signals.","operationId":"doDeviceRegister","parameters":[{"name":"orgId","in":"path","description":"Organization id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assetId":{"type":"string","description":"Unique identifier of the device"}},"required":["assetId"]}}}},"responses":{"200":{"description":"Operation was successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceList"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bad_Request"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"404":{"description":"Device Does Not Exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound"}}}},"default":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"DeviceList":{"type":"object","properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/Device"}}}},"Device":{"type":"object","properties":{"assetId":{"type":"string","description":"Serial number"},"make":{"type":"string","description":"The manufacturer name of the inverter"},"model":{"type":"string","description":"The model name of the inverter"},"maximumImportPower":{"type":"number","minimum":1,"maximum":99999,"description":"Inverter max import power"},"maximumExportPower":{"type":"number","minimum":1,"maximum":99999,"description":"Inverter max export power"},"batteries":{"type":"array","description":"Empty array of batteries","items":{"$ref":"#/components/schemas/BatteryArray"}},"solarArrays":{"type":"array","items":{"$ref":"#/components/schemas/SolarArray"}}},"required":["assetId","make","model","maximumImportPower","batteries","solarArrays"]},"BatteryArray":{"type":"object","properties":{"make":{"type":"string","description":"The manufacturer name of the battery"},"model":{"type":"string","description":"The model name of the battery"},"usableCapacity":{"type":"number","minimum":1,"maximum":999999,"description":"The usable capacity for the battery in watt hours (Wh)"},"cycleLimit":{"type":"number","minimum":1,"maximum":999,"description":"Limit on battery cycles"},"maximumChargePower":{"type":"number","minimum":1,"maximum":99999,"description":"The maximum limit for which the device can charge in watts (W)"},"maximumDischargePower":{"type":"number","minimum":1,"maximum":99999,"description":"The maximum limit for which the device can discharge in watts (W)"},"gridImportRestricted":{"type":"boolean","description":"Whether import to the grid is restricted"},"gridExportRestricted":{"type":"boolean","description":"Whether export to the grid is restricted"}},"required":["make","model","usableCapacity","maximumChargePower"]},"SolarArray":{"type":"object","properties":{"maximumPower":{"type":"number","minimum":1,"maximum":999999,"description":"The maximum solar power in watts (W)"},"orientation":{"type":"string","description":"Solar orientation","enum":["n","ne","e","se","s","sw","w","nw"]},"tilt":{"type":"number","minimum":0,"maximum":90,"description":"Tilt of a solar array in degrees"},"independentlyControlled":{"type":"boolean","description":"Whether a solar array is monitored via a CT clamp"}},"required":["maximumPower"]},"Bad_Request":{"type":"object","properties":{"errno":{"type":"string"},"msg":{"type":"string"},"data":{"type":"string"}},"required":["errno","msg","data"]},"Unauthorized":{"type":"object","properties":{"errno":{"type":"string"},"msg":{"type":"string"},"data":{"type":"object","properties":{"token":{"type":"string","description":"Access token"}},"required":["token"]}},"required":["errno","msg","data"]},"NotFound":{"type":"object","properties":{"errno":{"type":"string"},"msg":{"type":"string"},"data":{"type":"object"}},"required":["errno","msg","data"]},"Error":{"type":"object","properties":{"errno":{"type":"string"},"msg":{"type":"string"},"data":{"type":"object"}},"required":["errno","msg","data"]}}}}
```
