인터페이스 정의

배경

방문주차 기능(9월 말 배포 예정)을 위해 앱 ↔ MAW ↔ 홈넷사 구간의 인터페이스를 정의함. “LH 스마트홈 플랫폼-홈넷서버 간 연동규격(v.14)” 5.145.16(22p)에 규격은 있지만, 사내 인터페이스 정의서에는 외부 연동 내용이 빠져 있어 새로 채워 넣는 작업임.

DB 설계는 DB 담당자가 맡고, 그 결과가 나오면 화면과 개발을 붙임.

변경 내용

제공할 기능

• 방문차량 예약 조회 — 월간 허용시간, 월간 잔여시간, 예약 내역(방문 일련번호, 차량 정보, 시작·종료일자)
• 방문차량 예약 등록 — 방문자, 차량번호, 방문 시작일, 방문 종료일
• 방문차량 예약 수정 — 2026-09-16 기준 기능에서 제외됨
• 방문차량 예약 삭제
• 최근 방문 차량 조회 — 방문자, 차량번호, 시작·종료일, 즐겨찾기(핀) 여부

데이터 기준

1. 방문주차 내역은 세대 기준임.
2. 즐겨찾기와 방문자 이름은 사용자 기준임.
3. 로그 저장은 기존 소스 방식을 그대로 따름.

앱 → MAW

조회 시점에 우리 DB에 저장함(목록이 뜨는 시점에 insert).

아래 “수정” 설계는 2026-08 시점 것임. 수정 기능은 2026-09-16 기준 제외됨. 기록으로만 남김. “수정”은 홈넷사 쪽에 수정 API가 없어 두 갈래로 처리함.

1. 차량번호·날짜가 바뀌면 → 홈넷사에 삭제 후 등록하고 우리 DB에 저장.
2. 방문자 이름만 바뀌면 → 우리 DB의 이름만 수정.

POST https://{LH스마트홈:MAW}/maw/v1/household/modifyVisitVehicleReservation

요청	설명	포맷	크기	필수
traceId	요청ID (ms)	String	16	Y
sbdId	단지ID	String	8	Y
dongNo	동 번호	String	8	Y
hoNo	호 번호	String	8	Y
visitorName	방문자 이름	String		N
carNumber	차량 번호	String		N
visitStartDate	방문 시작일자	String		N
visitEndDate	방문 종료일자	String		N

응답은 traceId, resCd(처리결과 코드)임.

관리자 웹(LMC·SMC) API 규격 참고

