# 법인카드 사용내역 조회 모듈

바로빌 API를 이용한 법인카드 사용내역 조회 모듈입니다.

## 📋 기능

- 등록된 카드 목록 조회
- 기간별/일별/월별 카드 사용내역 조회
- 사용금액 통계 (총 사용금액, 사용건수, 취소건수)
- 페이지네이션 지원

## 🔧 설정

### 1. API 키 설정 (기존 etax 모듈과 공유)

다음 파일들이 필요합니다 (`/apikey/` 폴더):

| 파일명 | 설명 | 예시 |
|--------|------|------|
| `barobill_cert_key.txt` | 바로빌 CERTKEY (인증서 키) | `ABC123...` |
| `barobill_corp_num.txt` | 사업자번호 (하이픈 제외) | `6648603713` |
| `barobill_test_mode.txt` | 테스트 모드 (선택) | `test` 또는 `true` |

### 2. 바로빌 카드 등록

카드 사용내역을 조회하려면 **바로빌 웹사이트**에서 카드를 먼저 등록해야 합니다.

1. [바로빌](https://www.barobill.co.kr) 로그인
2. 카드조회 서비스 신청
3. 카드 등록 (카드사 웹 ID/비밀번호 필요)

## 📁 파일 구조

```
ecard/
├── index.php                    # 메인 UI (React 기반)
├── api/
│   ├── barobill_card_config.php # 바로빌 카드 API 설정
│   ├── cards.php                # 등록된 카드 목록 API
│   └── usage.php                # 카드 사용내역 조회 API
└── README.md                    # 이 문서
```

## 🔌 API 엔드포인트

### 카드 목록 조회
```
GET /ecard/api/cards.php
```

**응답 예시:**
```json
{
  "success": true,
  "cards": [
    {
      "cardNum": "1234-****-****-5678",
      "cardCompany": "02",
      "cardCompanyName": "KB국민",
      "alias": "법인카드1",
      "status": "1",
      "statusName": "정상"
    }
  ],
  "count": 1
}
```

### 사용내역 조회
```
GET /ecard/api/usage.php?type=period&startDate=20241101&endDate=20241130
```

**파라미터:**
| 파라미터 | 설명 | 기본값 |
|---------|------|--------|
| `type` | 조회 타입 (period/daily/monthly) | `period` |
| `cardNum` | 카드번호 (빈값=전체) | - |
| `startDate` | 시작일 (YYYYMMDD) - period용 | 30일 전 |
| `endDate` | 종료일 (YYYYMMDD) - period용 | 오늘 |
| `baseDate` | 기준일 (YYYYMMDD) - daily용 | 오늘 |
| `baseMonth` | 기준월 (YYYYMM) - monthly용 | 이번달 |
| `page` | 페이지 번호 | `1` |
| `limit` | 페이지당 건수 | `50` |

**응답 예시:**
```json
{
  "success": true,
  "data": {
    "logs": [
      {
        "cardNum": "1234-****-****-5678",
        "approvalNum": "12345678",
        "approvalDate": "2024-11-15",
        "approvalTime": "14:30:25",
        "merchantName": "스타벅스 강남점",
        "amount": 5000,
        "totalAmountFormatted": "5,000",
        "approvalTypeName": "승인",
        "installmentName": "일시불"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "countPerPage": 50,
      "maxPageNum": 1,
      "totalCount": 15
    },
    "summary": {
      "totalAmount": 150000,
      "count": 15,
      "approvalCount": 14,
      "cancelCount": 1
    }
  }
}
```

## 🎨 UI 기능

- **카드 선택**: 특정 카드 또는 전체 카드 조회
- **기간 설정**: 날짜 범위 직접 선택 또는 빠른 선택 (오늘, 7일, 30일, 3개월, 6개월)
- **통계 대시보드**: 총 사용금액, 사용건수, 취소건수 표시
- **사용내역 테이블**: 승인일시, 가맹점명, 금액, 할부, 승인/취소 구분

## ⚠️ 주의사항

1. 바로빌 카드조회 서비스는 **유료 서비스**입니다.
2. 카드 등록 시 **카드사 웹 ID/비밀번호**가 필요합니다.
3. 카드사에서 데이터를 수집하므로 **실시간 조회가 아닐 수 있습니다** (보통 1일 1회 수집).
4. 테스트 환경에서는 실제 데이터가 아닌 테스트 데이터가 조회됩니다.

## 🔗 참고 문서

- [바로빌 카드조회 API 레퍼런스](https://dev.barobill.co.kr/docs/references/카드조회-API)
- [바로빌 개발자센터](https://dev.barobill.co.kr)