링크허브 공식블로그

전자세금계산서 발행마감일 안내 [2019년 7월 귀속분]

링크허브 — Tue, 6 Aug 2019 17:34:46 +0900

안녕하세요. 믿을 수 있는 전자세금계산서 팝빌 입니다.

2019년 7월 귀속분 전자세금계산서 발행마감일은 2019년 8월 12일(월)입니다.

마감일 이후 발행으로 지연발급가산세가 부과되지 않도록 주의하시기 바랍니다.

전자세금계산서의 경우

발급기한이 지나고
공급시기가 속하는 과세기간에 대한
부가가치세 확정신고 기한까지 발행한 경우
지연발급가산세 공급자 1%, 매입자 0.5%

공급시기가 속하는 과세기간에 대한
부가가치세 확정신고 기한 후 발행한 경우
미발급가산세 : 공급자 2%, 매입세액불공제

전자계산서의 경우

발급기한이 지나고
과세기간 말의 다음달 25일까지 발행
지연발급가산세 : 공급자 1%

과세기간 말의 다음달 25일이 지나서 발행
미발급가산세 : 공급자 2%

발행마감일 이후 발행 시
"지연발급 가산세" 및 "미발급가산세"가
부과되지 않도록 주의하여 주시기 바랍니다!

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

팝빌 / T. 1599-7709 / E. popbill@linkhub.co.kr

전자세금계산서 의무발행 대상자 확대 - 발급방법 및 국세청 전송

링크허브 — Fri, 21 Jun 2019 15:52:11 +0900

안녕하세요. 믿을 수 있는 전자세금계산서 팝빌 입니다.

부가가치세는 사업자에게 있어 가장 중요한 세금 중 하나입니다!

부가가치세 신고·납부가 사업자의 매출을 확정하고, 매입세금계산서를 통해 주요 비용을 결정하기 때문인데요. 무엇보다도 부가가치세 신고에 더욱 신경을 써야 하는 이유는 부가가치세 신고에 의해 사업의 매출액이 결정되고, 신고된 매출액은 사업자의 소득세와 법인세를 결정하는 요인이 되기 때문입니다.

부가가치세 신고나 종합소득세 신고 시 납부세액을 줄일 수 있는 방법으로 사업과 관련하여 발생한 매입 거래 시 상대방으로부터 적격증빙을 수취하는 것인데요~ 매입거래를 했을 때 구입처로부터 적격증빙서류를 수취하지 못하면 매입세액 공제를 받을수 없습니다. 세금계산서나 계산서의 경우 중요한 적격증빙들 중 하나입니다.

이번 포스팅에서는 부가가치세나 종합소득세 신고 시 적격증빙 중에 하나인 전자세금계산서를 발행하는 방법에 대해 알아보도록 하겠습니다.

※ 부가가치세나 종합소득세 신고 시 반영되는 적격증빙에는 세금계산서와 계산서, 신용카드매출전표, 현금영수증 등이 있습니다.

[참고] 사업자 세부담을 덜어주는 적격증빙에는 어떤것이 있을까요? : https://blog.naver.com/popbill/221267128462

1. 전자세금계산서 의무발행 대상자

매출액에 관계없이 모든 법인사업자는 전자세금계산서를 발급해야 합니다. 또한 직전연도 사업장별 공급가액 합계가 3억원 이상인 개인사업자도 종이세금계산서 대신 의무적으로 전자세금계산서를 발급해야 합니다.

그리고 다가오는 2019년 7월부터는 과세와 면세의 합계 매출액이 3억원 이상인 개인사업자도 전자세금계산서를 의무적으로 발급해야 합니다.

2. 전자세금계산서 발행 시기

전자세금계산서는 부가가치세법 제15~17조에 따라 재화나 용역을 공급할 때마다 그 공급시기를 작성일자로하여 공급받는자에게 발급해야 하는것이 원칙입니다. 다만 거래처별 월 합계로 발급하는 경우 예외적으로 공급시기가 속하는 달의 다음달 10일까지 발급이 가능합니다.

단, 다음달 10일이 토요일 또는 공휴일인 경우에는 바로 다음 영업일까지 발급이 가능합니다.

3. 전자세금계산서 발행 방법

Step1. 회원 가입 및 로그인

전자세금계산서 서비스 이용을 위한 회원 가입 및 로그인을 진행합니다.

팝빌은 이용중인 시스템(ERP, 솔루션, 판매재고 등)에 세금계산서 기능을 연동할 수 있도록 전자세금계산서 연동 API 서비를 제공하고 있습니다.

팝빌과 연동된 프로그램을 이용하시는 분들께서는 팝빌에 "연동회원"으로 가입해 주시기 바랍니다.

[참고] 팝빌 연동회원 가입 절차 안내 : https://blog.naver.com/popbill/221049135762

Step 2. 공인인증서 등록 및 포인트 충전

