# 바로빌 API 연동 가이드

## ⚠️ 중요: 바로빌은 SOAP 웹서비스를 사용합니다

바로빌 API는 REST API가 아닌 **SOAP 웹서비스**를 사용합니다.
- 테스트 환경: `https://testws.baroservice.com/TI.asmx?WSDL`
- 운영 환경: `https://ws.baroservice.com/TI.asmx?WSDL`

## API 키 설정

### 1. 필수 파일 생성

`apikey` 폴더에 다음 파일들을 생성하세요:

#### 필수 파일
- `barobill_cert_key.txt`: CERTKEY (인증서 키)
  - 바로빌 개발자센터에서 인증서 등록 후 발급받은 CERTKEY
  - 세금계산서 발행에 필수

- `barobill_corp_num.txt`: 사업자번호
  - 세금계산서를 발행할 회사의 사업자번호
  - 하이픈(-) 없이 숫자만 입력
  - 예: `1234567890`

#### 선택 파일
- `barobill_test_mode.txt`: 테스트 모드 사용 시 "test" 또는 "true" 입력
  - 테스트 환경: `https://testws.baroservice.com/TI.asmx?WSDL`
  - 운영 환경: `https://ws.baroservice.com/TI.asmx?WSDL`

### 2. CERTKEY 발급 방법

1. [바로빌 개발자센터](https://dev.barobill.co.kr) 접속
2. 회원가입 및 로그인
3. 개발자센터 메뉴에서 "인증서 관리" 또는 "인증서 등록" 메뉴 찾기
4. 공동인증서(.pfx 또는 .p12 파일) 또는 금융인증서 업로드
5. 인증서 비밀번호 입력 및 등록
6. 등록 완료 후 발급받은 **CERTKEY** 확인
   - 예: "CERT-2024-ABC123-XYZ789" 또는 숫자/문자 조합의 고유 키
7. `apikey/barobill_cert_key.txt` 파일에 CERTKEY 저장

### 3. 사업자번호 설정

1. 세금계산서를 발행할 회사의 사업자번호 확인
2. 하이픈(-) 없이 숫자만 입력
   - 예: `123-45-67890` → `1234567890`
3. `apikey/barobill_corp_num.txt` 파일에 저장

### 4. 테스트 모드 설정

테스트 환경을 사용하려면:

1. `apikey/barobill_test_mode.txt` 파일 생성
2. 파일 내용에 `test` 또는 `true` 입력
3. 저장

## API 엔드포인트

### 세금계산서 발행 (저장 + 발급)
- **SOAP 메서드**: `RegistAndIssueTaxInvoice`
- **파일**: `issue.php`
- **문서**: `etax/docs/barobill-api-doc/TAXINVOICE/RegistAndIssueTaxInvoice.php`

### 세금계산서 조회
- **SOAP 메서드**: `GetTaxInvoice`
- **파일**: `invoices.php`
- **문서**: `etax/docs/barobill-api-doc/TAXINVOICE/GetTaxInvoice.php`

### 세금계산서 상태 조회
- **SOAP 메서드**: `GetTaxInvoiceStateEX`
- **문서**: `etax/docs/barobill-api-doc/TAXINVOICE/GetTaxInvoiceStateEX.php`

### 국세청 전송
- **SOAP 메서드**: `SendToNTS`
- **파일**: `status.php`
- **문서**: `etax/docs/barobill-api-doc/TAXINVOICE/SendToNTS.php`

## SOAP API 사용 예제

### 세금계산서 발행

```php
require_once(__DIR__ . '/barobill_config.php');

$invoiceData = [
    'issueKey' => 'MGT20241201123456', // 관리번호 (MgtKey)
    'supplierBizno' => '1234567890',
    'supplierName' => '공급자 회사명',
    'recipientBizno' => '0987654321',
    'recipientName' => '수취인 회사명',
    'supplyDate' => '2024-12-01',
    'items' => [
        [
            'name' => '품목명',
            'spec' => '규격',
            'qty' => '1',
            'unitPrice' => 10000,
            'supplyAmt' => 10000,
            'vat' => 1000
        ]
    ],
    'memo' => '비고'
];

$result = issueTaxInvoice($invoiceData);
```

### 국세청 전송

```php
require_once(__DIR__ . '/barobill_config.php');

$mgtKey = 'MGT20241201123456'; // 관리번호
$result = sendToNTS($mgtKey);
```

## 참고 문서

- [바로빌 개발자센터](https://dev.barobill.co.kr)
- [바로빌 세금계산서 API 문서](https://dev.barobill.co.kr/docs/references/%EC%84%B8%EA%B8%88%EA%B3%84%EC%82%B0%EC%84%9C-API)
- 로컬 문서: `etax/docs/barobill-api-doc/` 폴더

## 주의사항

1. **CERTKEY와 사업자번호는 절대 공개 저장소에 커밋하지 마세요**
2. `.gitignore`에 `apikey/*.txt` (예제 파일 제외) 추가 권장
3. 테스트 환경과 운영 환경의 CERTKEY를 분리하여 관리하세요
4. SOAP 클라이언트는 PHP의 `SoapClient` 클래스를 사용합니다
5. PHP 7.3 이상에서 `SoapClient` 확장이 활성화되어 있어야 합니다

## 문제 해결

### SOAP 클라이언트 생성 실패

- PHP `SoapClient` 확장이 설치되어 있는지 확인
- `php -m | grep soap` 명령으로 확인
- 설치되지 않았다면 PHP 확장 설치 필요

### CERTKEY 오류

- CERTKEY가 올바르게 입력되었는지 확인
- 바로빌 개발자센터에서 인증서가 정상적으로 등록되었는지 확인
- 테스트 모드에서는 CERTKEY가 선택사항일 수 있음

### 사업자번호 오류

- 하이픈(-) 없이 숫자만 입력했는지 확인
- 발행자 사업자번호가 올바른지 확인