가이드
기기
앱 연결 토큰으로 호출합니다.
매장 기기는 한 경로로 다룹니다. 목록으로 기기와 연결 상태를 보고, 명령으로 조작합니다.
목록과 단건
GET /device/v1/devices · GET /device/v1/devices/{id}
문은 kind가 door인 행입니다. 여기서 얻은 id가 명령의 {id}이고 출입 허가 doorIds의 값입니다.
| 필드 | 의미 |
|---|---|
id | 기기 ID |
name | 이름 |
health.state | online, offline, unknown(아직 한 번도 연결된 적 없음) |
capabilities | 받을 수 있는 명령 묶음 |
단건은 문의 지금 상태(standing)를 더합니다.
명령
POST /device/v1/devices/{id}/commands
Code
| 명령 | 동작 |
|---|---|
door.open | 잠깐 열기 |
door.hold | 열어두기 |
door.close | 잠그기 |
args.reason은 기록용입니다.
Idempotency-Key 헤더는 필수입니다. 없으면 400입니다. 요청마다 고유한 문자열(UUID 권장)을 넣습니다. 타임아웃 뒤 같은 값으로 다시 보내면 문이 두 번 열리지 않고 처음 결과가 돌아옵니다. 모든 호출이 출입 기록 GET /device/v1/entry-log에 남습니다.
결과
기기가 실제로 실행했다고 답한 뒤에 응답합니다. 성공은 200과 outcome: reported입니다.
실패는 details.reason으로 구분합니다.
reason | 의미 | 상태코드 |
|---|---|---|
offline | 연결 끊김. 명령을 보내지 않았습니다. | 409 |
refused | 기기가 거절했습니다. | 502 |
noResponse | 기기가 답하지 않았습니다. 실행됐는지 알 수 없습니다. | 504 |
504를 받으면 같은 Idempotency-Key로 다시 보냅니다. 처음 명령이 실행됐다면 그 결과가 돌아오고, 아니면 다시 시도합니다. 실제로 열렸는지는 GET /device/v1/entry-log로 확인합니다. health.state가 unknown인 기기는 아직 연결된 적이 없으니 offline과 같이 다룹니다.
Last modified on