전자세금계산서를 발행하기 위해서는 공인인증서로 전자서명을 해야 '전자서명법'에 의거하여 법적인 효력을 갖습니다. 팝빌에서 전자세금계산서를 발급하려면 먼저 사업자 범용 공인인증서나 전자세금계산서용 공인인증서를 발급받아야 합니다. 사용가능한 공인인증서가 없으시다면 하단의 내용을 참고하여 신규로 발급받아 주시기 바랍니다.

[참고] 전자세금계산서용 공인인증서 신규 발급절차 안내 : https://blog.naver.com/popbill/220993308863

팝빌 포인트는 필요한 만큼 충전해서 사용하는 합리적인 종량과금제로, 선(先) 충전 후(後) 차감되는 방식입니다.

[참고] 팝빌 회원 포인트 결제 방법 안내 : https://blog.naver.com/popbill/221131018225

Step 3. 전자세금계산서 발행

1. 과세형태 및 거래처유형 선택
- 세금계산서의 과세형태(과세, 영세, 면세)를 선택하고 거래처유형에서 사업자나 개인 또는 외국인을 선택합니다.

2. 공급받는자의 정보 기재 또는 거래처 불러오기
- 공급받는자의 사업자등록번호, 상호, 성명, 주소, 업태, 종목, 담당자 이메일 주소 등을 기입합니다. 주소록에 저장되어 있는 거래처일 경우 사업자번호을 기재하면 자동으로 불러오기가 됩니다.

3. 작성일자 선택
- 재화나 용역의 공급시기에 맞게 작성일자를 선택합니다. 공급시기가 속하는 다음달 10일 이후 발행 시 지연발급 가산세 및 미발급 가산세 대상이 됩니다.

4. 품목란 기재
- 거래내역에 맞게 날짜, 품목, 수량 및 단가, 공급가액 및 세액, 영수/청구를 기재합니다.

세금계산서의 필수 기재사항이 정확히 기재되었는지 확인 후 '발행' 버튼을 클릭하면 공인인증서 툴킷 창이 뜨게 되는데, 해당 공인인증서의 암호를 입력(전자서명)하면 전자세금계산서 발행이 완료됩니다. 발행된 내역은 [전자세금계산서 > 문서 관리함 > 매출 문서함]에서 조회가 가능합니다.

Step 4. 국세청 전송

전자세금계산서 발행과 동시에 전송이 되는 홈택스와 달리 팝빌은 발행 후 다음날 오후 3시에 자동으로 국세청에 전송하고 있습니다. 익일 전송이 가능하기 때문에 세금계산서가 국세청으로 전송되기 전까지는 별도의 수정세금계산서를 발행하지 않더라도 발행취소가 가능한 장점이 있습니다.

발행 즉시 국세청에 전송을 원하시면 환경설정을 변경해주시기 바랍니다.

[참고] 팝빌 전자세금계산서 국세청전송 설정 안내 : https://blog.naver.com/popbill/221066902146

이상으로 전자세금계산서 발행방법 및 국세청 전송에 대해 알아보았는데요~

종이세금계산서를 대신해 전자세금계산서를 의무적으로 발급해야하는 사업자가 확대되고 있는만큼 이번 포스팅이 해당 사업자분들에게 도움이 되었기를 바라며, 추가적인 문의사항은 팝빌 고객센터(1599-7709)로 연락주시면 친절하고 신속히 상담해드리겠습니다.

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

팝빌 / T. 1599-7709 / E. popbill@linkhub.co.kr

[Node.js] 팝빌 홈택스 현금영수증 조회 API 연동 가이드

링크허브 — Thu, 21 Feb 2019 17:46:40 +0900

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

본 포스팅에서는 Node.js - Express Framework 개발환경에서 고객사들이 팝빌 홈택스 현금영수증 조회 API SDK를 쉽고 빠르게 이용할 수 있도록, 예시를 통하여 연동 설정 방법을 안내드리겠습니다. npm을 이용해 팝빌 SDK 추가 후, 수집요청(RequestJob), 수집결과확인(GetJobState) 함수를 구현하는 순서로 진행하겠습니다.

팝빌 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 htCashbillService = popbill.HTCashbillService();

module.exports = router;

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

2. API 구현

API를 구현하기 전, 홈택스 현금영수증 조회를 위한 함수 프로세스 순서도를 먼저 살펴보시기 바랍니다.

① 수집요청(requestJob), 수집결과확인(getJobState) routes/index.js 파일에 router 함수를 추가합니다.

- 수집결과 조회 (Search API) 함수에 관한 샘플코드는 연동자료실에서 제공되는 Node.js SDK 예제코드 /routes/htcashbill.js 파일의 search() 함수를 참조하시기 바랍니다.

/*
 * 현금영수증 매출/매입 내역 수집을 요청합니다
 * - 홈택스연동 프로세스는 "[홈택스연동(현금영수증) API 연동매뉴얼] >
 *   1.1. 홈택스연동(현금영수증) API 구성" 을 참고하시기 바랍니다.
 * - 수집 요청후 반환받은 작업아이디(JobID)의 유효시간은 1시간 입니다.
 */
