# v2: Money Forward API 계정 설정 및 OAuth 애플리케이션 등록

## Money Forward란?

Money Forward (マネーフォワード)는 일본에서 가장 인기 있는 자동 가계부 및 재무 관리 서비스입니다. 은행 계좌, 신용카드, 전자화폐, 포인트 등을 자동으로 연동하여 수입과 지출을 한눈에 관리할 수 있습니다.

### Money Forward의 장점

- **자동 연동**: 2,600개 이상의 금융기관 지원
- **자동 분류**: AI 기반 자동 카테고리 분류
- **다양한 리포트**: 월별, 카테고리별 분석
- **개발자 API**: 강력한 REST API 제공
- **안전한 인증**: OAuth 2.0 표준 사용

## Money Forward 서비스 종류

Money Forward는 여러 서비스를 제공합니다:

### 1. Money Forward ME (개인용)
- 개인 가계부 관리
- 무료 / 프리미엄 플랜

### 2. Money Forward Cloud (법인용)
- 회계, 급여, 경비 관리
- 비즈니스용
- **이번 프로젝트에서 사용** (Business API)

## Money Forward 계정 생성

### 1. 회원가입

1. https://moneyforward.com 방문
2. 우측 상단의 "新規登録" (신규 등록) 클릭
3. 이메일 주소 입력 또는 Google/Facebook 로그인
4. 비밀번호 설정
5. 이메일 인증 완료

### 2. 기본 정보 입력

- 생년월일
- 성별 (선택)
- 주거 형태 (선택)

초기 설정은 간단하게 진행하고, 나중에 변경 가능합니다.

### 3. 금융기관 연동 (선택)

실제 데이터를 사용하려면 은행, 카드사를 연동하지만, **API 테스트만 하려면 연동하지 않아도 됩니다**.

## Money Forward Developers 등록

API를 사용하기 위해서는 별도로 Developers 계정에 애플리케이션을 등록해야 합니다.

### 1. Developers 페이지 접속

1. https://app-portal.moneyforward.com/apps/ 방문
2. Money Forward 계정으로 로그인

### 2. 애플리케이션 생성

**중요**: 2025년 현재 Money Forward API는 **파트너 승인 필요**할 수 있습니다. 개인 개발자의 경우 테스트 목적으로 신청 가능합니다.

1. "アプリケーション作成" (애플리케이션 생성) 클릭
2. 애플리케이션 정보 입력:

```
애플리케이션 명: My Financial Analyzer
説明 (설명): TypeScript + Vertex AI를 사용한 재무 분석 도구
Redirect URI: http://localhost:3000/callback
```

**Redirect URI**는 OAuth 인증 후 돌아올 URL입니다. 로컬 개발 시에는 `localhost`를 사용합니다.

### 3. Client ID / Client Secret 발급

애플리케이션 생성 후 다음 정보를 받을 수 있습니다:

```
Client ID: abc123...
Client Secret: xyz789...
```

**중요**: Client Secret은 한 번만 표시되므로 안전한 곳에 복사해두세요!

## OAuth 2.0 이해하기

Money Forward API는 OAuth 2.0 **Authorization Code Grant** 방식을 사용합니다.

### OAuth 2.0 플로우 (Business API)

```
1. [사용자] → Authorization URL 접속
   https://api.biz.moneyforward.com/authorize

2. [사용자] → Money Forward 로그인 및 권한 승인

3. [Money Forward] → Redirect URI로 Authorization Code 전달
   http://localhost:3000/callback?code=ABC123&state=xxx

4. [앱] → Authorization Code로 Access Token 요청
   POST https://api.biz.moneyforward.com/token
   인증 방식: CLIENT_SECRET_BASIC (Authorization 헤더)

5. [Money Forward] → Access Token 발급
   { "access_token": "...", "refresh_token": "...", "expires_in": 3600 }

6. [앱] → Access Token으로 API 호출
   GET https://api.biz.moneyforward.com/v2/tenant
```

### 토큰 종류

#### 1. Authorization Code
```
code=ABC123...
```

- **유효 기간**: 10분
- **용도**: Access Token 발급 시 1회 사용
- **재사용**: 불가

#### 2. Access Token
```
access_token=eyJhbGc...
```

- **유효 기간**: 2시간
- **용도**: API 호출 시 인증
- **재사용**: 만료 전까지 계속 사용

#### 3. Refresh Token
```
refresh_token=abc123...
```

- **유효 기간**: 영구 (취소 전까지)
- **용도**: Access Token 갱신
- **재사용**: 계속 사용 가능

## API 스코프(권한) - Business API

OAuth 인증 시 요청할 수 있는 권한 (Business API는 다른 형식 사용):

```typescript
// Business API Scope 형식
const scope = 'mfc/admin/tenant.read';
```

**사용 가능한 Scope 예시**:
- `mfc/admin/tenant.read`: 사업체 정보 조회
- `mfc/invoice/data.read`: 청구서 데이터 조회
- `mfc/invoice/data.write`: 청구서 데이터 작성

