[Java - Spring] 팝빌 현금영수증 API 연동 가이드

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

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

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

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

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

1. Popbill SDK 추가

---

① "pom.xml" 파일에 팝빌 SDK 라이브러리를 추가합니다. 

<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="com.popbill.example" />

 <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="cashbillService" class="com.popbill.api.cashbill.CashbillServiceImp">
          <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 구현

---

① 현금영수증 즉시발행(RegistIssue) 함수를 테스트하기 위해 CashbillServiceExample.java 를 생성하고  GET Request URL 을 처리하는 코드를 추가합니다. 

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

package com.popbill.example;

import com.popbill.api.CashbillService;
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.PopbillException;
import com.popbill.api.Response;
import com.popbill.api.cashbill.Cashbill;

@Controller
public class CashbillServiceExample {

    // 현금영수증 빈 객체 Autowired 설정
    @Autowired
    private CashbillService cashbillService;

    // http request로 들어오는 url을 특정 메소드로 연결
    @RequestMapping(value = "registIssue", method = RequestMethod.GET)
    public String registIssue(Model m) {

        // 팝빌 연동회원 사업자번호
        String corpNum = "1234567890";

        // 현금영수증 정보 객체
        Cashbill cashbill = new Cashbill();

        // 문서관리번호, 최대 24자리, 영문, 숫자 '-', '_'로 구성
        cashbill.setMgtKey("20190221-A");

        // 문서형태, {승인거래, 취소거래} 중 기재
        cashbill.setTradeType("승인거래");

        // 취소거래시 기재, 원본 현금영수증 국세청 승인번호 - getInfo API를 통해 confirmNum 값 기재
        cashbill.setOrgConfirmNum("");

        // 취소거래시 기재, 원본 현금영수증 거래일자 - getInfo API를 통해 tradeDate 값 기재
        cashbill.setOrgTradeDate("");

        // 과세형태, {과세, 비과세} 중 기재
        cashbill.setTaxationType("과세");

        // 거래처 식별번호, 거래유형에 따라 작성
        // 소득공제용 - 주민등록/휴대폰/카드번호 기재가능
        // 지출증빙용 - 사업자번호/주민등록/휴대폰/카드번호 기재가능
        cashbill.setIdentityNum("0101112222");

        // 거래구분, {소득공제용, 지출증빙용} 중 기재
        cashbill.setTradeUsage("소득공제용");

        // 거래유형, {읿반, 도서공연, 대중교통} 중 기재
        cashbill.setTradeOpt("일반");

        // 공급가액, 숫자만 가능
        cashbill.setSupplyCost("10000");

        // 부가세, 숫자만 가능
        cashbill.setTax("1000");

        // 봉사료, 숫자만 가능
        cashbill.setServiceFee("0");

        // 합계금액, 숫자만 가능, 봉사료 + 공급가액 + 부가세
        cashbill.setTotalAmount("11000");

        // 발행자 사업자번호, '-'제외 10자리
        cashbill.setFranchiseCorpNum("1234567890");

        // 발행자 상호
        cashbill.setFranchiseCorpName("발행자 상호");

        // 발행자 대표자명
        cashbill.setFranchiseCEOName("발행자 대표자");

        // 발행자 주소
        cashbill.setFranchiseAddr("발행자 주소");

        // 발행자 연락처
        cashbill.setFranchiseTEL("07043042991");

        // 발행안내 문자 전송여부
        cashbill.setSmssendYN(false);

        // 거래처 고객명
        cashbill.setCustomerName("고객명");

        // 거래처 주문상품명
        cashbill.setItemName("상품명");

        // 거래처 주문번호
        cashbill.setOrderNumber("주문번호");

        // 거래처 이메일
        cashbill.setEmail("test@test.com");

        // 거래처 휴대폰
        cashbill.setHp("010111222");

        // 메모
        String Memo = "현금영수증 즉시발행 메모";

        try {
            Response response = cashbillService.registIssue(corpNum, cashbill, Memo);
            m.addAttribute("Response", response);
        } catch (PopbillException e) {
            m.addAttribute("Response", e);
        }
        return "response";
    }

}

② API 호출 결과를 확인하기 위한 "src/main/webapp/WEB-INF/views/response.jsp" 페이지를 생성합니다.

<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<title>현금영수증 API 연동 가이드</title>
	</head>

	<body>
		Response.code : ${Response.code}</br>
		Response.message : ${Response.message}
	</body>
</html>

③ 현금영수증 발행 처리결과를 응답메시지를 통해 확인합니다.

예) 함수호출 성공처리

예) 함수호출 실패처리

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

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

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

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

---

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

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