router.get('/requestJob', function (req, res, next) {

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

    // 현금영수증 유형, SELL-매출, BUY-매입
    var type = popbill.MgtKeyType.BUY;

    // 시작일자, 날짜형식(yyyyMMdd)
    var SDate = '20180101';

    // 종료일자, 날짜형식(yyyyMMdd)
    var EDate = '20181231';

    htCashbillService.requestJob(testCorpNum, type, SDate, EDate,
        function (jobID) {
            res.render('response', {path: req.path, result: jobID})
        }, function (Error) {
            res.render('error', {path: req.path, code: Error.code, message: Error.message});
        });
});

/*
 * 수집 요청 상태를 확인합니다.
 * - 응답항목 관한 정보는 "[홈택스연동 (현금영수증) API 연동매뉴얼] >
 *   3.1.2. GetJobState(수집 상태 확인)" 을 참고하시기 바랍니다.
 */
router.get('/getJobState', function (req, res, next) {

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

    // 작업아이디
    var jobID = '019010912000000058';

    htCashbillService.getJobState(testCorpNum, jobID,
        function (response) {
            res.render('jobState', {path: req.path, result: response})
        }, function (Error) {
            res.render('error', {path: req.path, code: Error.code, message: Error.message});
        });
});

② 각각의 함수 호출결과 확인을 위해 views/response.ejs, views/jobState.ejs, views/error.ejs 파일을 추가합니다.

views/response.ejs

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
    <p>jobID (작업아이디) : <%=jobID%></p>
</body>
</html>

views/jobState.ejs

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
  <ul>
      <li>jobID (작업아이디) : <%= result.jobID %></li>
      <li>jobState (수집상태) : <%= result.jobState %></li>
      <li>queryType (수집유형) : <%= result.queryType %></li>
      <li>queryDateType (일자유형) : <%= result.queryDateType %></li>
      <li>queryStDate (시작일자) : <%= result.queryStDate %></li>
      <li>queryEnDate (종료일자) : <%= result.queryEnDate %></li>
      <li>errorCode (오류코드) : <%= result.errorCode %></li>
      <li>errorReason (오류메시지) : <%= result.errorReason %></li>
      <li>jobStartDT (작업 시작일시) : <%= result.jobStartDT %></li>
      <li>jobEndDT (작업 종료일시) : <%= result.jobEndDT %></li>
      <li>collectCount (수집개수) : <%= result.collectCount %></li>
      <li>regDT (수집 요청일시) : <%= result.regDT %></li>
  </ul>
</body>
</html>

views/error.ejs  
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
      <p>응답코드 (code) : <%=code%></p>
      <p>응답메시지 (message) : <%=message%></p>
</body>
</html>

③ 각 함수 응답을 확인합니다.

예) 수집요청 (requestJob) 함수호출 성공 처리시 - 작업아이디 (jobID) 반환

예) 수집결과확인 (getJobState) 함수호출 성공 처리시 - 수집상태정보 반환

예) 함수호출 실패 처리시, 응답코드(-로 시작하는 8자리 숫자값), 응답메시지(실패사유) 반환

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

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

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

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

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

[Node.js] 팝빌 홈택스 전자세금계산서 조회 API 연동 가이드

링크허브 — Thu, 21 Feb 2019 17:27:20 +0900

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

본 포스팅에서는 Node.js - Express Framework 개발환경에서 고객사들이 팝빌 홈택스 전자세금계산서 조회 API SDK를 쉽고 빠르게 이용할 수 있도록, 예시를 통하여 연동 설정 방법을 안내드리겠습니다. npm을 이용해 팝빌 SDK 추가 후, 수집요청(RequestJob), 수집결과확인(GetJobState) 함수를 구현하는 순서로 진행하겠습니다.

팝빌 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 htTaxinvoiceService = popbill.HTTaxinvoiceService();

module.exports = router;

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

2. API 구현

API를 구현하기 전, 홈택스 전자세금계산서 조회를 위한 함수 프로세스 순서도를 먼저 살펴보시기 바랍니다.

① 수집요청(requestJob), 수집결과확인(getJobState) routes/index.js 파일에 router 함수를 추가합니다.

- 수집결과 조회 (Search API) 함수에 관한 샘플코드는 연동자료실에서 제공되는 Node.js SDK 예제코드 /routes/httaxinvoice.js 파일의 search() 함수를 참조하시기 바랍니다.

/*
 * 전자세금계산서 매출/매입 내역 수집을 요청합니다
 * - 홈택스연동 프로세스는 "[홈택스연동(전자세금계산서계산서) API 연동매뉴얼] >
 *   1.1. 홈택스연동(전자세금계산서) API 구성" 을 참고하시기 바랍니다.
 * - 수집 요청후 반환받은 작업아이디(JobID)의 유효시간은 1시간 입니다.
 */
