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

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

본 포스팅에서는 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

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

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

---

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

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