안녕하세요. 고객의 가치를 연결하는 비즈니스 파트너 링크허브 입니다.
본 포스팅에서는 Node.js - Express Framework 개발환경에서 고객사들이 팝빌 전자명세서 API SDK 를 쉽고 빠르게 이용할 수 있도록, 예시를 통하여 연동 설정 방법을 안내드리겠습니다. npm을 이용해 팝빌 SDK 추가 후, 즉시발행(RegisIssue) 함수를 구현하는 순서로 진행하겠습니다.
팝빌 SDK는 Node.js V0.10.0 이상 모든 개발환경을 지원하며, 통신을 위한 별도 프로그램 설치가 필요하지 않습니다.
"팝빌은 링크허브에서 자체 개발하고 직접 운영하는 전자명세서 서비스 Brand Name 입니다."
다음 개발환경은 [ Node.js V8.9.4 | Express V4.13.1 ] 기준으로 작성되어 있어, 이용 중인 개발환경과 차이가 있을 수 있는 점 감안해 주시기 바랍니다.
1. 팝빌 SDK 추가
① 팝빌 모듈을 추가하기 위해 "package.json" 파일의 dependencies 항목에 아래 코드를 추가 한 후 npm 패키지 설치를 진행합니다.
{
"name": "node_popbill",
"version": "0.0.0",
"private": true,
"scripts": {
"start": "node ./bin/www"
},
"dependencies": {
"body-parser": "~1.13.2",
"cookie-parser": "~1.3.5",
"debug": "~2.2.0",
"express": "~4.13.1",
"jade": "~1.11.0",
"morgan": "~1.6.1",
"serve-favicon": "~2.3.0",
"popbill": "1.12.1"
}
}
$ npm install
② routes/index.js 파일에 팝빌 API 호출을 위한 인증정보를 할당하고 전자명세서 서비스 객체를 생성 합니다.
var express = require('express');
var router = express.Router();
var popbill = require('popbill');
/*
* 팝빌 서비스 연동환경 초기화
*/
popbill.config({
// 링크아이디
LinkID: 'TESTER',
// 비밀키
SecretKey: 'SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I=',
// 연동환경 설정값, 개발용(true), 상업용(false)
IsTest: true,
defaultErrorHandler: function (Error) {
console.log('Error Occur : [' + Error.code + '] ' + Error.message);
}
});
/*
* 전자명세서 API 서비스 클래스 생성
*/
var statementService = popbill.StatementService();
module.exports = router;
링크아이디(LinkID)와 비밀키(SecretKey) 값을 변경하시기 바랍니다.
2. API 구현 ① 전자명세서 발행함수 호출을 위해 routes/index.js 파일에 router 함수를 추가합니다.
RegistIssue API 열기 RegistIssue API 접기
/*
* 1건의 전자명세서를 즉시발행 처리합니다.
*/
router.get('/registIssue', function (req, res, next) {
// 팝빌회원 사업자번호, '-' 제외 10자리
var testCorpNum = '1234567890';
// 명세서 코드 - 121(거래명세서), 122(청구서), 123(견적서), 124(발주서), 125(입금표), 126(영수증)
var ItemCode = 121;
// 문서관리번호, 1~24자리 영문, 숫자, '-', '_' 조합으로 구성, 사업자별로 중복되지 않도록 생성
var MgtKey = '20190109-001';
// 전자명세서 정보
var statement = {
// [필수] 기재상 작성일자, 날짜형식(yyyyMMdd)
writeDate: '20190109',
// [필수] 영수, 청구 중 기재
purposeType: '영수',
// [필수] 과세형태, 과세, 영세, 면세 중 기재
taxType: '과세',
// 맞춤양식코드, 미기재시 기본양식으로 작성
formCode: '',
// [필수] 명세서 코드
itemCode: ItemCode,
// [필수] 문서관리번호
mgtKey: MgtKey,
/*************************************************************************
* 발신자 정보
**************************************************************************/
// 발신자 사업자번호
senderCorpNum: testCorpNum,
// 발신자 상호
senderCorpName: '발신자 상호',
// 발신자 주소
senderAddr: '발신자 주소',
// 발신자 대표자 성명
senderCEOName: '발신자 대표자 성명',
// 종사업장 식별번호, 필요시기재, 형식은 숫자 4자리
senderTaxRegID: '',
// 발신자 종목
senderBizClass: '종목',
// 발신자 업태
senderBizType: '업태',
// 발신자 담당자명
senderContactName: '담당자명',
// 발신자 메일주소
senderEmail: 'test@test.com',
// 발신자 연락처
senderTEL: '070-4304-2991',
// 발신자 휴대폰번호
senderHP: '000-111-222',
/*************************************************************************
* 수신자 정보
**************************************************************************/
// 수신자 사업자번호
receiverCorpNum: '8888888888',
// 수신자 상호
receiverCorpName: '수신자상호',
// 수신자 대표자 성명
receiverCEOName: '수신자 대표자 성명',
// 수신자 주소
receiverAddr: '수신자 주소',
// 수신자 종사업장 식별번호, 필요시 기재
recieverTaxRegID: '',
// 수신자 종목
receiverBizClass: '종목',
// 수신자 업태
receiverBizType: '업태',
// 수신자 담당자명
receiverContactName: '수신자 담당자 성명',
// 수신자 메일주소
receiverEmail: 'test@test.com',
// 수신자 연락처
receiverTEL: '070-1111-2222',
// 수신자 휴대폰 번호
receiverHP: '000111222',
/*************************************************************************
* 전자명세서 기재정보
**************************************************************************/
// [필수] 공급가액 합계
supplyCostTotal: '20000',
// [필수] 세액 합계
taxTotal: '2000',
// [필수] 합계금액 (공급가액 합계+ 세액 합계)
totalAmount: '22000',
// 기재 상 '일련번호' 항목
serialNum: '1',
// 기재 상 '비고' 항목
remark1: '비고1',
remark2: '비고2',
remark3: '비고3',
// 사업자등록증 이미지 첨부 여부
businessLicenseYN: false,
// 통장사본 이미지 첨부 여부
bankBookYN: false,
/*************************************************************************
* 상세9항목(품목) 정보
**************************************************************************/
detailList: [
{
serialNum: 1, // 품목 일련번호 1부터 순차기재
itemName: '품명',
purchaseDT: '20190109', // 구매일자
qty: '1', // 수량
unitCost: '10000', // 단가
spec: '규격', // 규격
supplyCost: '10000', // 공급가액
tax: '1000', // 세액
remark: '비고'
},
{
serialNum: 2, // 품목 일련번호 1부터 순차기재
itemName: '품명2',
purchaseDT: '20190109', // 구매일자
qty: '1', // 수량
unitCost: '10000', // 단가
spec: '규격', // 규격
supplyCost: '10000', // 공급가액
tax: '1000', // 세액
remark: '비고'
}
],
/*************************************************************************
* 전자명세서 추가속성
* - 추가속성에 관한 자세한 사항은 "[전자명세서 API 연동매뉴얼] >
* 5.2. 기본양식 추가속성 테이블"을 참조하시기 바랍니다.
**************************************************************************/
propertyBag: {
Balance: '2000', // 전잔액
Deposit: '500', // 입금액
CBalance: '2500' // 현잔액
}
};
statementService.registIssue(testCorpNum, statement,
function (result) {
res.render('response', {path: req.path, code: result.code, message: result.message});
}, function (Error) {
res.render('response', {path: req.path, code: Error.code, message: Error.message});
});
});
RegistIssue API 접기
② 함수 호출결과 확인을 위해 views/response.ejs 파일을 추가합니다.
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Response</title>
</head>
<body>
<p>응답코드(code) : <%=code%></p>
<p>응답메시지(message) : <%=message%></p>
</body>
</html>
③ 전자명세서 발행함수 호출 결과를 확인합니다.
예) 함수호출 성공 처리시
예) 함수호출 실패 처리시, 응답코드(-로 시작하는 8자리 숫자값), 응답메시지(실패사유) 반환
④ 발행된 전자명세서는 팝빌 개발용(test.popbill.com) 사이트에서 확인할 수 있습니다.
[참고] 팝빌 연동 개발을 위한 테스트베드(개발용) 안내 - https://linkhub.tistory.com/91
팝빌에서 제공하는 다양한 API는 동일한 컨셉으로 개발되어 있어, 하나의 서비스를 이용한 경험이 있으면 다른 서비스들도 유사한 방법으로 빠르게 연동이 가능하니 많은 이용 부탁드립니다.
지금까지 Node.js - Express Framework 개발환경에서 전자명세서 API를 연동하는 방법에 대해 안내해 드렸는데, 내용에 대한 추가적인 문의가 있으면 기술지원센터로 편하게 연락 주시기 바랍니다.
고객사의 편의를 위하여 이메일, 전화 등 다양한 채널을 열어놓고 있으니 언제든지 연락 주시기 바랍니다.
기술지원센터 / T. 1600-9854 / E. code@linkhub.co.kr