router.get('/requestJob', function (req, res, next) {

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

    // 세금계산서 유형, SELL-매출, BUY-매입, TRUSTEE-수탁
    var type = popbill.MgtKeyType.SELL;

    // 검색일자유형, W-작성일자, R-등록일자, I-발행일자
    var DType = 'W';

    // 시작일자, 날짜형식(yyyyMMdd)
    var SDate = '20181201';

    // 종료일자, 날짜형식(yyyyMMdd)
    var EDate = '20190109';

    htTaxinvoiceService.requestJob(testCorpNum, type, DType, SDate, EDate,
        function (jobID) {
            res.render('response', {path: req.path, jobID: jobID})
        }, function (Error) {
            res.render('error', {path: req.path, code: Error.code, message: Error.message});
        });
});

/*
 * 수집 요청 상태를 확인합니다.
 * - 응답항목 관한 정보는 "[홈택스연동 (전자세금계산서계산서) API 연동매뉴얼] >
 *   3.1.2. GetJobState(수집 상태 확인)" 을 참고하시기 바랍니다.
 */
router.get('/getJobState', function (req, res, next) {

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

    // 작업아이디
    var jobID = '019010912000000057';

    htTaxinvoiceService.getJobState(testCorpNum, jobID,
        function (response) {
            res.render('jobState', {path: req.path, result: response})
        }, function (Error) {
            res.render('error', {path: req.path, code: Error.code, message: Error.message});
        });
});

② 각각의 함수 호출결과 확인을 위해 views/response.ejs, views/jobState.ejs, views/error.ejs 파일을 추가합니다.

views/response.ejs

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
    <p>jobID (작업아이디) : <%=jobID%></p>
</body>
</html>

views/jobState.ejs

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
  <ul>
      <li>jobID (작업아이디) : <%= result.jobID %></li>
      <li>jobState (수집상태) : <%= result.jobState %></li>
      <li>queryType (수집유형) : <%= result.queryType %></li>
      <li>queryDateType (일자유형) : <%= result.queryDateType %></li>
      <li>queryStDate (시작일자) : <%= result.queryStDate %></li>
      <li>queryEnDate (종료일자) : <%= result.queryEnDate %></li>
      <li>errorCode (오류코드) : <%= result.errorCode %></li>
      <li>errorReason (오류메시지) : <%= result.errorReason %></li>
      <li>jobStartDT (작업 시작일시) : <%= result.jobStartDT %></li>
      <li>jobEndDT (작업 종료일시) : <%= result.jobEndDT %></li>
      <li>collectCount (수집개수) : <%= result.collectCount %></li>
      <li>regDT (수집 요청일시) : <%= result.regDT %></li>
  </ul>
</body>
</html>

views/error.ejs  
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
      <p>응답코드 (code) : <%=code%></p>
      <p>응답메시지 (message) : <%=message%></p>
</body>
</html>

③ 각가의 함수 응답을 확인합니다.

예) 수집요청 (requestJob) 함수호출 성공 처리시 - 작업아이디 (jobID) 반환

예) 수집결과확인 (getJobState) 함수호출 성공 처리시 - 수집상태정보 반환

예) 함수호출 실패 처리시, 응답코드(-로 시작하는 8자리 숫자값), 응답메시지(실패사유) 반환

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

지금까지 Node.js - Express Framework 개발환경에서 홈택스 전자세금계산서 조회 API를 연동하는 방법에 대해 안내해 드렸는데, 내용에 대한 추가적인 문의가 있으면 기술지원센터로 편하게 연락 주시기 바랍니다.

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

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

[Node.js] 팝빌 휴폐업조회 API 연동 가이드

링크허브 — Thu, 21 Feb 2019 16:36:52 +0900

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

본 포스팅에서는 Node.js - Express Framework 개발환경에서 고객사들이 팝빌 휴폐업조회 API SDK를 쉽고 빠르게 이용할 수 있도록, 예시를 통하여 연동 설정 방법을 안내드리겠습니다. npm을 이용해 팝빌 SDK 추가 후, 사업자 휴폐업조회 (CheckCorpNum) 함수를 구현하는 순서로 진행하겠습니다.

팝빌 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 closedownService = popbill.ClosedownService();

module.exports = router;

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

2. API 구현

① 휴폐업조회 함수 호출을 위해 routes/index.js 파일에 router 함수를 추가합니다.

router.get('/checkCorpNum', function (req, res, next) {

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

  // 조회할 사업자번호
  var checkCorpNum = '6798700433';

  closedownService.checkCorpNum(testCorpNum, checkCorpNum,
      function (CorpState) {
          res.render('response', {path: req.path, result: CorpState});
      }, function (Error) {
          res.render('error', {path: req.path, code: Error.code, message: Error.message});
  });
});

