튜토리얼
Delphi 개발환경에서 팝빌 SDK를 추가하고, 전자명세서 즉시 발행 (RegistIssue) API를 호출하는 기본 과정을 단계별로 따라 해볼 수 있도록 구성된 가이드 입니다.
1. POPBiLL SDK 추가
섹션 제목: “1. POPBiLL SDK 추가”팝빌 연동자료실에서 Delphi SDK 예제코드 다운로드 후 압축을 해제합니다.
압축해제한 SDK 예제코드에서 Linkhub/ Popbill/ PopbillTaxinvoice/ 각 폴더의 pas파일 3개를 프로젝트 유닛으로 추가합니다.
2. POPBiLL SDK 설정
섹션 제목: “2. POPBiLL SDK 설정”아래 코드를 참조하여 Form 파일을 수정합니다.
- ① use 참조유닛 추가
- ② 인증정보 변수와 서비스 클래스를 선언
- ③ FormCreate 프로시저에 전자명세서 서비스 클래스 인스턴스 생성 및 초기화
unit Example;
interface
uses Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs, StdCtrls, TypInfo, shellapi, ExtCtrls, Grids, Popbill, PopbillStatement;
const // API Key // - 연동신청 시 발급받은 인증 정보(LinkID, SecretKey로 구성) // • LinkID: 파트너를 식별하기 위한 고유 식별자 // • SecretKey: API 인증토큰 발급에 사용되는 키 // // TODO: 아래 LinkID, SecretKey를 발급받은 정보로 교체해 주세요. LinkID = 'TESTER'; SecretKey = 'SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I=';// 생략// ...// ...
var // 전자명세서 서비스 객체 선언 statementService : TStatementService;// 생략// ...// ...
procedure TfrmExample.FormCreate(Sender: TObject);begin // 전자명세서 서비스 객체 초기화 statementService := TStatementService.Create(LinkID,SecretKey);
// 연동환경(테스트/운영) 설정 // - 연동환경을 테스트 또는 운영으로 설정합니다. // • true: 테스트 환경으로 설정 // • false(default) : 운영 환경으로 설정 // // ※ 운영전환 이후부터 IsTest 설정 변경만으로 자유롭게 환경 전환(테스트<->운영)이 가능합니다. statementService.IsTest := true;
// 인증토큰 IP 일치 검증 사용 여부 // - 인증토큰을 발급받은 IP와, 그 토큰을 사용하여 API를 호출하는 IP가 같은지를 검사합니다. // (토큰이 외부로 유출되어도 다른 IP에서는 사용하지 못하도록 막는 보안 장치) // • true(사용, default) : 두 IP가 일치할 때만 API 호출 허용 // • false(미사용) : IP 일치 검사를 생략 // // ※ false는 토큰 발급 시점의 IP와 API 호출 시점의 IP가 달라질 수 있는 환경에서 사용 // 예) 오토스케일링, 로드밸런서, NAT 등으로 호출 IP가 유동적인 클라우드 환경 statementService.IPRestrictOnOff := true;
// 예외 처리 설정, true-사용, false-미사용, (기본값:true) statementService.IsThrowException := true;
// 로컬시스템 시간 사용 여부 // - 현재시각 기준을 설정합니다. // • true(사용) : 로컬시스템 시간 사용 // • false(미사용, default) : 팝빌 서버의 시간을 사용 // // ※ 현재시각은 주로 인증토큰 발급 및 만료 판단 등에 사용됩니다. // ※ 이 설정은 홈택스 수집 기간, 세금계산서 작성일자, 발행일자 같은 업무 데이터의 날짜값을 변경하는 옵션이 아닙니다. // ※ 로컬 서버 시간이 정상 동기화되어 있으면 일반적으로 true를 사용하고 서버 시간 오차로 인증 실패가 의심되거나 // 서버 시간을 신뢰하기 어려운 환경이면 false를 사용합니다. statementService.UseLocalTimeYN := false;end;3. RegistIssue 기능 구현
섹션 제목: “3. RegistIssue 기능 구현”Form에 버튼을 생성하고 버튼의 Click Event 코드에 전자명세서 즉시 발행 (RegistIssue) 함수를 추가합니다.
procedure TfrmExample.btnRegistIssueClick(Sender: TObject);var statement : TStatement; response : TResponse; memo : String; corpNum : String; mgtKey : String;begin
// 팝빌회원 사업자번호 corpNum := '1234567890';
// 전자명세서 문서번호 mgtKey := '20250314-001';
statement := TStatement.Create;
// 전자명세서 명세서 코드, 121-거래명세서, 122-청구서, 123-견적서, 124-발주서, 125-입금표, 126-영수증 statement.itemCode := 121;
// 맞춤양식코드, 기본값(공백처리) // 별도의 양식으로 전송하고자 하는경우 파트너센터(1600-8536)로 문의주시기 바랍니다. statement.formCode := '';
// [필수] 작성일자 statement.writeDate := '20250314';
// [필수] {영수, 청구, 없음} 중 기재 statement.purposeType := '영수';
// [필수] {과세, 영세, 면세} 중 기재 statement.taxType :='과세';
// 발행시 수신자 알림문자 전송여부 statement.SMSSendYN := false;
// [필수] 전자명세서 문서번호, 1~24자리, 영문, 숫자, '-', '_' // 조합으로 구성사업자별로 중복되지 않도록 구성 statement.MgtKey := mgtKey;
{**********************************************************************} { 발신자 정보 } {**********************************************************************}
// 발신자 사업자번호, '-'제외 10자리 statement.senderCorpNum := corpNum;
// 종사업장 식별번호. 필요시 기재. 형식은 숫자 4자리. statement.senderTaxRegID := '';
// 발신자 상호 statement.senderCorpName := '발신자 상호';
// 발신자 대표자 성명 statement.senderCEOName := '발신자 대표자 성명';
// 발신자 주소 statement.senderAddr := '발신자 주소';
// 발신자 종목 statement.senderBizClass := '발신자 종목';
// 발신자 업태 statement.senderBizType := '발신자 업태,업태2';
// 발신자 담당자명 statement.senderContactName := '발신자 담당자명';
// 발신자 담당자 메일주소 statement.senderEmail := 'test@test.com';
// 발신자 담당자 연락처 statement.senderTEL := '070-7070-0707';
// 발신자 담당자 휴대폰번호 statement.senderHP := '010-000-2222';
// 발신자 담당자 팩스 statement.senderFAX := '070-000-111';
{**********************************************************************} { 수신자 정보 } {**********************************************************************}
// 수신자 사업자번호, '-' 제외 10자리 statement.receiverCorpNum := '8888888888';
// 수신자 상호 statement.receiverCorpName := '수신자 상호';
// 종사업장 식별번호. 필요시 기재. 형식은 숫자 4자리. statement.receiverTaxRegID := '';
// 수신자 대표자 성명 statement.receiverCEOName := '수신자 대표자 성명';
// 수신자 주소 statement.receiverAddr := '수신자 주소';
// 수신자 종목 statement.receiverBizClass := '수신자 업종';
// 수신자 업태 statement.receiverBizType := '수신자 업태';
// 수신자 담당자명 statement.receiverContactName := '수신자 담당자명';
// 수신자 담당자 메일주소 // 팝빌 개발환경에서 테스트하는 경우에도 안내 메일이 전송되므로, // 실제 거래처의 메일주소가 기재되지 않도록 주의 statement.receiverEmail := 'test@receiver.com';
// 수신자 담당자 연락처 statement.receiverTEL := '070-1234-1234';
// 수신자 담당자 휴대폰번호 statement.receiverHP := '010-111-222';
// 수신자 담당자 팩스 statement.receiverFAX := '070-000-111';
//[필수] 공급가액 합계 statement.supplyCostTotal := '200000';
//[필수] 세액 합계 statement.taxTotal := '20000';
//[필수] 합계금액. 공급가액 + 세액 statement.totalAmount := '220000';
// 기재 상 일련번호 statement.serialNum := '1';
// 비고 statement.remark1 := '비고1'; statement.remark2 := '비고2'; statement.remark3 := '비고3';
// 사업자등록증 첨부여부 statement.businessLicenseYN := false;
// 통장사본 첨부여부 statement.bankBookYN := false;
{**********************************************************************} { 전자명세서 상세항목(품목) 정보 } { 일련번호(serialNum)은 1부터 순차적으로 기재하시기 바랍니다. } {**********************************************************************}
//SetLength로 초기화 한후 기재. setLength(statement.detailList, 2);
statement.detailList[0] := TStatementDetail.Create; statement.detailList[0].serialNum := 1; //일련번호 statement.detailList[0].purchaseDT := '20250314'; //거래일자 statement.detailList[0].itemName := '품목명'; //품목명 statement.detailList[0].spec := '규격'; //규격 statement.detailList[0].qty := '1'; //수량 statement.detailList[0].unitCost := '100000'; //단가 statement.detailList[0].supplyCost := '100000'; //공급가액 statement.detailList[0].tax := '10000'; //세액 statement.detailList[0].remark := '품목비고'; //비고 statement.detailList[0].spare1 := '여분1'; //여분1 statement.detailList[0].spare2 := '여분2'; //여분2 statement.detailList[0].spare3 := '여분3'; //여분3 statement.detailList[0].spare4 := '여분4'; //여분4 statement.detailList[0].spare5 := '여분5'; //여분5
statement.detailList[1] := TStatementDetail.Create; statement.detailList[1].serialNum := 2; //일련번호 statement.detailList[1].purchaseDT := '20250314'; //거래일자 statement.detailList[1].itemName := '품목명'; //품목명 statement.detailList[1].spec := '규격'; //규격 statement.detailList[1].qty := '1'; //수량 statement.detailList[1].unitCost := '100000'; //단가 statement.detailList[1].supplyCost := '100000'; //공급가액 statement.detailList[1].tax := '10000'; //세액 statement.detailList[1].remark := '품목비고'; //비고 statement.detailList[1].spare1 := '여분1'; //여분1 statement.detailList[1].spare2 := '여분2'; //여분2 statement.detailList[1].spare3 := '여분3'; //여분3 statement.detailList[1].spare4 := '여분4'; //여분4 statement.detailList[1].spare5 := '여분5'; //여분5
{**********************************************************************} { 추가속성 항목 } {**********************************************************************}
setLength(statement.propertyBag,3);
statement.propertyBag[0] := TProperty.Create; statement.propertyBag[0].name := 'Balance'; //전잔액 statement.propertyBag[0].value := '30000';
statement.propertyBag[1] := TProperty.Create; statement.propertyBag[1].name := 'CBalance'; //현금액 statement.propertyBag[1].value := '20000';
statement.propertyBag[2] := TProperty.Create; statement.propertyBag[2].name := 'Deposit'; //현잔액 statement.propertyBag[2].value := '10000';
memo := '즉시 발행 메모';
try response := statementService.RegistIssue(corpNum, statement, memo); statement.Free; except on le : EPopbillException do begin statement.Free; ShowMessage('응답코드 : ' + IntToStr(le.code) + #10#13 +'응답메시지 : '+ le.Message); Exit; end; end; ShowMessage('응답코드 : ' + IntToStr(response.code) + #10#13 + '응답메시지 : '+ response.Message + #10#13 +'팝빌 승인번호 : '+ response.invoiceNum);end;4. API 응답결과 확인
섹션 제목: “4. API 응답결과 확인”API 호출 응답결과는 다음과 같습니다.
| 구분 | 응답 |
|---|---|
| 성공 | code : 1 |
| 실패 | code : 오류코드 (8자리 음의 정수) [오류코드] message : 오류메시지 |