# 필요한 값 정리 (하나캐피탈 차량금융 연동)

> 출처: `하나캐피탈_차량금융상품_연동가이드.pdf` 3장.
> 분류 — **동적**(요청마다 값 지정) / **2단계**(렌탈료계산 시 추가) / **고정**(기본값, 상품정책 따라 조정)

---

## 0. 사전 발급/협의 값 (연동 개시 전 확보)

| 값 | 설명 | 발급/책임 | 확보 여부 |
|---|---|---|---|
| `ccoCustNo` | 제휴사고객번호 (예: 6502189659) | **하나캐피탈 발급** | ☐ |
| `ccoCustSno` | 제휴사고객일련번호 (예: 0) | **하나캐피탈 발급** | ☐ |
| 릴레이 엔드포인트/포트 | `http://localhost:11080/inbound` — 하나캐피탈이 설치·운영 | 하나캐피탈 | ☐ |
| 방화벽 IP 화이트리스트 | 릴레이 접근 IP 등록 | 양사 협의 | ☐ |
| `serviceID` | `UCARI00013` (잔가/렌탈료·공통조회) | 고정 | ✅ |
| `version` | `1.0` | 고정 | ✅ |

---

## 1. 차량코드 매칭값 (동적) — GNA가 카탈로그를 매칭·저장

하나캐피탈이 TSV 카탈로그(브랜드→시리즈→모델→라인업→트림 5계층 + 각 IIDX)를 제공하면,
GNA는 자사 차량트리에 매칭해 **트림마다 하나 차량코드**를 저장한다. 조회 시 이 매칭값을 사용.

| 요청 파라미터 | GNA 저장 컬럼(nTreeCarTrim) | 하나 코드 | 필수 |
|---|---|---|---|
| `braNo`   | `apiHanaBrand`  | IIDX_BRAND (브랜드) | ✅ |
| `mdlNo`   | `apiHanaModel`  | IIDX_MODEL (모델) | ✅ |
| `linupNo` | `apiHanaLineup` | IIDX_LINEUP (라인업) | ✅ |
| `trimNo`  | `apiHanaTrim`   | IIDX_TRIM (트림) | ✅ |
| (참조용)  | `apiHanaSeries` | IIDX_SERIES (시리즈) | 참조 |

> ⚠️ **주기적 갱신 필수**: 신차/신규 트림 출시, 연식 변경(2025년형→2026년형), 트림/옵션 개편,
> 가격/사양 변경, 단종 시 하나 차량코드가 변경·추가·폐지된다. 미갱신 시 신차/신규 트림은
> **조회 불가**, 폐지·변경 코드로는 **오류 또는 잘못된 잔가/렌탈료** 산출. (권장 갱신: 월 1회 + 대규모 개편 시 수시)

---

## 2. 계약·차량 입력값 (동적) — 견적 요청마다 지정

| 파라미터 | 예시 | 설명 | 필수 |
|---|---|---|---|
| `puryCarAmt`  | 34000000 | 차량금액 + 옵션금액 | ✅ |
| `cntrPrid`    | 36 | 계약기간(개월) — 12/24/36/48/60 | ✅ |
| `prrpAmt`     | 0 | 선납금 | ○ |
| `drvrAgeDvCd` | 04 | 운전자연령구분 — 02:만21세↑, 04:만26세↑ | ○ |

---

## 3. 잔가율 관련 (2단계) — 1단계 응답으로 계산되어 2단계 요청에 투입

> 오케스트레이터 API를 쓰면 **자동 처리**되므로 직접 넘길 필요 없음. (릴레이 직접 호출 시에만 수동 세팅)

| 파라미터 | 설명 | 산출 |
|---|---|---|
| `rcstPer`    | 잔가율 — 1단계(dvCd=1) 응답값 입력 | `mxRevalRtoCtnt["<계약기간>"]["<구간>"]` |
| `aplRcstAmt` | 적용잔가금액 | `차량금액 × 잔가율%` (예: 34,000,000 × 61.5% = 20,910,000) |

---

## 4. 상품·보장·부대 고정값 (고정 기본값) — `Message.info`

> `api/config.py`의 `FIXED_INFO`에 세팅됨. 상품정책 변경 시 갱신. 요청 `options`로 개별 오버라이드 가능.

