튜토리얼
Node.js 개발환경에서 팝빌 SDK를 추가하여 전자세금계산서 즉시 발행 (RegistIssue) 함수를 구현하는 예시입니다.
1. POPBiLL SDK 추가
팝빌 Node.js SDK를 추가하기 위해 Express 프로젝트 "package.json" 파일에 팝빌 Node.js SDK 정보를 추가하고 npm install 또는 npm update를 진행합니다.
{
"name": "Popbill TEST",
"version": "0.0.0",
"private": true,
"scripts": {
"start": "node ./bin/www"
},
"dependencies": {
"cookie-parser": "~1.4.3",
"debug": "~2.6.9",
"ejs": "~2.5.7",
"express": "~4.16.0",
"http-errors": "~1.6.2",
"morgan": "~1.9.0",
"popbill": "^1.59.3"
}
}2. POPBiLL SDK 설정
프로젝트 routes 폴더 하위의 index.js 파일에 연동신청시 발급받은 API Key 를 변수로 선언하고 아래의 코드를 참조하여 전자세금계산서 서비스 객체를 생성 합니다.
// 생략..
var popbill = require('popbill');
popbill.config( {
// 링크아이디
LinkID :'TESTER',
// 비밀키
SecretKey : 'SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3T=',
// 연동환경 설정, true-테스트, false-운영(Production), (기본값:false)
IsTest : true,
// 통신 IP 고정, true-사용, false-미사용, (기본값:true)
IPRestrictOnOff: true,
// 팝빌 API 서비스 고정 IP 사용여부, 기본값(false)
UseStaticIP: false,
// 로컬시스템 시간 사용여부, true-사용, false-미사용, (기본값:true)
UseLocalTimeYN: true,
defaultErrorHandler: function (Error) {
console.log('Error Occur : [' + Error.code + '] ' + Error.message);
}
});
// 전자세금계산서 서비스 객체 초기화
var taxinvoiceService = popbill.TaxinvoiceService();
// 생략..
3. RegistIssue 기능 구현
index.js 파일에 전자세금계산서 즉시 발행 (RegistIssue) 함수 호출 코드를 추가합니다.
router.get('/registIssue', function (req, res, next) {
// 팝빌회원 사업자번호, '-' 제외 10자리
var testCorpNum = '1234567890';
// 문서번호, 1~24자리 영문,숫자,'-','_' 조합으로 사업자별로 중복되지 않도록 구성
var mgtKey = '20220101-032';
// 세금계산서 항목
var Taxinvoice = {
// [필수] 작성일자, 날짜형식 yyyyMMdd
writeDate: '20220101',
// [필수] 과금방향, (정과금, 역과금) 중 기재, 역과금은 역발행의 경우만 가능
chargeDirection: '정과금',
// [필수] 발행형태, (정발행, 역발행, 위수탁) 중 기재
issueType: '정발행',
// [필수] (영수, 청구, 없음) 중 기재
purposeType: '영수',
// [필수] 과세형태, (과세, 영세, 면세) 중 기재
taxType: '과세',
/************************************************************************
* 공급자 정보
**************************************************************************/
// [필수] 공급자 사업자번호, '-' 제외 10자리
invoicerCorpNum: testCorpNum,
// [정발행시 필수] 문서번호, 1~24자리 숫자,영문,'-','_' 조합으로 사업자별로 중복되지 않도록 구성
invoicerMgtKey: mgtKey,
// 공급자 종사업장 식별번호, 필요시 기재, 4자리 숫자
invoicerTaxRegID: '',
// [필수] 공급자 상호
invoicerCorpName: '공급자 상호',
// [필수] 대표자 성명
invoicerCEOName: '대표자 성명',
// 공급자 주소
invoicerAddr: '공급자 주소',
// 공급자 종목
invoicerBizClass: '공급자 업종',
// 공급자 업태
invoicerBizType: '공급자 업태',
// 공급자 담당자명
invoicerContactName: '공급자 담당자명',
// 공급자 연락처
invoicerTEL: '070-4304-2991',
// 공급자 휴대폰번호
invoicerHP: '010-000-111',
// 공급자 메일주소
invoicerEmail: 'test@test.com',
// 정발행시 알림문자 전송여부
// - 문자전송지 포인트가 차감되며, 전송실패시 포인트 환불처리됩니다.
invoicerSMSSendYN: false,
/************************************************************************
* 공급받는자 정보
**************************************************************************/
// [필수] 공급받는자 구분, (사업자, 개인, 외국인) 중 기재
invoiceeType: '사업자',
// [필수] 공급받는자 사업자번호, '-'제외 10자리
invoiceeCorpNum: '8888888888',
// [역발행시 필수] 공급받는자 문서번호
invoiceeMgtKey: '',
// 공급받는자 종사업장 식별번호, 필요시 기재, 4자리 숫자
invoiceeTaxRegID: '',
// [필수] 공급받는자 상호
invoiceeCorpName: '공급받는자 상호',
// [필수] 공급받는자 대표자 성명
invoiceeCEOName: '공급받는자 대표자 성명',
// 공급받는자 주소
invoiceeAddr: '공급받는자 주소',
// 공급받는자 종목
invoiceeBizClass: '공급받는자 종목',
// 공급받는자 업태
invoiceeBizType: '공급받는자 업태',
// 공급받는자 담당자명
invoiceeContactName1: '공급받는자 담당자명',
// 공급받는자 연락처
invoiceeTEL1: '010-111-222',
// 공급받는자 휴대폰번호
invoiceeHP1: '070-111-222',
// 공급받는자 이메일 주소
// 팝빌 개발환경에서 테스트하는 경우에도 안내 메일이 전송되므로,
// 실제 거래처의 메일주소가 기재되지 않도록 주의
invoiceeEmail1: 'test2@test.com',
// 역발행시 알림문자 전송여부
// - 문자전송지 포인트가 차감되며, 전송실패시 포인트 환불처리됩니다.
invoiceeSMSSendYN: false,
/************************************************************************
* 세금계산서 기재정보
**************************************************************************/
// [필수] 공급가액 합계
supplyCostTotal: '10000',
// [필수] 세액합계
taxTotal: '1000',
// [필수] 합계금액 (공급가액 합계 + 세액 합계)
totalAmount: '11000',
// 기재 상 '일련번호'' 항목
serialNum: '123',
// 기재 상 '현금'' 항목
cash: '',
// 기재 상 '수표' 항목
chkBill: '',
// 기재 상 '어음' 항목
note: '',
// 기재 상 '외상' 항목
credit: '',
// 기재 상 '비고' 항목
remark1: '비고',
remark2: '비고2',
remark3: '비고3',
// 기재 상 '권' 항목, 최대값 32767
kwon: '',
// 기재 상 '호' 항목, 최대값 32767
ho: '',
// 사업자등록증 이미지 첨부여부
businessLicenseYN: false,
// 통장사본 이미지 첨부여부
bankBookYN: false,
/************************************************************************
* 상세항목(품목) 정보
**************************************************************************/
detailList: [
{
serialNum: 1, // 일련번호, 1부터 순차기재
purchaseDT: '20220101', // 거래일자, 형식 : yyyyMMdd
itemName: '품명1',
spec: '규격',
qty: '1', // 수량, 소수점 2자리까지 기재 가능
unitCost: '5000', // 단가, 소수점 2자리까지 기재 가능
supplyCost: '5000', // 공급가액, 소수점 기재불가, 원단위 이하는 절사하여 표현
tax: '500', // 세액, 소수점 기재불가, 원단위 이하는 절사하여 표현
remark: '비고'
},
{
serialNum: 2, // 일련번호, 1부터 순차기재
purchaseDT: '20220101', // 거래일자, 형식 : yyyyMMdd
itemName: '품명2',
spec: '규격',
qty: '1', // 수량, 소수점 2자리까지 기재 가능
unitCost: '5000', // 단가, 소수점 2자리까지 기재 가능
supplyCost: '5000', // 공급가액, 소수점 기재불가, 원단위 이하는 절사하여 표현
tax: '500', // 세액, 소수점 기재불가, 원단위 이하는 절사하여 표현
remark: '비고'
}
],
/************************************************************************
* 수정세금계산서 기재정보
* - 수정세금계산서를 작성하는 경우에만 값을 기재합니다.
* - 수정세금계산서 관련 정보는 연동매뉴얼 또는 개발가이드 링크 참조
* - [참고] 수정세금계산서 작성방법 안내 - http://blog.linkhubcorp.com/650
**************************************************************************/
// [수정세금계산서 발행시 필수] 수정사유코드, 수정사유에 따라 1~6 숫자 기재
modifyCode: '',
// [수정세금계산서 발행시 필수] 당초승인번호 기재
orgNTSConfirmNum: '',
/************************************************************************
* 추가담당자 정보
* - 세금계산서 발행안내 메일을 수신받을 공급받는자 담당자가 다수인 경우
* 추가 담당자 정보를 등록하여 발행안내메일을 다수에게 전송할 수 있습니다. (최대 5명)
**************************************************************************/
// 추가담당자 정보
addContactList: [
{
// 일련번호, 1부터 순차기재
serialNum: 1,
// 담당자명
contactName: '담당자 성명',
// 담당자 메일
email: 'test2@test.com'
},
{
// 일련번호, 1부터 순차기재
serialNum: 2,
// 담당자명
contactName: '담당자 성명 2',
// 담당자 메일
email: 'test3@test.com'
}
]
};
taxinvoiceService.registIssue(testCorpNum, Taxinvoice,
function (result) {
res.render('response', {path: req.path, code: result.code, message: result.message, ntsConfirmNum: result.ntsConfirmNum});
}, function (Error) {
res.render('response', {path: req.path, code: Error.code, message: Error.message});
});
});함수 호출결과 코드와 메시지를 출력하는 "/views/response.ejs" 파일을 추가합니다.
<!DOCTYPE html>
<html>
<head>
<title>Popbill Taxinvoice</title>
</head>
<body>
<div>
<p>Response</p>
<br/>
<fieldset>
<ul>
<li>응답코드 (Response.code) : <%= code %></li>
<li>응답메시지 (Response.message) : <%= message %></li>
<% if (typeof ntsConfirmNum != 'undefined') { %>
<li>국세청승인번호 (Response.ntsConfirmNum) : <%= ntsConfirmNum %></li>
<% } %>
</ul>
</fieldset>
</div>
</body>
</html>4. 결과 확인
함수 호출 반환 결과는 아래와 같습니다.
- 성공 : Response code 로 숫자 1 반환
- 실패 : PopbillException 으로 음의 정수 8자리 숫자값 오류코드와 오류메시지 반환 [오류코드]