modooapi-workers-fbs

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

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

- Base URL: https://fbs.modooapi.com
- 인증: modooapi.com/console 에서 발급한 중앙 액세스 토큰을 모든 /api/* 요청에 `Authorization: Bearer <token>` 헤더로 전송한다.
- 공통 응답: 성공 { "success": true, "data": ... }, 실패 { "success": false, "error": "<메시지>" }.
- 개요: 모계좌(출금, 플랫폼 펀딩계좌)에서 지정 입금계좌로 실시간 이체한다(Coocon 펌뱅킹 WAPI_1100). 운영 가동 중(Coocon 운영 오픈, relay 고정 IP 209.71.88.78 등록 완료). 모계좌는 콘솔 설정값(호출자 비지정 — 보안). 호출자는 입금 대상·금액·적요만 지정한다. ⚠️ 운영 입금이체는 실제 자금 이동 + 수수료 발생. 결과 불확실(001/TIM/9979/9980/9999/타임아웃) 시 재시도 금지, 처리결과조회(WAPI_6113) 필수.

## 연동 가이드
## 입금이체 흐름
1) POST /api/transfer {inBankCode, inAccountNo, inName, amount, ref?} — 모계좌에서 입금계좌로 이체. 모계좌는 콘솔 설정값.
2) 응답이 success=true & resultCd=000 → 이체 완료. balanceAfter=거래 후 모계좌 잔액.
3) 응답이 needsReconciliation=true(001/TIM/9979/9980/9999/타임아웃) → 자금 이동 여부 불확실. **재시도 금지.** POST /api/transfer/result 로 거래성립 여부를 확인한다.
4) /api/transfer/result 응답: success=true → 이체 성립 확정(RSPS_CD 000). needsReconciliation=true(RSPS_CD 001/TIM 또는 조회 응답 미확정) → 거래 진행중, 3~5분 후 비-001 응답까지 재조회. success=false & 비-진행중 → 이체 미성립(거절).

## 멱등(중복이체 방지) — ref 필수
- ref(주문번호 등 거래별 고유 멱등키)는 필수. 같은 ref 의 진행중/완료/불확실 거래가 있으면 재이체하지 않고 기존 상태를 반환한다(원자적 claim → 동시 요청·재시도에도 1회만 이체).
- 확정 실패(failed)한 ref 는 같은 ref 로 재시도 가능. 같은 ref 를 다른 금액으로 재사용하면 409 거부.

## 필드
- inBankCode: 입금 은행코드 3자리(GET /api/banks). inAccountNo: 입금 계좌(숫자, ≤16). inName: 입금계좌 적요(≤10자).
- amount: 이체금액(원, 1 이상 정수, ≤13자리). outName: 모계좌 적요(선택, 기본=콘솔값).
- 모계좌(출금 은행·계좌)와 취급기관코드는 콘솔 설정 — 호출자가 지정하지 않는다(보안).

## 운영 메모
- ⚠️ 운영 입금이체는 실제 자금 이동 + 수수료 발생. 1회 이체 상한(콘솔 max_amount)으로 안전장치.
- Coocon 호출은 relay 고정 IP(209.71.88.78) 경유 — 화이트리스트 등록 IP(미등록 시 9989).
- 계좌번호는 마스킹 저장(끝4자리). 시각 KST(+09:00). 설정 미비 시 503.
- 연동 키 관리: https://fbs.modooapi.com/console (CONSOLE_SECRET 관리자 전용).

## 엔드포인트

### POST https://fbs.modooapi.com/api/transfer  [🔒 토큰]
입금이체(WAPI_1100) — 모계좌→입금계좌 실시간 이체. inBankCode/inAccountNo/inName/amount/ref 필수. ref(멱등키)로 동시·재시도 중복이체를 차단(같은 ref 재호출은 재이체 안 함). 응답 needsReconciliation=true 면 처리결과조회로 확인. amount 는 정수(원)만(소수점·콤마 불가).
요청:
{ "inBankCode": "020", "inAccountNo": "1002068124680", "inName": "홍길동", "amount": "1000", "outName": "모두", "ref": "order-123" }
응답:
{ "success": true, "data": {
  "trscSeqNo": "0123456", "success": true, "resultCd": "000",
  "resultMsg": "정상처리", "balanceAfter": "...", "needsReconciliation": false } }

### GET https://fbs.modooapi.com/api/balance  [🔒 토큰]
모계좌 잔액조회(WAPI_2100) — 설정된 모계좌(출금)의 잔액·미결제 타점권을 조회한다.
응답:
{ "success": true, "data": {
  "success": true, "resultCd": "000", "balance": "246992092094", "unsettled": "244119720094" } }

### POST https://fbs.modooapi.com/api/transfer/result  [🔒 토큰]
이체처리 결과조회(WAPI_6113) — 입금이체의 거래성립 여부를 재확인한다. 거래성립은 응답코드 RSPS_CD 로 판정 — success=true면 이체 성립 확정, needsReconciliation=true(RSPS_CD 001/TIM 또는 조회 응답 자체가 미확정)면 거래 진행중(3~5분 후 비-001 응답까지 재조회). originalSeqNo(이체 응답의 trscSeqNo) + trscDt(원거래 거래일자 yyyymmdd) 필수.
요청:
{ "originalSeqNo": "0104202", "trscDt": "20260617" }
응답:
{ "success": true, "data": {
  "success": true, "resultCd": "000", "responseCode": "000", "origResponseCode": "000", "amount": "1000", "needsReconciliation": false } }

### GET https://fbs.modooapi.com/api/banks  [🔒 토큰]
금융기관 코드 목록

### GET https://fbs.modooapi.com/console  [🔑 관리자]
관리자 콘솔 — 설정·잔액조회·이체 테스트·거래내역·처리결과조회 (CONSOLE_SECRET)

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