| 파라미터 | 기본값 | 설명(코드 의미) |
|---|---|---|
| `reprPrdtCd`     | 1 | 정비상품 — 01:Self 02:Standard 03:Premium 04:Semi 05:Special 06:Special(계열사) 07:EV Special |
| `agrTrvgDstnCd`  | 20000 | 약정주행거리(km) — 15000/20000/25000/30000/40000/50000 |
| `custDvCd`       | 1 | 고객구분 — 1:개인 2:개인사업자 3:법인 |
| `dlvyDvCd`       | 10 | 출고구분 — 10:대리점 20:특판출고 (10 고정) |
| `dlvyArDvCd`     | 004 | 출고지역 — 003창원 004부산 007광주 015울산 022아산 023서산 024소하리 025화성 026덕평 027송도 029평택 035칠곡 |
| `cndgmtArDvCd`   | 004 | 탁송지역 — 001서울 004부산 005대구 006대전 007광주 009인천 011경기 012충남 013충북 015울산 016경남 017경북 018전남 019전북 … |
| `cndgmtMthCd`    | 02 | 탁송방법 — 01:외주탁송 02:제조사탁송 03:1차제조사+2차외주탁송 |
| `bkbxNo`         | 01 | 블랙박스 — 01:해당없음 08:아이나비(A300) 09:지넷(G프로200) |
| `snrWndtngNo`    | 01 | 측후면썬팅 — 01:해당없음 02:일반(쿠폰) 03:3M 04:루마 |
| `cwsWndtngNo`    | 01 | 전면썬팅 — 01:해당없음 05:포함 |
| `naviNo`         | 01 | NAVI — 01:해당없음 05:포함 |
| `sustRpraDvCd`   | 04 | 대물배상 — 04:1억 05:2억 06:3억 |
| `ownBodyAcdDvCd` | 23 | 자기신체사고 — 21:3천만/15백만 22:5천만/15백만 23:1억/15백만 |
| `apemSconJnYn`   | N | 임직원특약 가입여부 — Y/N |
| `agCmrt` / `agCmfeAmt` | 1 / 352600 | AG수수료율 / AG수수료금액 |
| `grtAmt`         | 3526000 | 보증금액 |
| `cmCmrt` / `cmCmfeAmt` | 3 / 1057800 | CM수수료율 / CM수수료금액 |
| `mcarBnamtDvCd`  | 2 | 자차부담금 — 01:50만 06:5만~50만 02:30만 03:20만 04:10만 |
| `tdpDvCd`        | 1 | 주행거리프로모션 — 1:해당없음 2:추가수수료 전체제외 3:추가수수료 0.5% 고정 |
| `iflwKndCd`      | (빈값) | 유입종류코드 |

---

## 5. 인증·공통 헤더 (요청마다 자동 세팅) — `Header` / `Message.reqInfo`

| 파라미터 | 값 | 설명 |
|---|---|---|
| `serviceID` | UCARI00013 | 서비스 ID |
| `version`   | 1.0 | 버전 |
| `ccoCustNo` | 6502189659 | 제휴사고객번호 |
| `ccoCustSno`| 0 | 제휴사고객일련번호 |
| `prdtCd`    | 0 | 사용금지(0) |
| `dvCd`      | 1 / 2 | 처리구분 — 1:잔가조회 2:렌탈료계산 |

---

## 6. 응답으로 받는 값 (GNA 견적 최종 산출)

| GNA 필드 | 출처 | 산출 |
|---|---|---|
| `priceResidualRto` | 1단계 | 잔가율(%) — 예 61.5 |
| `priceResidual`    | 1단계 | 적용잔가금액 = 차량금액 × 잔가율% — 예 20,910,000 |
| `priceMonth`       | 2단계 | 월 렌탈료 = `rentalFeeInfo.rlpnRtfe` — 예 1,174,910 |

> 렌탈료 상세: `carRtfe`(차량 렌탈료), `addRtfe`(부가 렌탈료), `spprcAmt`(공급가액),
> `srtxAmt`(부가세 10%), `acqCamtAmt`(취득원가금액), `irrPer`(IRR), `jnIscoNm`(보험사) 등.

---

## 체크리스트 (연동 운영)

- ☐ API 서버(로컬 릴레이 `:11080`) 설치 — **하나캐피탈측 담당**
- ☐ 제휴사고객번호(`ccoCustNo`/`ccoCustSno`) 발급 및 접속 승인
- ☐ 엔드포인트/포트(11080)/방화벽(IP 화이트리스트) 협의
- ☐ 차량 카탈로그(TSV) 정기 제공 주기·경로 확정 (권장 월 1회 + 수시)
- ☐ 신차/개편 발생 시 카탈로그 우선 전달 프로세스
- ☐ 코드표(지역·정비·보장 등) 및 응답 규격서·에러코드 최신본 공유
- ☐ 테스트 케이스(대표 차종별 잔가·렌탈료) 상호 검증