IoT 계량기: 장치 등록 및 계량값 서명 방법

IoT 장치: AMI 또는 IoT 엔드포인트를 등록하고, 비밀 키를 복사(한 번만 표시됨)하고, 새 비밀 키로 교체하고, 장치가 /api/public/utilities/iot/reads에 대한 각 요청에 서명하는 방법(예시 요청, 제한 사항 및 받을 수 있는 모든 응답 포함)을 설명합니다.

AMI 또는 IoT 계량기는 HTTPS를 통해 TRANXACT 에 자체 측정값을 게시합니다. 각 장치는 서버에서 생성한 키(utd_ 뒤에 24개의 문자와 숫자가 붙음)와 비밀 키를 가지고 있습니다. 장치는 모든 요청에서 자신이 누구인지 증명하므로 다른 누구도 해당 계량기의 측정값을 게시할 수 없습니다.

기기 등록

CRM > 유틸리티 > 유틸리티 계량기 및 판독 > IoT 장치를 열고 새로 만들기를 누르세요.
레이블을 입력하고, 읽을 계량기를 선택한 다음, 서명 방식으로 hmac(각 요청에 대한 HMAC-SHA256 서명 - 권장), bearer(토큰으로 전송되는 키와 비밀 키) 또는 둘 다를 선택하십시오.
이 장치의 분당 최대 읽기 횟수를 설정하고, 펌웨어 버전을 알고 있다면 펌웨어 버전도 설정하십시오.
저장하세요. 답변에 키와 비밀 키가 표시됩니다. "지금 비밀 키를 복사하세요. 다시 표시되지 않습니다." 두 가지 모두 장치 설정에 입력하세요.

비밀 키는 한 번만 표시됩니다. 이후에는 관리자를 포함하여 누구에게도 다시 표시되지 않습니다. 목록에는 마지막 네 글자("비밀 키 끝")만 표시됩니다. 비밀 키를 분실한 경우 새로 발급받으세요.

비밀을 회전시키다

기기 목록에서 '새 비밀번호'를 누르고 확인하세요. 새 비밀번호는 한 번만 표시되며, 이전 비밀번호는 즉시 사용 중지됩니다. 따라서 기기에 새 비밀번호를 즉시 입력하세요. 기기를 회전시키지 않고 사용을 중지하려면 상태를 '사용 중지됨'으로 설정하고, 서비스에서 제외될 때는 '사용 중지됨'으로 설정하세요.

기기가 측정값을 기록하는 방법

JSON 본문을 구성합니다. 이 본문에는 읽기 시간(ISO 8601 시간)과 읽기 데이터가 포함된 읽기 목록이 포함됩니다. 배터리, 신호, 펌웨어 및 알람 정보는 선택 사항입니다.
현재 유닉스 시간을 초 단위로 타임스탬프로 사용합니다.
장치 비밀 키를 사용하여 타임스탬프, 마침표, 그리고 본문의 정확한 바이트("<타임스탬프>.<본문>")를 HMAC-SHA256으로 계산합니다. 그 결과를 64자리 소문자 16진수로 출력합니다.
본문을 /api/public/utilities/iot/reads로 POST하고 헤더에 X-Utility-Device(키), X-Utility-Timestamp 및 X-Utility-Signature(16진수, 선택적으로 sha256= 접두사 추가)를 포함합니다.

POST https://<your-tranxact-host>/api/public/utilities/iot/reads
Content-Type: application/json
X-Utility-Device: <utd_DEVICE_KEY>
X-Utility-Timestamp: <1792252800>
X-Utility-Signature: sha256=<64 hex characters>

{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}],
 "battery_pct":<87>,"signal_dbm":<-71>,"firmware":"<2.4.1>",
 "alarms":[{"type":"<leak>","detail":"<continuous flow 6 h>"}]}

동일한 서명이 셸에서 작동하여 장치를 설치하기 전에 테스트할 수 있었습니다.

BODY='{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "<DEVICE_SECRET>" | sed 's/^.* //')
curl -X POST "https://<your-tranxact-host>/api/public/utilities/iot/reads" \
  -H "Content-Type: application/json" \
  -H "X-Utility-Device: <utd_DEVICE_KEY>" \
  -H "X-Utility-Timestamp: $TS" \
  -H "X-Utility-Signature: sha256=$SIG" \
  --data-binary "$BODY"

보내는 바이트에 정확히 서명하십시오. 서명 후 JSON 형식을 변경하거나 다른 줄 바꿈 문자를 사용하여 전송하면 바이트가 변경되어 서명이 더 이상 일치하지 않습니다.

베어러(또는 둘 다)로 설정된 장치는 Authorization: Bearer <utd_DEVICE_KEY>.<DEVICE_SECRET>와 같은 서명 헤더 없이 전송할 수 있습니다. HMAC는 더 안전한 선택입니다. 비밀 키는 전송되지 않으며, 캡처된 요청은 재사용할 수 없습니다.

제한

타임스탬프는 서버 시계와 5분 이내의 오차 범위 내에 있어야 합니다. 기기의 시계는 NTP로 설정해 두십시오.
동일한 서명된 요청이 두 번 전송되면 재전송 요청으로 간주되어 거부됩니다. 이미 파일에 있는 읽기 작업은 중복으로 간주되어 한 번만 저장됩니다.
최대 64KB의 데이터 읽기 및 500회 읽기 요청, 기기 자체의 분당 최대 읽기 횟수, 그리고 한 주소에서 분당 최대 600건의 요청이 허용됩니다.
해당 장치는 작동 중이어야 하며 계량기에 연결되어 있어야 합니다.

기기가 반환하는 값

답변	의미
승인됨, 중복됨, 예외, 거부됨, 경고 및 문제가 포함된 201 또는 200	요청이 접수되었습니다. 각 읽기 작업은 집계되며, 인덱스가 유효하지 않은 읽기 작업은 문제(problem)로 표시됩니다.
401 device_auth	알 수 없거나 비활성화된 키, 잘못된 모드 또는 일치하지 않는 서명입니다. 장치의 거부 횟수가 증가합니다.
401 오래된 타임스탬프	타임스탬프가 5분 이상 차이가 납니다.
409 리플레이	서명된 요청서는 이미 접수되었습니다.
413 너무 많이 읽었습니다	한 번의 요청으로 500회 이상 조회되었습니다.
422 미터 없음	해당 장치는 계량기에 연결되어 있지 않습니다.
429 요금 제한됨	전송 속도가 제한 속도를 초과했습니다. 잠시 기다렸다가 다시 보내주세요.
400 bad_json	본문은 JSON 형식이 아닙니다.
403 유틸리티_꺼짐	해당 회사의 공공요금 공급이 중단되었습니다.

건강 및 경보

각 요청은 기기의 마지막 접속 시간, 배터리 잔량(%) 및 신호 강도(dBm)를 업데이트합니다. 배터리 잔량이 15% 미만이면 배터리 부족 경보가 울립니다.
기기가 보낼 수 있는 알람 유형은 배터리 부족, 변조, 누수, 역류, 유량 없음, 오프라인 및 기타가 있습니다. 기기당 각 유형별로 하나의 알람만 활성화할 수 있습니다.
장치 경보 목록에는 경보가 표시되며, '지우기'를 클릭하면 메모와 함께 경보가 종료됩니다. 누출이 발생하면 즉시 우선순위가 높은 누출 조사 서비스 주문이 생성되며, 변조 또는 역류 경보가 발생할 경우에도 서비스 주문이 생성됩니다.
대시보드의 IoT 미터 보고(24시간) 수치는 지난 하루 동안 신호가 수신된 활성 장치 수를 나타냅니다.