sam-kd/etax/api

바로빌 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. 바로빌 개발자센터 접속
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 사용 예제

세금계산서 발행

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);

국세청 전송

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

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

참고 문서

• 바로빌 개발자센터
• 바로빌 세금계산서 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가 선택사항일 수 있음

사업자번호 오류

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