[PHP] 팝빌 현금영수증 API 연동 가이드

안녕하세요. 고객의 가치를 연결하는 비즈니스 파트너 링크허브 입니다.

본 포스팅에서는 PHP 개발환경에서 고객사들이 팝빌 현금영수증 API SDK를 쉽고 빠르게 이용할 수 있도록, 예시를 이용하여 연동 설정 방법을 안내드리겠습니다. 먼저, SDK를 추가한 후 "즉시발행(RegistIssue) API"를 구현하는 순서로 진행하겠습니다.

팝빌 SDK는 PHP v4.x 이상 모든 개발환경에서 이용 가능하며, API 호출과 응답의 메시지 인코딩은 "UTF-8 Character-Set"을 지원합니다.

"팝빌은 링크허브에서 자체 개발하고 직접 운영하는 현금영수증 서비스 Brand Name 입니다."

아래 설명하는 예시는 [ CentOS v6.8 | Apache v2.2.15 | PHP v5.5.38 ] 기준으로 작성되어 있어, 이용 중이신 개발환경과 차이가 있을 수 있는 점 감안해 주시기 바랍니다.

1. 서버환경 구성

현금영수증 API 연동을 위해서 통신환경 구성을 위한 curl, openssl 두 가지의 PHP 모듈이 반드시 추가되어 있어야 합니다.

curl 모듈은 통신 프로토콜을 이용하여 데이터를 전송하기 위한 라이브러리와 커맨드 라인 도구를 제공하고, openssl 모듈은 보안 프로토콜인 TLS 통신을 지원하며 암호화 기능 및 여러가지 유틸리티가 포함되어 있습니다.

다음 커맨드를 사용하여 서버에 설치되어 있는 PHP 모듈을 확인합니다.

# php -m
[php modules]
bz2
curl
date
ftp
json
openssl
session
standard
tokenizer

[Zend Modules]

curl 모듈이 설치되어 있지 않다면, 다음을 참고하여 curl 모듈을 추가합니다.

[참고] PHP-curl 모듈 추가 과정 https://linkhub.tistory.com/145

2. 현금영수증 SDK 추가

① 링크허브 연동자료실에서 PHP 현금영수증 SDK를 다운로드 후 압축을 해제합니다.

[참고] PHP 현금영수증 SDK 다운로드 - https://www.linkhub.co.kr/Downloads/Cashbill/67?PageNum=1

② SDK 내에 포함되어 있는 "Popbill" 폴더를 복사합니다.

③ 웹서버 기본 디렉토리에 "/var/www/html/common.php" 환경설정을 위한 파일을 신규로 생성하고 인증정보(LinkID, SecretKey), 통신방식, 클래스(CashbillService), 연동환경 설정값(IsTest)를 선언합니다.

<?php

require_once './Popbill/PopbillCashbill.php';

// 링크허브에서 발급받은 인증정보 링크아이디(LinkID), 비밀키(SecretKey)를 입력합니다.

// 인증정보는 파트너 식별 및 API 통신전문 변조를 방지하는 기능을 수행하므로
// 외부에 유출되지 않도록 각별히 유의하여 관리해 주시기 바랍니다.
$LinkID = 'LinkID';  
$SecretKey = 'SwWxqU+0TExEXy/9TVjKPExI2VTUMMSLZtJf3Ed8q3I=';

// 통신방식 설정. 기본값 - CURL
define('LINKHUB_COMM_MODE','CURL');

// 현금영수증 클래스 생성
$CashbillService = new CashbillService($LinkID, $SecretKey);

// true - 개발용(테스트베드), false - 상업용(실서비스)
$CashbillService->IsTest(true); 

?>

▶ 링크허브에서 발급받은 고객사 인증정보로 링크아이디(LinkID)와 비밀키(SecretKey) 값을 변경하시기 바랍니다.

Windows에서 Apache v2.2.x를 사용하는 경우, Apache와 curl에 각각 포함하고 있는 openssl 모듈 충돌로 인해 통신이 정상적이지 않을 수 있습니다. 이러한 경우 통신방식을 CURL에서 STREAM으로 변경하여야 하며, STREAM 모드에서는 php.ini의 allow_url_fopen항목의 값을 On으로 설정해야 합니다.

3. API 구현

① RegistIssue API를 호출하는 "/var/www/html/RegistIssue.php" 파일을 생성하고, 현금영수증을 발행하기 위해 RegistIssue API를 작성합니다.

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <title>현금영수증 API 연동 가이드</title>
</head>
<?php

include 'common.php';

// 팝빌 회원 사업자번호, '-' 제외 10자리
$corpNum = '1234567890';

// 문서관리번호, 사업자별로 중복없이 1~24자리 영문, 숫자, '-', '_' 조합으로 구성
$mgtKey = '20181031-001';