② 함수 호출결과 확인을 위해 views/response.ejs 파일을 추가합니다.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
    <p>type : null-미확인, 1-부가가치세 일반과세자, 2-부가가치세 면세과세자, 3-부가가치세 간이과세자, 4-비영리법인 또는 국가기관</p>
    <p>state : null-미확인, 0-미등록, 1-사업중, 2-폐업, 3-휴업 </p>
    <br/>
    <p>corpNum (사업자번호) : <%=result.corpNum%></p>
    <p>state (휴폐업상태) : <%=result.state%></p>
    <p>stateDate (휴폐업일자) : <%=result.stateDate%></p>
    <p>type (사업자 과세유형) : <%=result.type%></p>
    <p>typeDate (과세유형 전환일자) : <%=result.typeDate%></p>
    <p>checkDate (국세청확인일자) : <%=result.checkDate%></p>
</body>
</html>

오류코드, 메시지 확인을 위해 views/error.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

지금까지 Node.js - Express Framework 개발환경에서 휴폐업조회 API를 연동하는 방법에 대해 안내해 드렸는데, 내용에 대한 추가적인 문의가 있으면 기술지원센터로 편하게 연락 주시기 바랍니다.

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

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

[Node.js] 팝빌 카카오톡 API 연동 가이드

링크허브 — Thu, 21 Feb 2019 16:19:17 +0900

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

본 포스팅에서는 Node.js - Express Framework 개발환경에서 고객사들이 팝빌 카카오톡 API SDK를 쉽고 빠르게 이용할 수 있도록, 예시를 통하여 연동 설정 방법을 안내드리겠습니다. npm을 이용해 팝빌 SDK 추가 후, 알림톡 전송 (SendATS) 함수를 구현하는 순서로 진행하겠습니다.

팝빌 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 kakaoService = popbill.KakaoService();

module.exports = router;

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

2. API 구현

① 알림톡 전송 함수 호출을 위해 routes/index.js 파일에 router 함수를 추가합니다.

router.get('/sendATS', function (req, res, next) {

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

    // 알림톡 템플릿코드
    // 승인된 알림톡 템플릿 코드는 ListATStemplate API, GetATSTemplateMgtURL API, 혹은 팝빌사이트에서 확인이 가능합니다.
    var templateCode = '018110000047';

    // 발신번호 (팝빌에 등록된 발신번호만 이용가능)
    var snd = '070-4304-2991';

    // 알림톡 내용 (최대 1000자)
    var content = '테스트 템플릿 입니다.';

    // 대체문자 내용 (최대 2000byte)
    var altContent = '알림톡 대체 문자';

    // 대체문자 유형 [공백-미전송, C-알림톡내용, A-대체문자내용]
    var altSendType = 'A';

    // 예약일시 (작성일시 : yyyyMMddHHmmss)
    var sndDT = '';

    // 수신번호
    var receiver = '010111222';

    // 수신자 이름
    var receiverName = 'partner';

    // 팝빌회원 아이디
    var UserID = 'testkorea';

    // 전송요청번호
    // 파트너가 전송 건에 대해 관리번호를 구성하여 관리하는 경우 사용.
    // 1~36자리로 구성. 영문, 숫자, 하이픈(-), 언더바(_)를 조합하여 팝빌 회원별로 중복되지 않도록 할당.
    var requestNum = "";

    kakaoService.sendATS_one(testCorpNum, templateCode, snd, content, altContent, altSendType, sndDT, receiver, receiverName, UserID, requestNum,
        function (receiptNum) {
            res.render('response', {path: req.path, receiptNum: receiptNum});
        }, function (Error) {
            res.render('error', {path: req.path, code: Error.code, message: Error.message});
        });
});

② 함수 호출결과 확인을 위해 views/response.ejs 파일을 추가합니다.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
      <p>receiptNum (접수번호) : <%=receiptNum%></p>
</body>
</html>

오류코드, 메시지 확인을 위해 views/error.ejs 파일을 추가합니다.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
      <p>응답코드 (code) : <%=code%></p>
      <p>응답메시지 (message) : <%=message%></p>
</body>
</html>

③ 알림톡 전송요청 함수 응답을 확인합니다.

예) 함수호출 성공 처리시, receiptNum(접수번호) 반환

예) 함수호출 실패 처리시, 응답코드(-로 시작하는 8자리 숫자값), 응답메시지(실패사유) 반환

④ 알림톡 전송 결과는 getMessages 함수 또는 팝빌 개발용(test.popbill.com) 사이트에서 확인할 수 있습니다.

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

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

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

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

[Node.js] 팝빌 팩스 API 연동 가이드

링크허브 — Thu, 21 Feb 2019 15:56:37 +0900

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

본 포스팅에서는 Node.js - Express Framework 개발환경에서 고객사들이 팝빌 팩스 API SDK를 쉽고 빠르게 이용할 수 있도록, 예시를 통하여 연동 설정 방법을 안내드리겠습니다. npm을 이용해 팝빌 SDK 추가 후, 팩스 전송(SendFAX) 함수를 구현하는 순서로 진행하겠습니다.

팝빌 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 faxService = popbill.FaxService();

module.exports = router;

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

