# modooapi-workers-realname 연동 가이드 (AI 에이전트용)

너는 modooapi 의 "modooapi-workers-realname" API 를 호출하는 통합 에이전트다. 아래 명세대로 정확히 요청을 구성하라.

- Base URL: https://realname.modooapi.com
- 인증: modooapi.com/console 에서 발급한 중앙 액세스 토큰을 모든 /api/* 요청에 `Authorization: Bearer <token>` 헤더로 전송한다.
- 공통 응답: 성공 { "success": true, "data": ... }, 실패 { "success": false, "error": "<메시지>" }.
- 개요: 은행코드+계좌번호+idNo(사업자번호 10자리 또는 주민 생년월일 YYMMDD 6자리)로 예금주 실명을 확인한다 — 입력 idNo 가 예금주 정보와 일치할 때만 예금주명(accountName)을 반환한다. Coocon KIB(ACCTNM_RCMS_WAPI) 연동, 운영 가동 중. 인증키는 콘솔(admin) 관리, relay 고정 IP(209.71.88.78) 경유(Coocon 화이트IP 등록 완료). 시각 KST(+09:00). ※ idNo 없이 예금주명만 받는 성명조회는 별도 인증키가 필요하다(현재 운영 키는 실명조회 전용).

## 연동 가이드
1) 실명조회: 은행(bankCode)+계좌(accountNo)+idNo(사업자10 또는 주민생년월일6) → idNo 일치 시 matched=true + accountName(예금주명). 불일치/오류 시 matched=false + resultCd/resultMsg(예: 주민번호 오류). ※ 현재 운영 인증키는 실명조회 전용 — idNo 생략(성명조회) 시 정상 동작하지 않을 수 있다.
2) 은행코드는 GET /api/banks 로 확인. (실명조회용) 개인사업자 계좌는 은행별로 사업자번호 조회 불가(X)가 많다 → bizQuery 가 O 가 아니면 주민 생년월일(6자리) 사용 권장.
3) AES키가 설정돼 있으면 요청/응답을 AES256 암호화(_aes)로, 없으면 평문(_wapi)로 호출한다. 응답/로그에 예금주명·전체계좌·주민번호는 저장하지 않는다(감사 로그는 끝4자리·결과코드만).
4) 미설정(인증키 없음) 시 503. relay IP 미등록 시 Coocon 9989(허용된 아이피 아님).

## 엔드포인트

### POST https://realname.modooapi.com/api/realname  [🔒 토큰]
예금주 실명조회 — idNo 일치 시 예금주명 반환 — bankCode+accountNo+idNo(사업자번호 10자리 또는 주민 생년월일 YYMMDD 6자리)로 예금주 실명조회. idNo 가 예금주 정보와 일치할 때만 matched=true + accountName(예금주명). 운영 가동 중. (idNo 없이 예금주명만 받는 성명조회는 별도 인증키 필요.)
요청:
{ "bankCode": "081", "accountNo": "12345678901234", "idNo": "800101" }
응답:
{ "success": true, "data": { "matched": true, "accountName": "홍길동",
  "bankCode": "081", "bankName": "하나은행", "resultCd": "000" } }
// 불일치/오류: { "success": true, "data": { "matched": false, "accountName": null, "resultCd": "...", "resultMsg": "..." } }

### GET https://realname.modooapi.com/api/banks  [🔒 토큰]
금융기관 코드 목록(+ 개인사업자 사업자번호 조회 가능여부)
응답:
{ "success": true, "data": [ { "code": "088", "name": "신한은행", "bizQuery": "조건부" } ] }

### GET https://realname.modooapi.com/console  [🔑 관리자]
실명조회 설정 콘솔(인증키·AES키 관리, admin)

## 규칙
- 금액은 정수(원). 날짜/시각은 명세 포맷을 따른다.
- 토큰이 없거나 무효면 401. 권한/IP 오류는 403. 입력 오류는 400.
- 실패 시 error 메시지와 (있으면) resCode 를 사용자에게 그대로 전달하라.