# 会費ペイ (Kaihipay) API 사용법

## 개요

会費ペイ (kaihipay.jp)는 일본의 회비 자동 결제 서비스입니다. 학원, 피트니스 클럽, 협회 등에서 월회비나 수강료를 자동으로 징수하는 시스템입니다.

## API 제공 여부

会費ペイ는 API 연동 기능을 제공하고 있습니다.

- **API Reference**: https://api.kaihipay.jp/api/reference/
- **API 소개 블로그**: https://blog.kaihipay.jp/introduction-api/

## API 사용 전 준비사항

1. 会費ペイ 계정 및 API 키 발급 필요
2. API 사양서 확인 (会費ペイAPI 사양서)
3. 클라이언트와 직접 문의하여 API 접근 권한 획득 필요

## 제공되는 주요 기능

- 회원 정보 조회
- 결제 내역 조회
- 회원 등록/수정
- 결제 상태 확인

## Google Apps Script 샘플 코드

### 1. API 키 설정

```javascript
// code.gs

// Google Sheet에서 API 정보 읽기
function getKaihipayConfig() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('API_Config');
  return {
    apiKey: sheet.getRange('B1').getValue(), // API Key
    apiSecret: sheet.getRange('B2').getValue(), // API Secret
    baseUrl: 'https://api.kaihipay.jp/api/v1' // API Base URL (추정)
  };
}
```

### 2. 회원 정보 조회

```javascript
// 회원 목록 조회
function getKaihipayMembers() {
  const config = getKaihipayConfig();

  const url = `${config.baseUrl}/members`;

  const options = {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${config.apiKey}`,
      'Content-Type': 'application/json'
    },
    muteHttpExceptions: true
  };

  try {
    const response = UrlFetchApp.fetch(url, options);
    const statusCode = response.getResponseCode();

    if (statusCode === 200) {
      const data = JSON.parse(response.getContentText());
      Logger.log('회원 정보: ' + JSON.stringify(data));
      return data;
    } else {
      Logger.log('에러: ' + statusCode + ' - ' + response.getContentText());
      return null;
    }
  } catch (error) {
    Logger.log('API 호출 실패: ' + error.toString());
    return null;
  }
}
```

### 3. 결제 내역 조회

```javascript
// 결제 내역 조회
function getKaihipayPayments(startDate, endDate) {
  const config = getKaihipayConfig();

  const url = `${config.baseUrl}/payments?start_date=${startDate}&end_date=${endDate}`;

  const options = {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${config.apiKey}`,
      'Content-Type': 'application/json'
    },
    muteHttpExceptions: true
  };

  try {
    const response = UrlFetchApp.fetch(url, options);
    const statusCode = response.getResponseCode();

    if (statusCode === 200) {
      const data = JSON.parse(response.getContentText());
      return data;
    } else {
      Logger.log('에러: ' + statusCode + ' - ' + response.getContentText());
      return null;
    }
  } catch (error) {
    Logger.log('API 호출 실패: ' + error.toString());
    return null;
  }
}
```

### 4. 데이터를 Google Sheet에 저장

```javascript
// 결제 내역을 Sheet에 저장
function savePaymentsToSheet() {
  const today = new Date();
  const startDate = new Date(today.getFullYear(), today.getMonth(), 1);
  const endDate = today;

  const startDateStr = Utilities.formatDate(startDate, 'JST', 'yyyy-MM-dd');
  const endDateStr = Utilities.formatDate(endDate, 'JST', 'yyyy-MM-dd');

  const payments = getKaihipayPayments(startDateStr, endDateStr);

  if (!payments || !payments.data) {
    Logger.log('결제 데이터가 없습니다.');
    return;
  }

  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('KaihipayPayments');
  if (!sheet) {
    Logger.log('KaihipayPayments 시트를 찾을 수 없습니다.');
    return;
  }

  // 헤더 설정
  sheet.getRange(1, 1, 1, 5).setValues([
    ['날짜', '회원명', '금액', '상태', '결제방법']
  ]);

  // 데이터 저장
  const rows = payments.data.map(payment => [
    payment.date,
    payment.member_name,
    payment.amount,
    payment.status,
    payment.payment_method
  ]);

  if (rows.length > 0) {
    sheet.getRange(2, 1, rows.length, 5).setValues(rows);
  }

  Logger.log(`${rows.length}건의 결제 내역을 저장했습니다.`);
}
```

### 5. 자동 업데이트 설정

```javascript
// Sheet 오픈 시 자동 업데이트
function onOpen() {
  const ui = SpreadsheetApp.getUi();
  ui.createMenu('会費ペイ')
    .addItem('데이터 업데이트', 'updateKaihipayData')
    .addToUi();
}

// 업데이트 실행
function updateKaihipayData() {
  savePaymentsToSheet();
  SpreadsheetApp.getActiveSpreadsheet().toast('会費ペイ 데이터가 업데이트되었습니다.', '완료', 3);
}
```

## 주의사항

1. **API 사양서 확인 필요**: 위 코드는 추정된 엔드포인트를 사용하고 있습니다. 실제 API Reference를 확인하여 정확한 엔드포인트와 파라미터를 사용해야 합니다.

2. **인증 방식 확인**: API 키 방식인지, OAuth 방식인지 확인이 필요합니다.

3. **Rate Limit**: API 호출 제한이 있을 수 있으므로 확인 필요합니다.

4. **에러 처리**: 실제 운영 시 더 상세한 에러 처리가 필요합니다.

## 다음 단계

1. 会費ペイ에 API 접근 권한 요청
2. API 사양서 확보
3. 실제 엔드포인트 및 데이터 형식 확인
4. 테스트 환경에서 API 연동 테스트
5. 본번 환경 적용

## 참고 링크

- 公式サイト: https://kaihipay.jp/
- API Reference: https://api.kaihipay.jp/api/reference/
- API機能紹介: https://blog.kaihipay.jp/introduction-api/