getSnapkeyList (getSnapkeyList: Get a list of temporary keys)

getSnapkeyList: getSnapkeyList: Get a list of temporary keys

Legacy HTTP retained: New integrations can use Door and lock (detection.door) for the related capability. The two interfaces are not a one-to-one replacement. No registry one-to-one mapping for this door/doorbell HTTP method.

Function details

Obtain the temporary key list of the door lock device.

Request address

https://openapi-[DataCenter].easy4ip.com/openapi/getSnapkeyList

Request format

HTTP POST. JSON body layout: Request conventions. Sign with Signature.

Minimum permissions required for sub-account token request

The sub-account accessToken policy must include Config; device resource URI is dev:{deviceId}. See Permission codes.

Incoming parameter description

Parameter name	Parameter type	Required or not	Default value	Legal value	Parameter description
token	String	Yes			Administrator or sub-account accessToken
deviceId	String	Yes			Door lock device serial number

Sample input

{
 "system":{
 "ver":"1.0",
 "appId":"lcdxxxxxxxxx",
 "sign": "xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=",
 "time":1603350639,
 "nonce":"350f4c7a-a352-46cf-ae03-f4f526f5d99f"
 },
 "id":"b8f45dbb-79ad-4a7e-8b24-7eb618c5191f",
 "params":{
 "token":"At_00000ad9e6e87f0142eb92e207aec46a",
 "deviceId":"TESTQWERXXXX"
 }
}

Return data field description

Field	Type	Description
snapkeys.keyId	String	Secret key unique id
snapkeys.snapKey	String	Temporary secret key
snapkeys.name	String	Secret key name
snapkeys.status	String	Temporary key status, notUsed: not used; bUsed: used; failed: expired
snapkeys.createUtcTime	String	The Utc time when the secret key was created, in yyyyMMddTHHmmssZ format
snapkeys.createLocalTime	String	The local time of the secret key creation device, in yyyyMMddTHHmmssZ format
snapkeys.localTime	String	The local time of the device where the temporary key is invalid or used, in the format yyyyMMddTHHmmss
snapkeys.utcTime	String	The UTC time when the temporary key is invalid or used, in the format yyyyMMddTHHmmssZ
snapkeys.effectiveNum	String	Maximum effective unlock count (returned on some device models only)
snapkeys.effectTime	String	Validity time detail (some models only)
snapkeys.effectPeriod	String	Recurring effective period detail (some models only)

Sample output

{
 "id":"b8f45dbb-79ad-4a7e-8b24-7eb618c5191f",
 "result":{
 "code":"0",
 "msg":"The operation was successful",
 "data": {
 "snapkeys":[{
 "keyId":"100",
 "snapKey":"123456",
 "name":"Temporary Key 1",
 "status":"notUsed",
 "createUtcTime":"20170418T162832Z",
 "createLocalTime":"20170418T162832Z",
 "localTime":"20170418T163832",
 "utcTime":"20170418T163832Z",
 "effectiveNum":"3",
 "effectTime":"20170418T080000Z/20170418T200000Z",
 "effectPeriod":"1,2,3,4,5"
 }]
 }
 }
}

Error codes

This method may return the codes below. See Return codes and Capability errors for the full catalog.

Gateway and auth (SN / TK / OP)

Code	Meaning	Next step
`SN1001`	Signature error	Check `sign` per Development specification
`TK1002`	Token invalid or expired	Refresh accessToken
`OP1002`	Missing required parameter	Add required fields
`OP1003`	Invalid parameter	Match this page’s parameter table
`OP1009`	Permission denied	Check token and device bind/share grants
`OP1013`	Total call limit exceeded	Reduce call rate
`OP1014`	Daily per-interface limit exceeded	See Interface call limits
`DV1007`	Device offline	Wait until the device is online

See Return codes · OP/SN/TK for the full catalog.

Sub-accounts (SUB)

Code	Meaning	Next step
`SUB1001`–`SUB1002`	Sub-account lacks API permission	Update policy via addPolicy
`SUB1005`	Sub-account token expired	Refresh subAccountToken
`SUB1006`	No device grant for sub-account	Check `Resource` and device serial
`SUB1008`	Sub-account not bound to app	Create and bind the sub-account first

See Return codes · SUB.

Device access and channels (DV10xx)

Code	Meaning	Next step
`DV1007`	Device offline or timeout	Wait for the device to come online
`DV1009`	Device busy	Retry later
`DV1012`	Insufficient share/grant permission	Check sub-account `Permission` / `Resource`
`DV1019`	Capability not supported	Confirm model and capability list
`DV1020`	Channel offline	Check channel status
`DV1026`	Function not supported	Use another API or upgrade firmware
`DV1028`	Not bound or channel missing	Verify `deviceId` / `channelId`

See Return codes · DV.

Lock and doorbell (DV10xx)

Code	Meaning	Next step
`DV1016`	Device password error	Verify lock password
:---	:---	:---
`DV1038`	Battery too low for temporary key	Charge and retry
:---	:---	:---
`DV1039`	Temporary key conditions not met	Adjust parameters per this page
:---	:---	:---
`DV1050`	Temporary key count limit	Delete old keys or wait
:---	:---	:---
`DV1070`	Doorbell/intercom busy	Retry or hang up

See Return codes · catalog.