2. API 구현

① 팩스전송 함수 호출을 위해 routes/index.js 파일에 router 함수를 추가합니다.

router.get('/sendFAX', function (req, res, next) {

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

    // 발신번호
    var senderNum = '07043042991';

    // 발신자명
    var senderName = '발신자명';

    // 광고팩스 전송여부
    var adsYN = false;

    // 수신팩스번호
    var receiveNum = '070111222';

    // 수신자명
    var receiveName = '수신자명';

    // 파일경로 배열, 전송개수 촤대 20개
    var filePaths = ['/Users/John/Desktop/test.jpg'];

    // 팩스제목
    var title = '팩스전송';

    // 예약전송일시 날짜형식(yyyyMMddHHmmss), 미기재시 즉시전송
    var reserveDT = '';

    // 전송요청번호
    // 파트너가 전송 건에 대해 관리번호를 구성하여 관리하는 경우 사용.
    // 1~36자리로 구성. 영문, 숫자, 하이픈(-), 언더바(_)를 조합하여 팝빌 회원별로 중복되지 않도록 할당.
    var requestNum = "";

    faxService.sendFax(testCorpNum, senderNum, receiveNum, receiveName, filePaths, reserveDT, senderName, adsYN, title, requestNum,
        function (receiptNum) {
            res.render('response', {path: req.path, result: receiptNum});
        }, function (Error) {
            res.render('error', {path: req.path, code: Error.code, message: Error.message});
        });
});

② 함수 호출결과 확인을 위해 views/response.ejs 파일을 추가합니다.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
      <p>receiptNum (접수번호) : <%=receiptNum%></p>
</body>
</html>

오류코드, 메시지 확인을 위해 views/error.ejs 파일을 추가합니다.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
      <p>응답코드 (code) : <%=code%></p>
      <p>응답메시지 (message) : <%=message%></p>
</body>
</html>

③ 팩스 전송요청 함수 응답을 확인합니다.

예) 함수호출 성공 처리시, receiptNum(접수번호) 반환

예) 함수호출 실패 처리시, 응답코드(-로 시작하는 8자리 숫자값), 응답메시지(실패사유) 반환

④ 팩스 결과는 getFaxResult 함수 또는 팝빌 개발용(test.popbill.com) 사이트에서 확인할 수 있습니다.

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

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

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

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

[Node.js] 팝빌 문자 API 연동 가이드

링크허브 — Thu, 21 Feb 2019 15:36:02 +0900

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

본 포스팅에서는 Node.js - Express Framework 개발환경에서 고객사들이 팝빌 문자 API SDK를 쉽고 빠르게 이용할 수 있도록, 예시를 통하여 연동 설정 방법을 안내드리겠습니다. npm을 이용해 팝빌 SDK 추가 후, 단문 메시지 전송(SendSMS) 함수를 구현하는 순서로 진행하겠습니다.

팝빌 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 messageService = popbill.MessageService();

module.exports = router;

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

2. API 구현

① 단문메시지 전송함수 호출을 위해 routes/index.js 파일에 router 함수를 추가합니다.

/*
 * SMS(단문)를 전송합니다.
 *  - 메시지 내용이 90Byte 초과시 메시지 내용은 자동으로 제거됩니다.
 */
router.get('/sendSMS', function (req, res, next) {

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

    // 발신번호
    var sendNum = '07043042991';

    // 발신자명
    var sendName = '발신자명';

    // 수신번호
    var receiveNum = '000111222';

    // 수신자명
    var receiveName = '수신자명';

    // 메시지 내용, 90Byte 초과시 길이가 조정되어 전송
    var contents = 'SMS 단건전송 메시지 테스트';

    // 예약전송일시(yyyyMMddHHmmss), 미기재시 즉시전송
    var reserveDT = '';

    // 광고문자 전송여부
    var adsYN = false;

    // 전송요청번호
    // 파트너가 전송 건에 대해 관리번호를 구성하여 관리하는 경우 사용.
    // 1~36자리로 구성. 영문, 숫자, 하이픈(-), 언더바(_)를 조합하여 팝빌 회원별로 중복되지 않도록 할당.
    var requestNum = "";

    messageService.sendSMS(testCorpNum, sendNum, receiveNum, receiveName, contents, reserveDT, adsYN, sendName, requestNum,
        function (receiptNum) {
            res.render('response', {path: req.path, result: receiptNum});
        }, function (Error) {
            res.render('error', {path: req.path, code: Error.code, message: Error.message});
        });
});

② 함수 호출결과 확인을 위해 views/response.ejs 파일을 추가합니다.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
      <p>receiptNum (접수번호) : <%=receiptNum%></p>
</body>
</html>

오류코드, 메시지 확인을 위해 views/error.ejs 파일을 추가합니다.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Response</title>
</head>
<body>
      <p>응답코드 (code) : <%=code%></p>
      <p>응답메시지 (message) : <%=message%></p>
</body>
</html>