• SMC 모든 API는 {resCd, resMsg, resData, totCnt} 형태로 응답함. 프론트는 resCd가 SQI0000이 아니면 resMsg를 그대로 팝업에 띄우므로 운영팀이 캡처해 오는 오류 문구가 곧 resMsg임. 코드 체계는 SQI0xxx(공통 CRUD), SQI1xxx(계정·인증), SQI2xxx(토큰), SQI3xxx(권한), SQI4000(업로드 차단), SQI9xxx(시스템 오류). 401 응답만 키 이름이 resCode로 나감. 전체 목록은 공개노트/개발/모듈/SMC API와 응답 코드, LMC는 공개노트/개발/모듈/LMC 결과 코드와 안내 문구
• LMC API 권한은 인터페이스 단위가 아니라 URL 접두(/api/v1/{업무ID}/**) + HTTP 메서드(C=POST, R=GET, U=PUT, D=DELETE) 단위로 DB(cmn.tb_rol_mnu_r × cmn.tb_mnu_m)에 정의됨. 같은 업무ID를 공유하는 API는 권한이 함께 열리고 닫힘. DB에서 권한을 바꿔도 재기동 전에는 반영 안 됨(기동 시 1회만 Security 매처로 등록)
• LMC → 홈넷/SMS/푸시는 직접 호출이 아니라 내부 API 서버(SMAH 내부 WAS) 경유. 세대 전입/전출 시 홈넷사 이벤트 코드는 H1(전입)/H2(전출)

최근 차량 조회는 별도 API 없이 기존 입출차 API를 재사용함. 입출차 조회를 100건 받아 carOwner가 '10'인 건만 남기고 차량번호로 grouping해, 차량번호당 가장 최근 1건만 보여줌. 이름이 아니라 차량번호만 unique로 봄. 즐겨찾기한 차량을 맨 위로 올림. 입출차 API 결과와 방문주차 목록을 같이 받아와야 함.

MAW → 홈넷사

POST https://{단지별홈넷사서버}/api/um/visitorCars

헤더: Authorization(사용자 인증 access_token), Accept·Content-Type은 application/json; charset=utf-8 고정.

요청	설명	포맷	크기	필수
trace_id	요청ID (ms)	String	16	Y
sbd_id	단지ID	String	8	Y
dong_no	동 번호	String	8	Y
ho_no	호 번호	String	8	Y
car_number	방문 차량번호	String		Y
visit_start_date	방문 시작일자 (yyyy.mm.dd)	String		Y
visit_end_date	방문 종료일자 (yyyy.mm.dd)	String		Y

응답은 trace_id, result_code임.

연동규격 V1.4(2026-08-14) 5.14~5.16에서 확인한 사항:

• 조회 GET /api/um/visitorCars: 요청 파라미터 없음. 응답에 monthly_allowed_time, monthly_remaining_time(분), visitCars[index, car_number, visit_start_date, visit_end_date]. 허용·잔여시간은 V1.4.0에서 추가됨.
• 삭제 DELETE /api/um/visitorCars: index(주차서버가 부여한 방문 일련번호) 하나만 보냄.
• 등록 응답에 index가 없음. 등록 뒤 조회를 해야 index를 얻음.
• 등록·삭제의 result_code 2000은 홈넷서버가 주차서버에 전달했다는 뜻임. 실제 반영 결과는 홈넷서버가 보내는 방문예약삭제완료(C5) 이벤트를 받은 뒤 조회로 확인함.
• 중복 기준은 동일 차량번호 + 동일 방문 시작일자(2111). 삭제 대상 없음은 2112.
• 입출차 조회(5.8 GET /api/um/vehicles)에 car_owner(세대 00 / 방문 10) 필터가 있음. 이벤트(7.4)는 방문입차 C3, 방문출차 C4, 방문예약삭제완료 C5.

운영 규칙(2026-09-16 확인): 잔여시간을 초과하는 예약도 등록됨. 초과분은 단지에서 자체 계산해 별도 청구하고 앱에는 ‘초과이용시간’으로 표시함. 방문차량 입출차 push는 하지 않음. 화면의 방문자 입력은 최대 15자임.

테스트 케이스는 프로젝트/방문주차/통합시험 시나리오에 있음.

앱↔MAW는 camelCase(sbdId), MAW↔홈넷사는 snake_case(sbd_id)를 씀. 구간마다 표기가 다르니 매핑할 때 주의.

2026-09-17 기준 방문차량 조회·삭제 API 파라미터와 모바일 화면 설계 모두 확정. 기능은 2026-10 배포 후 동작 가능한 단지부터 순차 오픈 예정(기본매뉴얼/입주민/입출차와 주차등록이 안 돼요).

MAW에 실제로 구현된 값 (2026-09-18 코드 확인)

위 설계 대비 서버에 무엇이 들어갔는지 코드로 확인한 결과임. 정의서를 채울 때 이 값을 기준으로 할 것.

구간	보내는 파라미터
등록 POST /api/um/visitorCars	trace_id, sbd_id, dong_no, ho_no, car_number, visit_start_date, visit_end_date (날짜 yyyy.MM.dd)
조회 GET /api/um/visitorCars	trace_id, sbd_id, dong_no, ho_no — 네 개 고정임. 기간·차량번호 필터 없음
삭제 DELETE /api/um/visitorCars	trace_id, sbd_id, dong_no, ho_no, index
입출차 조회 GET /api/um/vehicles	trace_id, sbd_id, dong_no, ho_no — 네 개 고정임. 기간·차량번호·건수 필터와 페이징 없음. car_owner 필터도 보내지 않고 응답을 홈넷 원본 그대로 내려줌

• 삭제의 index는 MAW DB의 주차서버 예약번호(prk_srvr_rsvt_no)임. 앱은 MAW 예약 일련번호(vstVhcRsvtSn)를 보내고 MAW가 이 값으로 바꿔 홈넷에 전달함. 두 번호는 서로 다름
• 홈넷이 삭제 응답으로 5013(해당 데이터 없음)을 주면 오류로 보지 않고 DB만 del_yn='Y' 처리하고 성공으로 끝냄. 홈넷에서 이미 지워진 예약을 앱에서 지울 때의 정상 동작임
• 조회가 동기화를 겸함. 홈넷 목록을 기준으로 smah.tb_vst_vhc_rsvt_m을 덮어쓰고, 홈넷에 없는 DB 행은 del_yn='Y'로 지움. DB만 고쳐도 다음 조회에서 되돌아감
• 홈넷이 예약번호를 재사용하는 경우를 가정해 삭제 처리된 같은 번호의 행을 되살림(유니크 제약 회피)
• 방문자명은 홈넷에 보내지 않고 MAW DB에만 저장함. 예약번호가 바뀌면 방문자명이 끊길 수 있음
• 등록·취소는 1초 대기 후 홈넷 재조회로 반영을 확인함. 반영이 안 보이면 SQI0001
• 등록 검증: 차량번호 필수, 차량번호·방문자명 20자 초과 불가(화면 입력 제한 15자와 다름), 날짜는 yyyy-MM-dd만 허용
• 월 허용·잔여시간은 홈넷 값 그대로이고, 비면 문자열 "0"으로 채움
• 최근 방문차량은 홈넷 입출차 조회를 다시 호출해 만듦 → 홈넷이 죽으면 최근 방문차량 목록 자체가 실패함

서버 쪽 전체 규격은 공개노트/개발/모듈/MAW 세대·헬스케어 API.

타임아웃이 구간마다 다름

구간	응답 타임아웃
MAW → 홈넷서버	3초
MAW → 내부 API WAS (홈넷 토큰)	3초
MAW → 내부 API WAS (SMS·이벤트)	30초
MAW → 이음(에너지)	20초
MAW → 승강기 플랫폼	10초
LMC → 내부 API WAS	5초 / 20초 / 없음으로 제각각. 전출·반려 푸시와 홈넷서버 게이트웨이 조회에는 타임아웃이 아예 없음

인터페이스 정의서에 타임아웃 열이 있다면 이 값을 넣을 것. LMC 쪽 상세는 공개노트/개발/모듈/LMC 기능 상세.

확인 방법

1. 연동규격 v.14 5.14~5.16과 위 파라미터 이름·크기가 일치하는지 대조할 것.
2. Postman으로 MAW 등록 API를 호출하고 홈넷사 쪽에 예약이 실제로 들어갔는지 확인할 것.
3. 삭제 후 조회하면 목록에서 빠지고 잔여시간이 복원되는지 확인할 것.

관련

• 공개노트/기능/홈넷 서버 연동
• 기본매뉴얼/운영/grafana로 로그 보기