개요
앱에서 누른 기기 제어가 실제 월패드까지 가려면 네 단계를 거침.
앱 → 우리 WAS(MAW) → 홈넷사 서버 → 단지 내 게이트웨이(월패드)
각 구간의 성격이 다르고, 장애가 어느 구간에서 났는지 가르는 것이 문제 해결의 절반임.
- 앱 → WAS:
homez-m.lh.or.kr로 들어옴. 앱이 네트워크 오류로 막으면 요청 자체가 WAS에 도달하지 않음 - WAS → 홈넷사 서버: HTTPS. 우리 쪽은 클라우드 서버이고, 홈넷 서버는 방화벽으로 막혀 있어 클라우드에서만 호출할 수 있음
- 홈넷사 서버 → 게이트웨이: 단지 내 로컬 네트워크. 여기가 불안정하면 타임아웃이 남. 우리가 손댈 수 없는 구간임
인증
단지마다 홈넷 서버가 따로 있고, 각각 인증이 걸려 있음.
- 우리가 단지별로 Client ID, Client Secret, sbd ID, TLS 인증서를 발급해 홈넷사에 전달함.
- 홈넷사는 이 정보로
client_credentials방식의 access token을 발급받음. - 발급받은 access token은 1시간마다 바뀜. 점검할 때는 새로 발급받지 말고 홈넷서버연동토큰상세 테이블에 저장된 토큰을 쓸 것.
- 이후 API 호출은
Authorization: Bearer <token>으로 함.
연동 규격 V1.0/V1.1이 둘 다 동작함(trace_id, sbd_id 파라미터 유무 차이). 2026-09 기준 수신함/의 최신 규격서는 V1.4임.
연동을 시작하려면 관리자 시스템에서 연동 시험 시작(홈넷 서버 연동 시작) 을 눌러야 함. 이걸 안 누르면 DB의 홈넷 연동 상태 코드(hnet_lnkg_ss_cd)가 ON이 아니라서, 홈넷사가 토큰을 받으려(POST /api/ccg/authcheck) 할 때 CustomJdbcTokenStore.storeAccessToken()에서 Could not find hnsver_sn(...) on del_yn(N) and hnet_lnkg_ss_cd(ON) 오류가 나며 500 + 5001로 떨어짐.
우리 WAS → 홈넷 서버 방향의 HTTPS는 우리 CA(lh-smah-ca-2024)로 발급한 인증서를 검증함. 홈넷 서버는 외부망이라 WAS에서 Squid 프록시를 거쳐 나감.
TLS 인증서의 유효기간은 1년임. 매년 같은 시기에 만료로 인한 조회 실패가 재발함. 발급·재발급 절차는 기본매뉴얼/운영/홈넷 서버 연동 (인증서 발급)에 있음.
LH → 홈넷 방향 토큰 (APW가 발급받음)
위 인증은 홈넷사가 우리를 부를 때 쓰는 토큰임. 반대로 우리가 홈넷서버를 부를 때(기기 제어, 승강기 호출, 단말기 조회)는 APW가 홈넷서버의 POST /api/ccg/authcheck에서 토큰을 받아 씀. 서버 구조는 공개노트/개발/모듈/APW 연계 서버.
- 인증 정보는
cmn.tb_hnsvr_m의lh_pltfrm_id,lh_pltfrm_scrtkey(홈넷사가 발급해 준 값). Basic 인증 +grant_type=client_credentials,trace_id,sbd_id - 받은 토큰은
cmn.tb_hnsvr_lnkg_tkn_d에 저장. 만료까지 10분 넘게 남았으면 재사용, 10분 이하면 재발급 - 발급 요청 타임아웃 20초. Squid 프록시를 거쳐 나감
- 홈넷 URL은
tb_hnsvr_m.hnsvr_ipad에 포트가 없으면:8094를 자동으로 붙임. 홈넷사가 다른 포트를 쓰면 DB에호스트:포트로 넣을 것 - 홈넷서버 응답 대기는 최대 10분(WebClient 타임아웃). 응답이 없으면 그만큼 기다림
발급 전 검증 4가지. 하나라도 걸리면 요청조차 보내지 않음. “특정 단지만 제어가 안 된다”면 이 순서로 봄.
| 조건 | 로그 문구 |
|---|---|
tb_hnsvr_m.del_yn = 'Y' | 사용하지 않는 홈넷서버입니다. |
hnet_lnkg_ss_cd != 'ON' (연동 시험 시작 안 누름) | 홈넷연동상태코드를 확인해주세요. |
lh_pltfrm_id 또는 lh_pltfrm_scrtkey 비어 있음 | 홈넷서버로부터 발급 받은 LH플랫폼 인증정보가 없습니다. |
hnsvr_ipad 비어 있음 | 홈넷 서버 도메인 정보 없음 |
간헐적으로 안 되면 토큰 만료 10분 경계를 의심함. 로그 토큰 만료예정시각이, 홈넷서버로부터 토큰 요청 실패함. 로그에 ssl secure 모드가 해제 되었으니 주의필요 가 찍히면 local 프로필 설정이 운영에 잘못 들어간 것임.
MAW는 토큰을 보관하지 않음
앱 요청을 처리하는 MAW는 토큰을 직접 발급받지 않고 APW의 홈넷서버 토큰 조회 API에서 매번 받아 씀(2026-09-18 코드 확인). 공개노트/개발/모듈/MAW 앱 API 서버
- 캐시가 없음. Redis에도, 메모리에도, DB에도 저장하지 않음. MAW 쪽 홈넷 토큰 테이블을 다루는 코드는 전부 주석 처리되어 쓰지 않음
- 유효기간을 해석하지 않음. 응답에 만료 시각이나 남은 초가 없고 토큰 문자열만 받음
- 갱신 주기가 없음. 홈넷서버를 부르는 API마다 매 요청 토큰을 새로 조회함. 기기 목록 조회 1건에도 토큰 조회 1회가 붙음
- 토큰 조회 타임아웃은 3초임(과거 20초에서 줄임)
- 따라서 캐싱·만료·재발급은 전부 APW 책임임
“우리집제어가 전부 안 된다 / 로딩만 돈다” 는 이 토큰 조회가 3초 안에 응답하지 못하는 상황을 먼저 의심함. MAW 로그에는
API Error또는홈넷사 API 호출중 오류 발생만 남고 원인은 APW 쪽에 있음. 홈넷사가 토큰 정책을 바꾸면 MAW는 고칠 것이 없고 APW만 보면 됨. 공통 상수 테이블에 APW 주소·내부 API 키가 없으면 모든 홈넷 연동이 데이터 없음(SQI0002)으로 죽음.
연동 상태 코드를 보는 곳과 안 보는 곳
hnet_lnkg_ss_cd = 'ON'을 요구하는 경로와 그렇지 않은 경로가 섞여 있음(2026-09-18 코드 확인).
| 경로 | ON 요구 |
|---|---|
| APW 토큰 발급 | O |
| MAW 승강기 호출(건설임대) | O |
| MAW 기기 제어·기기 목록 | X |
확인 필요
MAW의 기기 제어 경로는 연동 상태 코드를 보지 않아, 연동을
OFF로 내려도 기기 제어 요청은 계속 홈넷서버로 나감. 반대로 승강기 호출만ON을 요구해 “기기 제어는 되는데 승강기만 안 되는” 단지가 나올 수 있음. 의도된 차이인지 담당자 확인 필요.
누가 홈넷서버를 부르는가 (2026-09-18 확정)
입주민 앱 경로는 APW 홈넷 프록시를 거치지 않음. MAW 코드 1~3편 전 범위에 APW 홈넷 프록시를 부르는 곳이 없음. MAW는 홈넷서버를 직접 부르고, APW에는 홈넷 토큰·푸시·SMS·이벤트만 맡김. APW 홈넷 프록시를 쓰는 것은 가전사 앱 쪽(PIW) 임 → 공개노트/개발/모듈/PIW 연계 서버.
응답 타임아웃이 경로마다 다름 — 입주민 앱(MAW 직접) 3초, 가전사 앱(APW 프록시) 10분. “제어가 오래 걸린다”의 원인 판정이 갈리므로 어느 앱에서 온 문의인지 먼저 확인할 것.
우리가 홈넷서버에 호출하는 API
| 홈넷 경로 | 용도 | 부르는 서버 |
|---|---|---|
POST /api/ccg/authcheck | 토큰 발급 | APW |
GET /api/um/devices | 세대 기기 목록·상태 | MAW(입주민 앱), APW(가전사 앱 프록시) |
POST /api/um/devices/command | 기기 제어 | MAW(입주민 앱), APW(가전사 앱 프록시), SCW(AutoDR·예약) |
POST /api/um/subscribeDeviceEvt | 상태변경 이벤트 구독·해지 | APW |
POST /api/um/elevator | 승강기 호출 | MAW(입주민 앱), APW(가전사 앱 프록시) |
GET /api/um/visits | 방문 내역(목록·상세) | MAW |
GET /api/um/vehicles | 입출차 내역 | MAW |
GET·POST·DELETE /api/um/visitorCars | 방문차량 예약 조회·등록·삭제 | MAW |
GET /api/um/evcharge | 세대 전기차 충전 상태 | MAW |
GET·POST /api/um/goals | 에너지 월 목표량 조회·저장 | MAW |
POST /api/lh2hn/lhHouseholdEvent | 세대 이벤트(전출 등) 전달 | APW |
GET /api/um/gateways | 세대 단말기 상태 | APW |
GET /api/lh2hn/gateways | 홈넷서버 전체 세대 단말기 목록 | APW (LMW 요청 시), SCW |
MAW가 부르는 경로는 전부 응답 타임아웃 3초임. 방문 내역은 목록 1건마다 상세를 다시 부르므로 건수가 많으면 누적으로 느려짐. 방문주차 등록·취소는 1초 대기 후 재조회가 붙어 홈넷 왕복이 여러 번 일어남. 공개노트/개발/모듈/MAW 세대·헬스케어 API
홈넷서버가 우리를 부르는 API(/api/hn2lh/*: 이벤트, heartbeat, 기기 목록 보고, 공지·관리비·투표 조회)는 공개노트/개발/모듈/APW 연계 서버에 목록이 있음.
상태 확인
홈넷사가 1시간마다 heart beat를 보냄. APW POST /api/hn2lh/heartbeat로 들어와 smah.tb_hnsvr_brf_l에 남음. 관리자 시스템의 최종 내역 생성 일시가 이 값임. 이 값이 최근이면 홈넷 서버는 살아 있다는 뜻이므로, 홈넷사에 장애를 알릴 때 이 사실을 같이 적음.
결과 코드
홈넷 서버 연동 규격(V1.4)의 결과 코드임. 로그에서 result_code나 resultCd로 나옴.
| HTTP | result_code | 뜻 |
|---|---|---|
| 200 | 2000 | 정상 처리 |
| 200 | 1999 | 실패 |
| 401 | 4003 | 필요한 인증정보를 제공하지 않음 |
| 401 | 4015 | 잘못된 AccessToken |
| 401 | 4013 | 인증서버 장애로 토큰 검증 불가 |
| 401 | 4041 | 해당 권한으로 제공되지 않는 URL |
| 401 | 4019 | AccessToken 정보 확인 중 오류 |
| 401 | 4099 | 인증 처리 과정 중 오류 |
| 200 | 5011 | 해당 세대 정보가 없음 |
| 200 | 5012 | 필수 파라미터 누락 |
| 200 | 5013 | 해당 데이터가 없음 |
| 200 | 5014 | 필수 입력 파라미터 값이 잘못됨 |
| 200 | 5016 | 홈넷 인증 정보가 존재하지 않음 |
| 200 | 5017 | 해당 인증정보로 대상 단지에 접근 불가 (다른 홈넷사의 단지를 조회) |
| 405 | 4051 | API 호출 메소드(GET/POST) 오류 |
| 400 | 4101 | 명령 대상 기기 아이디 미존재 |
| 500 | 5999 | 기기 명령 수행 실패 |
| 200 | 2999 | 게이트웨이/기기 목록 조회 시 정보 없음 |
| 200 | 2101 | 제어 대상 기기 아이디 미존재 |
| 200 | 2102 | 미전입 세대 제어 요청 |
| 200 | 2111 | 동일 날짜·동일 차량번호로 기 등록된 요청 |
| 200 | 2112 | 삭제 대상 방문차량 미존재 |
| 200 | 2121 | 동일 이름·얼굴 기 등록된 요청 |
| 200 | 2123 | 삭제 대상 이름·얼굴 미존재 |
| 200 | 9071 | 전기차 충전상태 조회 서비스 제공 불가 |
| 200 | 9072 | 전기차 충전상태 조회 서비스 제공 안 함 (협의 중) |
| 200 | 2032 | 기기 제어(조회) 실패, 게이트웨이 timeout |
| 200 | 2033 | 기기 제어(조회) 실패, 장치 timeout |
| 500 | 5001 | 서버 오류 |
| 503 | 5030 | 서비스 일시 중지 |
확인 필요
홈넷 연동규격서의
2102설명은 “미전원일 때 제어 요청” 인데, MAW는 이 코드를 받으면 미전입으로 보고 홈넷사에 자동 전입 이벤트를 보냄(2026-09-18 코드 확인). 규격 문구와 구현 해석이 어긋나므로 홈넷사와 확인 필요. “우리집제어를 켰더니 홈넷 쪽에 전입 이벤트가 들어왔다”는 문의가 이 동작임.
ID 규칙
- 단말기(게이트웨이) ID:
{단지ID}-{동}-{호}-00(예:C02895-0201-0208-00) - 디바이스 ID:
{단지ID}_{동}_{호}_{기기코드}(예:C02895_101_607_Sc00_power)
과거에는 단지 ID 자리에 w99999999 같은 고정값이 들어감. 홈넷사 패치로 단지 ID가 들어가게 바뀌었고, 적용 여부를 확인하는 절차가 기본매뉴얼/운영/단지 연동 점검임.
장애 판정
| 로그 문구 | 원인 | 조치 |
|---|---|---|
Connection timed out (응답 없음) | 단지 내 홈넷 서버 방화벽·포트 | 홈넷사에 방화벽 확인 요청 |
PKIX path building failed / SSL 핸드셰이크 실패 | 홈넷사가 우리 TLS 인증서 미등록 | 홈넷사에 인증서 등록 요청 |
SSL 인증서 확인 실패 / PKIX path validation failed → CertificateExpiredException: NotAfter ... (운영 중 단지, 해당 홈넷사 전체 동시 발생) | TLS 인증서 만료 (1년) | 홈넷사에 재발급 요청 받아 재발급 후 전달. 기본매뉴얼/운영/홈넷 서버 인증서 만료 |
ReadTimeoutException + resultCode: FAIL | 단지 로컬망 통신 불안정 | 홈넷사에 전달 |
result_code: 2000 + gateways: [] | 홈넷사가 빈 목록 응답 | 홈넷사에 전달 |
Could not find hnsver_sn | 연동 시험 시작 미실행 | 관리자 시스템에서 연동 시작 |
관련
기본매뉴얼/운영/홈넷 서버 연동 (인증서 발급) 기본매뉴얼/운영/단지 연동 점검 기본매뉴얼/운영/WAS 로그 확인 공개노트/기능/우리집제어 공개노트/기능/승강기 호출 공개노트/개발/모듈/MAW 앱 API 서버 공개노트/개발/모듈/PIW 연계 서버 기본매뉴얼/운영/홈넷 서버 인증서 만료 코맥스 코콤 현대HT