# v4: Freee API 연동 및 인증 설정

Google Sheets와의 연동을 마쳤으니, 이제 데이터의 원천인 **Freee** 회계 서비스와 연동할 차례입니다. 이번 포스트에서는 Freee API에 접근하기 위한 인증 설정을 진행하고, 간단한 API 호출을 통해 연결을 테스트합니다.

Freee API는 OAuth 2.0 인증 방식을 사용합니다. 이번 단계에서는 사용자께서 이미 발급받았다고 하신 Access Token을 직접 사용하여 API를 호출하는 간단한 방법으로 진행하겠습니다.

## 1단계: Freee 앱 및 API 자격 증명 확인

Freee API를 사용하기 위해서는 먼저 Freee 개발자 포털에서 애플리케이션을 등록해야 합니다.

1.  **Freee 개발자 포털 접속**: [Freee Developers](https://developer.freee.co.jp/)에 접속하여 로그인합니다.
2.  **앱 생성**: `앱 관리` 섹션에서 새로운 앱을 생성합니다. 필요한 정보(앱 이름, 콜백 URL 등)를 입력하고 앱을 등록합니다.
3.  **자격 증명 확인**: 앱 관리 페이지에서 **Client ID**와 **Client Secret**을 확인할 수 있습니다. 이 정보들은 나중에 전체 OAuth 2.0 인증 흐름을 구현할 때 필요합니다.

## 2단계: 환경 변수 업데이트

프로젝트의 `.env` 파일에 이미 Freee 관련 환경 변수들의 플레이스홀더를 만들어 두었습니다. 이 부분에 자신의 Freee 앱 **Client ID**, **Client Secret**, 그리고 미리 발급받은 **Access Token**을 채워 넣어주세요.

```ini
# .env 파일 예시
GOOGLE_DOCUMENT_ID=...
FREEE_CLIENT_ID="YOUR_FREEE_CLIENT_ID"
FREEE_CLIENT_SECRET="YOUR_FREEE_CLIENT_SECRET"
FREEE_ACCESS_TOKEN="YOUR_FREEE_ACCESS_TOKEN"
GOOGLE_SERVICE_ACCOUNT_KEY_PATH=...
```

**중요**: Access Token은 만료 시간이 있으므로, 실제 서비스에서는 주기적으로 토큰을 갱신하는 로직(Refresh Token)이 필요합니다. 이번 시리즈에서는 우선 수동으로 발급받은 토큰을 사용합니다.

## 3단계: API 요청을 위한 `axios` 설치

HTTP 클라이언트 라이브러리인 `axios`를 설치하여 Freee API에 요청을 보냅니다.

```bash
npm install axios
```

## 4단계: Freee API 클라이언트 및 테스트 함수 작성

API 요청을 보낼 `src/freeeClient.ts` 파일을 생성하고, 인증 헤더를 포함하여 API를 호출하는 기본 클라이언트와 테스트 함수를 작성합니다.

`src/freeeClient.ts` 파일을 생성하고 다음 내용을 추가합니다.

```typescript
import axios from 'axios';
import * as dotenv from 'dotenv';

dotenv.config();

const FREEE_ACCESS_TOKEN = process.env.FREEE_ACCESS_TOKEN;
const FREEE_API_BASE_URL = 'https://api.freee.co.jp';

if (!FREEE_ACCESS_TOKEN) {
  throw new Error('환경 변수 FREEE_ACCESS_TOKEN이 설정되지 않았습니다.');
}

const freeeApiClient = axios.create({
  baseURL: FREEE_API_BASE_URL,
  headers: {
    'Authorization': `Bearer ${FREEE_ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
});

// Freee API 연결 테스트를 위한 함수
export const testFreeeConnection = async () => {
  try {
    // 사용자 정보를 가져오는 엔드포인트 호출
    const response = await freeeApiClient.get('/api/1/users/me');
    console.log('Freee API 연결 성공! 사용자 정보:', response.data.user);
    return response.data;
  } catch (error: any) {
    if (axios.isAxiosError(error)) {
      console.error('Freee API 연결 실패:', error.response?.data || error.message);
    } else {
      console.error('Freee API 연결 중 알 수 없는 오류 발생:', error.message);
    }
    throw error;
  }
};
```

## 5단계: `index.ts`에서 Freee API 연결 테스트

`src/index.ts` 파일을 수정하여, `testFreeeConnection` 함수를 호출하고 Freee API와의 연결이 성공적인지 확인합니다.

```typescript
import { readTransactionData } from './googleSheetClient';
import { testFreeeConnection } from './freeeClient'; // 새로 추가

const main = async () => {
  console.log('프로젝트 시작...');

  // Google Sheets 데이터 읽기 (주석 처리)
  // try {
  //   const transactions = await readTransactionData('Sheet1');
  //   console.log('읽어온 거래 내역:', transactions);
  // } catch (error) {
  //   console.error('거래 내역 읽기 중 오류 발생:', error);
  // }

  // Freee API 연결 테스트
  try {
    await testFreeeConnection();
  } catch (error) {
    // 에러는 testFreeeConnection 함수 내부에서 이미 처리됨
  }

  console.log('프로젝트 종료.');
};

main().catch(error => {
  console.error('전체 실행 중 오류 발생:', error);
  process.exit(1);
});
```

이제 모든 준비가 끝났습니다. `.env` 파일에 Freee Access Token을 정확히 입력했다면, 다음 명령어로 Freee API 연결을 테스트할 수 있습니다.

```bash
npx ts-node src/index.ts
```

성공적으로 연결되면 콘솔에 "Freee API 연결 성공!" 메시지와 함께 사용자 정보가 출력될 것입니다.

---

다음 **v5** 포스트에서는 Freee API를 사용하여 실제 "거래 내역(deals)" 데이터를 가져오는 방법에 대해 자세히 알아보겠습니다.