50308dd340
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
139 lines
4.0 KiB
Markdown
139 lines
4.0 KiB
Markdown
# 법인카드 사용내역 조회 모듈
|
|
|
|
바로빌 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)
|
|
|