hskwon
aca1767eb9
- URL 하드코딩 → .env APP_URL 기반 동적 URL로 변경 - DB 연결 하드코딩 → .env 기반으로 변경 - MySQL strict mode DATE 오류 수정
148 lines
4.6 KiB
Markdown
148 lines
4.6 KiB
Markdown
# 바로빌 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가 선택사항일 수 있음
|
|
|
|
### 사업자번호 오류
|
|
|
|
- 하이픈(-) 없이 숫자만 입력했는지 확인
|
|
- 발행자 사업자번호가 올바른지 확인
|