sam-sales/barobill/ecard

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

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

📋 기능

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

🔧 설정

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

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

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

2. 바로빌 카드 등록

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

1. 바로빌 로그인
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

응답 예시:

{
  "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

응답 예시:

{
  "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 레퍼런스
• 바로빌 개발자센터