③ 문자 전송요청 함수 응답을 확인합니다.

예) 함수호출 성공 처리시, receiptNum(접수번호) 반환

예) 함수호출 실패 처리시, 응답코드(-로 시작하는 8자리 숫자값), 응답메시지(실패사유) 반환

④ 문자전송 결과는 getMessages 함수 또는 팝빌 개발용(test.popbill.com) 사이트에서 확인할 수 있습니다.

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

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

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

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

[Node.js] 팝빌 전자명세서 API 연동 가이드

링크허브 — Thu, 21 Feb 2019 14:54:31 +0900

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

본 포스팅에서는 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 함수를 추가합니다.

/*
 * 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});
        });
});

② 함수 호출결과 확인을 위해 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

지금까지 Node.js - Express Framework 개발환경에서 전자명세서 API를 연동하는 방법에 대해 안내해 드렸는데, 내용에 대한 추가적인 문의가 있으면 기술지원센터로 편하게 연락 주시기 바랍니다.

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

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

[Java - Spring] 팝빌 홈택스 현금영수증 조회 API 연동 가이드

링크허브 — Thu, 21 Feb 2019 13:39:28 +0900

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

본 포스팅에서는 Java - Spring 개발환경에서 고객사들이 팝빌 홈택스 현금영수증 조회 API SDK를 쉽고 빠르게 이용할 수 있도록, 예시를 이용하여 연동 설정 방법을 안내드리겠습니다. 먼저, Maven을 이용해 팝빌 SDK를 추가한 후 수집요청(RequestJob), 수집상태확인(GetJobState) 함수를 구현하는 순서로 진행하겠습니다.

팝빌 SDK는 JDK V1.6 개발환경에 최적화 되어 있으며, API 호출과 응답의 메시지 인코딩은 "UTF-8 Character-Set"을 지원합니다.

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

아래 설명하는 예시는 [ JDK v1.6 | Tomcat v7 | STS v3.6.4 ] 기준으로 작성되어 있어, 이용 중이신 개발환경과 차이가 있을 수 있는 점 감안해 주시기 바랍니다.

1. Popbill SDK 추가

① Maven 업데이트를 위해 "pom.xml" 파일에 팝빌 SDK Dependency를 추가하고 메이븐 업데이트를 진행합니다.

<dependency>
	<groupId>kr.co.linkhub</groupId>
	<artifactId>popbill-sdk</artifactId>
	<version>1.20.0</version>
</dependency>

② 홈택스 현금영수증 조회 서비스 클래스를 빈으로 등록하기 위해 아래코드를 참조하여 "servlet-context.xml" 파일을 수정합니다.

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/mvc"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:beans="http://www.springframework.org/schema/beans"
            xmlns:context="http://www.springframework.org/schema/context"
            xmlns:util="http://www.springframework.org/schema/util"
            xsi:schemaLocation="http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">

<!-- DispatcherServlet Context: defines this servlet's request-processing infrastructure -->
<!-- Enables the Spring MVC @Controller programming model -->
<annotation-driven />

<!-- Handles HTTP GET requests for /resources/** by efficiently serving up static resources in the ${webappRoot}/resources directory -->
<resources mapping="/resources/**" location="/resources/" />

<!-- Resolves views selected for rendering by @Controllers to .jsp resources in the /WEB-INF/views directory -->
<beans:bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
<beans:property name="prefix" value="/WEB-INF/views/" />
<beans:property name="suffix" value=".jsp" />
</beans:bean>
<context:component-scan base-package="kr.test.popbill" />

 <util:properties id="EXAMPLE_CONFIG">

       <!-- 링크아이디 -->
      <beans:prop key="LinkID">TESTER</beans:prop>

       <!-- 비밀키 -->
      <beans:prop key="SecretKey">SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I=</beans:prop>

       <!-- 연동환경 설정값 true(개발용), false(상업용) -->
      <beans:prop key="IsTest">true</beans:prop>

       <!-- 인증토큰 아이피 제한 기능 사용여부 권장(true) -->
      <beans:prop key="IsIPRestrictOnOff">true</beans:prop>
  </util:properties>

  <beans:beans>

          <!-- 홈택스 현금영수증 조회 Service Implementation Bean registration.  -->
     <beans:bean id="htCashbillService" class="com.popbill.api.hometax.HTCashbillServiceImp">
         <beans:property name="linkID" value="#{EXAMPLE_CONFIG.LinkID}"/>
         <beans:property name="secretKey" value="#{EXAMPLE_CONFIG.SecretKey}"/>
         <beans:property name="test" value="#{EXAMPLE_CONFIG.IsTest}"/>
         <beans:property name="IPRestrictOnOff" value="#{EXAMPLE_CONFIG.IsIPRestrictOnOff}"/>
     </beans:bean>

  </beans:beans>

</beans:beans>

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

2. API 구현

API를 구현하기 전, 홈택스 현금영수증 조회를 위한 함수 프로세스 순서도를 먼저 살펴보시기 바랍니다.

① 수집작업 요청 (RequestJob), 작업상태확인(GetJobState) 함수를 테스트하기 위해 TaskController.java 를 생성하고 GET Request URL을 처리하는 코드를 추가합니다.

- 예제코드를 참조하여 @Controller 어노테이션 과 홈택스 현금영수증 서비스 빈 객체주입을 위한 @Autowired 어노테이션을 추가합니다.

- Search API 에 관한 예제는 제공되는 SpringMVC SDK 예제코드 /com.popbill.example/HTCashbillExample.java 에 선언된 Search() 함수를 참조하시기 바랍니다.

- RequestJob 호출시 반환되는 JobID를 GetJobState 함수 파라미터로 기재하여 호출합니다.

package kr.test.popbill;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import com.popbill.api.HTCashbillService;
import com.popbill.api.PopbillException;
import com.popbill.api.hometax.HTCashbillJobState;
import com.popbill.api.hometax.QueryType;

@Controller
public class TaskController {

// 팝빌 홈택스 현금영수증 조회 서비스 빈 주입
@Autowired
   private HTCashbillService htCashbillService;

@RequestMapping(value = "requestJob", method = RequestMethod.GET)
   public String requestJob(Model m) {

       /*
        * 현금영수증 매출/매입 내역 수집을 요청합니다
        * - 홈택스연동 프로세스는 "[홈택스연동(현금영수증) API 연동매뉴얼] >
        *   1.1. 홈택스연동(현금영수증) API 구성" 을 참고하시기 바랍니다.
        * - 수집 요청후 반환받은 작업아이디(JobID)의 유효시간은 1시간 입니다.
        */