**이번 프로젝트에서 사용**:
- `mfc/admin/tenant.read`: 사업체 기본 정보 조회

**주의**: Business API의 scope는 앱 등록 시 선택한 서비스에 따라 다릅니다.

## 환경 변수 설정

`.env.example` 파일 생성:

```bash
# Money Forward OAuth
MONEYFORWARD_CLIENT_ID=your_client_id_here
MONEYFORWARD_CLIENT_SECRET=your_client_secret_here
MONEYFORWARD_REDIRECT_URI=http://localhost:3000/callback

# Google Cloud Vertex AI (다음 단계에서 설정)
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_APPLICATION_CREDENTIALS=./service-account-key.json
```

실제 사용할 `.env` 파일:

```bash
MONEYFORWARD_CLIENT_ID=abc123xyz...
MONEYFORWARD_CLIENT_SECRET=secret456...
MONEYFORWARD_REDIRECT_URI=http://localhost:3000/callback

# Vertex AI는 v6에서 설정
GOOGLE_CLOUD_PROJECT=
GOOGLE_APPLICATION_CREDENTIALS=
```

## 보안 모범 사례

### 1. Client Secret 관리

**절대 하지 말아야 할 것**:
```typescript
// ❌ 나쁜 예: 코드에 하드코딩
const clientSecret = 'abc123xyz...';
```

**올바른 방법**:
```typescript
// ✅ 좋은 예: 환경 변수 사용
import 'dotenv/config';
const clientSecret = process.env.MONEYFORWARD_CLIENT_SECRET!;
```

### 2. .gitignore 설정

프로젝트 루트에 `.gitignore` 파일:

```
# 환경 변수
.env
.env.local
.env.*.local

# OAuth 토큰 저장 파일
tokens.json
.tokens/

# 의존성
node_modules/

# 빌드
dist/
build/

# IDE
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db
```

### 3. 토큰 저장

Access Token과 Refresh Token은 안전하게 저장해야 합니다:

```typescript
// 옵션 1: 파일 저장 (로컬 개발용)
const tokens = {
  access_token: '...',
  refresh_token: '...',
  expires_at: Date.now() + 7200000, // 2시간
};
fs.writeFileSync('.tokens/tokens.json', JSON.stringify(tokens));

// 옵션 2: 데이터베이스 (프로덕션)
await db.tokens.upsert({ userId, ...tokens });
```

### 4. HTTPS 사용 (프로덕션)

프로덕션 환경에서는 반드시 HTTPS를 사용해야 합니다:

```
❌ http://example.com/callback
✅ https://example.com/callback
```

로컬 개발 시에만 `http://localhost` 허용됩니다.

## API 엔드포인트 - Business API

Money Forward Business API의 주요 엔드포인트:

### Base URL
```
https://api.biz.moneyforward.com
```

### 주요 엔드포인트

**사업체 정보** (Tenant)
```
GET /v2/tenant
```

응답 예시:
```json
{
  "tenant_code": "1911-2783",
  "tenant_name": "株式会社PlanitAI"
}
```

**Expense API** (경비 관리)
```
Base URL: https://expense.moneyforward.com/api/external/v1
GET /api/external/v1/offices
GET /api/external/v1/offices/{office_id}/me/ex_transactions
```

**주의**:
- Business API는 서비스별로 Base URL이 다릅니다
- Expense, Payable, Invoice 등 각 서비스마다 별도 URL 사용
- 자세한 엔드포인트는 공식 문서 참조

## Rate Limiting

Money Forward API는 요청 횟수 제한이 있습니다:

- **시간당**: 1,000 요청
- **일일**: 10,000 요청

Response Header에서 확인 가능:
```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1638360000
```

## 체크리스트

v2를 완료하기 전에 다음을 확인하세요:

- [ ] Money Forward 개인 계정 생성 완료
- [ ] Money Forward Developers 애플리케이션 등록
- [ ] Client ID 발급 및 저장
- [ ] Client Secret 발급 및 안전하게 저장
- [ ] Redirect URI 설정 (`http://localhost:3000/callback`)
- [ ] OAuth 2.0 플로우 이해
- [ ] `.env.example` 파일 생성
- [ ] `.gitignore`에 `.env` 및 `tokens.json` 추가

## 참고 자료

- [Money Forward API 공식 문서](https://developers.moneyforward.com)
- [OAuth 2.0 RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)
- [OAuth 2.0 간단 설명](https://oauth.net/2/)

## 다음 단계

v3에서는 TypeScript 프로젝트를 초기화하고 개발 환경을 설정합니다.

준비할 것:
- Node.js 설치 (v18 이상)
- 텍스트 에디터 (VS Code 권장)
- 터미널 기본 지식

---

**작성일**: 2025-11-30
**상태**: ✅ 완료
**다음**: v3 - 개발 환경 설정