// 현금영수증 객체 생성
$Cashbill = new Cashbill();

// [필수] 현금영수증 문서관리번호,
$Cashbill->mgtKey = $mgtKey;

// [취소 현금영수증 발행시 필수] 원본 현금영수증 국세청승인번호
// 국세청승인번호는 GetInfo API의 ConfirmNum 항목으로 확인할 수 있습니다.
$Cashbill->orgConfirmNum = '';

// [취소 현금영수증 발행시 필수] 원본 현금영수증 거래일자
// 현금영수증 거래일자는 GetInfo API의 TradeDate 항목으로 확인할 수 있습니다.
$Cashbill->orgTradeDate = '';

// [필수] 문서형태, (승인거래, 취소거래) 중 기재
$Cashbill->tradeType = '승인거래';

// [필수] 거래구분, (소득공제용, 지출증빙용) 중 기재
$Cashbill->tradeUsage = '소득공제용';

// [필수] 거래유형, (일반, 도서공연, 대중교통) 중 기재
$Cashbill->tradeOpt = '일반';

// [필수] 과세형태, (과세, 비과세) 중 기재
$Cashbill->taxationType = '과세';

// [필수] 거래금액, ','콤마 불가 숫자만 가능
$Cashbill->totalAmount = '11000';

// [필수] 공급가액, ','콤마 불가 숫자만 가능
$Cashbill->supplyCost = '10000';

// [필수] 부가세, ','콤마 불가 숫자만 가능
$Cashbill->tax = '1000';

// [필수] 봉사료, ','콤마 불가 숫자만 가능
$Cashbill->serviceFee = '0';

// [필수] 가맹점 사업자번호
$Cashbill->franchiseCorpNum = $corpNum;

// 가맹점 상호
$Cashbill->franchiseCorpName = '발행자 상호';

// 가맹점 대표자 성명
$Cashbill->franchiseCEOName = '발행자 대표자명';

// 가맹점 주소
$Cashbill->franchiseAddr = '발행자 주소';

// 가맹점 전화번호
$Cashbill->franchiseTEL = '070-1234-1234';

// [필수] 식별번호, 거래구분에 따라 작성
// 소득공제용 - 주민등록/휴대폰/카드번호 기재가능
// 지출증빙용 - 사업자번호/주민등록/휴대폰/카드번호 기재가능
$Cashbill->identityNum = '0101112222';

// 주문자명
$Cashbill->customerName = '고객명';

// 주문상품명
$Cashbill->itemName = '상품명';

// 주문주문번호
$Cashbill->orderNumber = '주문번호';

// 주문자 이메일
$Cashbill->email = 'test@test.com';

// 주문자 휴대폰
$Cashbill->hp = '010-111-222';

// 발행시 알림문자 전송여부
$Cashbill->smssendYN = false;

// 메모
$memo = '현금영수증 즉시발행 메모';

try {
    $result = $CashbillService->RegistIssue($corpNum, $Cashbill, $memo);
    $code = $result->code;
    $message = $result->message;
} catch (PopbillException $pe) {
    $code = $pe->getCode();
    $message = $pe->getMessage();
}
?>
<body>
  Response.code : <?php echo $code ?></p>
  Response.message : <?php echo $message ?></p>
</body>
</html>

② 현금영수증 발행 처리결과를 응답 메시지를 통해 확인 합니다.

③ 발행된 현금영수증은 팝빌 개발용(test.popbill.com) 사이트에서 확인할 수 있습니다.

[참고] 팝빌 연동 개발을 위한 테스트베드(개발용) 안내 - https://linkhub.tistory.com/91

팝빌에서 제공하는 다양한 API는 동일한 컨셉으로 개발되어 있어, 하나의 서비스를 이용한 경험이 있으면 다른 서비스들도 유사한 방법으로 빠르게 연동이 가능하니 많은 이용 부탁드립니다.

지금까지 PHP 개발환경에서 현금영수증 API를 연동하는 방법에 대해 안내드렸습니다. 내용에 대한 추가적인 문의가 있으면 기술지원센터로 편하게 연락주시기 바랍니다.

고객사의 편의를 위하여 이메일, 전화 등 다양한 채널을 열어놓고 있으니 언제든지 연락 주시기 바랍니다.

기술지원센터 / T. 1600-9854 / E. code@linkhub.co.kr

저작자표시 동일조건

'가치를 연결하다 > 튜토리얼' 카테고리의 다른 글

[ASP.NET] 팝빌 현금영수증 API 연동 가이드 (0)	2018.11.01
[VB.NET] 팝빌 현금영수증 API 연동 가이드 (0)	2018.10.31
[Delphi(델파이)] 팝빌 현금영수증 API 연동 가이드 (0)	2018.10.31
[ASP] 팝빌 전자세금계산서 API 연동 가이드 (0)	2018.10.24

링크허브 공식블로그