// 팝빌회원 사업자번호
String testCorpNum = "1234567890";

       // 현금영수증 유형, SELL-매출, BUY-매입
       QueryType TIType = QueryType.SELL;

       // 시작일자, 표시형식(yyyyMMdd)
       String SDate = "20181201";

       // 종료일자, 표시형식(yyyyMMdd)
       String EDate = "20190104";

       try {
           String jobID = htCashbillService.requestJob(testCorpNum, TIType, SDate, EDate);
           m.addAttribute("JobID", jobID);
       } catch (PopbillException e) {
           m.addAttribute("Response", e);
       }
       return "response";
   }
   @RequestMapping(value = "getJobState", method = RequestMethod.GET)
   public String getJobState(Model m) {

       /*
        * 수집 요청 상태를 확인합니다.
        * - 응답항목 관한 정보는 "[홈택스연동 (현금영수증) API 연동매뉴얼] >
        *   3.1.2. GetJobState(수집 상태 확인)" 을 참고하시기 바랍니다.
        */
  
       // 팝빌회원 사업자번호
       String testCorpNum = "1234567890";

       // 수집요청(requestJob)시 반환받은 작업아이디
       String jobID = "019010415000000005";

       try {
           HTCashbillJobState jobState = htCashbillService.getJobState(testCorpNum, jobID);
           m.addAttribute("JobState", jobState);
       } catch (PopbillException e) {
           m.addAttribute("Response", e);
       }
       return "response";
   }
}

② API 호출결과 출력을 위해 "src/main/webapp/WEB-INF/views/response.jsp" 페이지를 추가합니다.

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<%@ page language="java" contentType="text/html; charset=utf-8" pageEncoding="utf-8"%>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Response </title>
</head>
<body>
<c:if test="${JobID != null}">
<p>작업아이디 (JobID) : ${JobID}</p>
</c:if>

<c:if test="${JobState != null}">
<p>JobID (작업아이디) : ${JobState.jobID}</p>
<p>jobState (수집상태) : ${JobState.jobState}</p>
<p>queryType (수집유형) : ${JobState.queryType}</p>
<p>queryDateType (일자유형) : ${JobState.queryDateType}</p>
<p>queryStDate (시작일자) : ${JobState.queryStDate}</p>
<p>queryEnDate (종료일자) : ${JobState.queryEnDate}</p>
<p>errorCode (오류코드) : ${JobState.errorCode}</p>
<p>jobStartDT (작업 시작일시) : ${JobState.jobStartDT}</p>
<p>jobEndDT (작업 종료일시) : ${JobState.jobEndDT}</p>
<p>collectCount (수집개수) : ${JobState.collectCount}</p>
<p>regDT (수집 요청일시) : ${JobState.regDT}</p>
</c:if>

<c:if test="${Response != null}">
<p>Response.code : ${Response.code}</p>
<p>Response.message : ${Response.message}</p>
</c:if>
</body>
</html>

③ 함수 호출결과를 확인합니다.

예) 수집요청 (RequestJob) 함수호출 성공처리 - 작업아이디(JobID) 반환

예) 수집결과확인 (GetJobState) 함수호출 성공처리

예) 함수호출 실패처리 - 오류코드(-로 시작하는 8자리 숫자값), 오류메시지(사유에 대한 설명) 반환

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

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

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

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