[Delphi(델파이)] 팝빌 현금영수증 API 연동 가이드

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

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

팝빌 SDK는 Delphi v5.x 이상(XE, v10.x 포함) 모든 개발환경을 지원하며, 통신을 위한 별도 프로그램 설치가 필요하지 않습니다.

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

아래 설명하는 예시는 Delphi v5.x 기준으로 작성되어 있어, 이용 중이신 개발환경과 차이가 있을 수 있는 점 감안해 주시기 바랍니다.

1. 프로젝트 생성

---

Delphi에서 [File > New Application] 메뉴를 선택하여 현금영수증 API SDK 추가하기 위한 신규 프로젝트를 생성합니다. 

2. 현금영수증 SDK 추가

---

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

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

② 신규 프로젝트 생성 경로에 "Popbill Unit" 명으로 새 폴더를 생성하고, SDK에 포함되어 있는 Linkhub.pas, Popbill.pas, PopbillCahbill.pas 유닛을 복사합니다.

③ Delphi에서 [Project > Add to Project...] 메뉴를 선택합니다.

④ "Popbill Unit" 폴더에서 Linkhub.pas, Popbill.pas, PopbillCashbill.pas 유닛을 선택하여 프로젝트에 추가합니다.

프로젝트에 유닛이 추가된 것을 확인할 수 있습니다.

⑤ MainForm에 참조 유닛(Popbill, PopbillCashbill), 인증정보(LinkID, SecretKey), 클래스(TCashbillService)를 선언합니다. 

uses         
        // 참조 유닛 추가        
        Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs, StdCtrls, Popbill, PopbillCashbill;  

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

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

var         
        // 클래스 선언 추가        
        cashbillService : TCashbillService;  

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

API 호출 시점에 인증서버로부터 발급받은 토큰을 이용해 사용자를 인증하며, 발급된 토큰은 30분의 유효시간 내에서 재사용이 가능합니다. 만약, 현금영수증 서비스 객체를 지역변수로 선언하거나  API 호출시 마다 객체를 초기화 시키면 API를 호출할 때마다 토큰을 재발급 받는 과정을 거처야 하기 때문에 성능 저하 및 리소스 낭비의 요인이 됩니다.

⑥ FormCreate, FormClose 이벤트에서 TCashbillService Class를 생성/해제하고 MainForm의 전역변수로 선언합니다.

procedure TfrmMyForm.FormCreate(Sender: TObject);
begin              
        // 현금영수증 클래스 생성           
        cashbillService := TCashbillService.Create(LinkID,SecretKey);           

        // true - 개발용(테스트베드), false - 상업용(실서비스)        
        cashbillService.IsTest := true;                                                     

        // API 호출 시 파라미터의 정보에 이상이 있는 경우 예외(Exception)가 발생하며, 오류코드와 오류메시지를 반환합니다.
        // 발생한 예외는 true일 경우 except문에서 처리하고, false일 경우 except문에서 처리하지 않도록 구현되어 있습니다. 
        // 기본값은 true이며, true로 설정하여 사용시 애플리케이션이 비정상 종료되는 경우 false로 변경하여 사용합니다. 
        cashbillService.IsThrowException := true;          
end;

procedure TfrmMyForm.FormClose(Sender: TObject; var Action: TCloseAction);
begin         
        // 현금영수증 클래스 해제        
        cashbillService.Free;                                                        
end;

3. API 구현

---

① 버튼 클릭 시 RegistIssue API 호출하여 현금영수증을 발행하기 위해 MainForm에 버튼을 생성합니다.

② btnRegistIssue OnClick 이벤트에 현금영수증을 발행하기 위해 RegistIssue API를 작성합니다.

procedure TfrmExample.btnRegistIssueClick(Sender: TObject);
var
        cashbill : TCashbill;
        response : TResponse;
        memo : String;
        corpNum : String;
begin
        // 팝빌회원 사업자번호
        corpNum := '1234567890';
      
        cashbill := TCashbill.Create;

        // [필수] 문서 관리번호 1~24자리, 영문, 숫자, '-', '_' 조합하여 구성
        // 사업자별로 중복되지 않도록 구성
        cashbill.MgtKey := '20181031-001'

        // [취소거래시 필수] 원본 현금영수증 국세청승인번호
        // 문서 정보 (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';

        // [필수] 가맹점 사업자번호, '-' 제외 10자리
        cashbill.franchiseCorpNum := corpNum;

        // 가맹점 상호
        cashbill.franchiseCorpName := '발행자상호';

        // 가맹점 대표자 성명
        cashbill.franchiseCEOName := '발행자 대표자';

        // 가맹점 주소
        cashbill.franchiseAddr := '발행자 주소';

        // 가맹점 전화번호
        cashbill.franchiseTEL := '07043042991';

        // [필수] 식별번호
        // 거래구분(tradeUsage)이 '소득공제용'인 경우 [주민등록/휴대폰/카드]번호로 발행가능
        // 거래구분(traseUsage)이 '지출증빙용'인 경우 [주민등록/휴대폰/카드/사업자]번호로 발행가능
        cashbill.identityNum := '0101112222';

        // 주문자명
        cashbill.customerName := '고객명';

        // 주문상품명
        cashbill.itemName := '상품명';

        // 주문번호
        cashbill.orderNumber := '주문번호';

        // 주문자 이메일주소
        cashbill.email := 'test@test.com';

        // 주문자 휴대폰번호
        cashbill.hp := '010-111-222';

        // 주문자 팩스번호
        cashbill.fax := '777-444-333';

        // 발행안내문자 전송여부
        cashbill.smssendYN := False;

        // 메모
        memo := '즉시발행 현금영수증 메모';
                
        try
                response := cashbillService.RegistIssue(corpNum, cashbill, memo);
                cashbill.Free;
        except
                on le : EPopbillException do begin
                        cashbill.Free;
                        ShowMessage('응답코드 : ' + IntToStr(le.code) + #10#13 
                                    + '응답메시지 : ' + le.Message);
                        Exit;
                end;
        end;

        ShowMessage('응답코드 : ' + IntToStr(response.code) + #10#13 
                    + '응답메시지 : ' + response.Message);
end;

③ 정상적으로 API 호출이 완료되었음을 메시지를 통해 확인합니다. 

[참고] "권한정보의 서명이 일치하지 않습니다." 오류메시지 해결방법 안내 - https://linkhub.tistory.com/98

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

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

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

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

---

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

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