스마트홈 위키

홈넷 서버 연동 (인증서 발급)

Properties2
tags운영, 홈넷, 인증서, 연동
aliases인증서 발급, TLS 인증서, 홈넷 연동 등록, 연동 시험 시작, 클라이언트 시크릿 전달, 홈넷 서버 등록

7 min read

목적

신규 단지의 홈넷 서버를 등록하고 TLS 인증서를 발급해 홈넷사에 전달함. 이 작업이 끝나야 우리집제어·승강기 호출이 동작함.

사전 준비

  • 홈넷사에서 온 연동 요청 메일
  • COTIS 기준 단지명, 세대수, 주소
  • 준공단지 현황의 Q+라운지 시작일

절차

  1. 홈넷사 연동 요청 메일을 확인할 것.
  2. 단지 관리 > 건축 정보로 들어갈 것.
  3. COTIS 단지명으로 단지를 검색해 지역 본부를 확인할 것.
  4. 세대수와 주소로 그 단지가 맞는지 대조할 것.
  5. 수정을 눌러 아래를 채울 것.
    • 스마트홈 대상 → 대상
    • 단지명 정보(스마트홈) → COTIS와 똑같이
    • 점검 시작 → 준공단지 현황의 Q+라운지 시작일
    • 서비스 시작 → 오늘 날짜
    • 서비스 옵션 → 보통 승강기 호출, 우리집제어, 노이즈가드
  6. 단지 관리 > 홈넷 서버 관리에서 등록할 것.
  7. 연동 시험 시작 → 홈넷 서버 연동 시작을 누를 것. 홈넷 서버 관리 목록 우측 상단에 버튼이 있음. 시험 연동 단계면 연동 시험 시작, 본 연동이면 홈넷 서버 연동 시작임. 누른 뒤 연동 시작 일자가 갱신되고 홈넷 연동 상태가 “연동이상”에서 정상으로 바뀌는지 볼 것. 이 단계를 빠뜨리면 홈넷사가 access token을 발급받을 때(POST /api/ccg/authcheck) Could not find hnsver_sn(...) on del_yn(N) and hnet_lnkg_ss_cd(ON) 오류가 나고 홈넷사에는 500 + result_code 5001로 떨어짐. 2026-03-05 해남해리2(C02921-1), 2026-07-21에 이 이유로 났음.
  8. TLS 인증서를 다운로드할 것.
  9. Client ID, Client Secret, sbd ID, TLS 인증서를 홈넷사에 메일로 전달할 것. Client Secret은 메일로만 전달하고 위키·메모에는 남기지 않음.
  10. 홈넷사에서 연동 정보 조회 요청 메일이 오면 세대 단말기 정보 조회를 시험할 것.

확인

  • 홈넷 서버 관리에 서버가 등록돼 있고 연동 상태가 시작됨
  • 홈넷사가 access token 발급에 성공함
  • 세대 단말기 정보 조회가 건수 있게 돌아옴
  • 관리자 시스템의 홈넷 서버 상태가 정상이고 최종 내역 생성 일시가 최근임

조회가 안 될 때는 로그의 오류 문구로 원인을 가름.

  • 응답이 아예 오지 않고 Connection timed out → 단지 내 홈넷 서버 방화벽 설정. 홈넷사에 방화벽 확인과 포트 개방을 요청함
  • 응답은 오는데 PKIX path building failed / SSL 핸드셰이크 실패 → 홈넷사가 우리 TLS 인증서를 등록하지 않은 것임
  • SSL 인증서 확인 실패 / CertificateExpiredException이 운영 중 단지에서 나오면 인증서 만료임. 유효기간은 1년이라 매년 같은 시기에 재발생함. 확인·재발급 절차는 기본매뉴얼/운영/홈넷 서버 인증서 만료

홈넷사가 “토큰 발급이 안 된다”고 할 때

홈넷사가 500 오류를 보고하면 아래 세 가지를 요청해 우리 로그와 대조할 것.

  1. 요청 전문: URL·Method, Headers, Body (grantType, traceId, sbdId)
  2. 응답 로그: 500과 함께 돌아온 메시지 전체
  3. 발생 시각

우리 쪽 WAS 로그에서 Could not find hnsver_sn 또는 hnet_lnkg_ss_cd를 찾을 것. 나오면 위 7번(연동 시작 미실행)임. 관리자 시스템에서 연동을 시작한 뒤 홈넷사에 재시도를 요청하고, 로그에서 authcheck가 200으로 바뀌는지, 최종 홈넷 서버 상태가 정상이 되는지 볼 것.

인증서 재발급 (만료된 경우)

재발급은 홈넷사의 요청이 있어야 함. 우리가 먼저 발견했으면 홈넷사에 재발급을 요청해 달라고 연락할 것.

  1. 홈넷사의 재발급 요청을 받을 것.
  2. 갱신 날짜를 확인할 것. 인증서 발급 이력 테이블(tb_tlscrtf_pblc_l)을 볼 것.
  3. 인증서를 재발급할 것.
  4. 해당 홈넷사에 새 TLS 인증서를 전달할 것. 만료 여부를 서버에서 직접 확인하는 명령과 점검 스크립트는 기본매뉴얼/운영/홈넷 서버 인증서 만료에 있음.

관련

공개노트/기능/홈넷 서버 연동 기본매뉴얼/운영/홈넷 서버 인증서 만료 기본매뉴얼/운영/서비스 오픈 기본매뉴얼/운영/단지 연동 점검 기본매뉴얼/운영/WAS 로그 확인 기본매뉴얼/관리사무소/새로 연동한 단지의 단말기 조회가 안 돼요 기본매뉴얼/관리사무소/세대 단말기 조회가 안 돼요

백링크