팝빌 현금영수증 커넥트

현금영수증 커넥트는 팝빌을 통해 발급한 현금영수증의 발행 / 국세청 전송 신고 / 국세청전송 결과 정보를 실시간 연결하여 자동으로 확인할 수 있는 웹훅 수신(Webhook Incoming) 기술을 적용한 서비스 입니다. 현금영수증 상태를 별도의 API 함수를 호출하지 않아도 지정한 콜백 URL을 통해 변경실시간으로 현금영수증 상태변경 이벤트 메시지를 수신할 수 있습니다.

커넥트 서비스 프로세스

ㆍ 팝빌 커넥트 메시지는 고객사 커넥트 수신 URL로 HTTP POST Request 형태로 전송됩니다.

ㆍ 파트너사 웹 어플리케이션을 통해 HTTP POST Request Body를 JSON decode 커넥트 이벤트 메시지를 확인합니다.

ㆍ HTTP 통신오류(Read timeout, Gateway timeout, SSL 오류 등)로 인해 커넥트 실패시 5분 간격으로 총 2회 재시도됩니다.

ㆍ 기술지원센터에서는 커넥트 실패 건에 대해 모니터링하여 고객사 서버의 장애 감지시 유선으로 안내해 드립니다.

ㆍ 다수의 연동회원사 커넥트 콜백 URL을 동일하게 설정하는 경우 기술지원센터(1600-9854)로 문의하여 주시기 바랍니다.

커넥트 프로세스 흐름도

커넥트 수신 예제코드- SpringMVC

1) 이벤트 메시지 JSON 처리를 위해서 gson Dependency 정보를 추가하여 Maven 업데이트 합니다.

<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.3</version>
</dependency>

2) 아래의 코드를 참조하여 POST Request Body 처리 기능을 추가합니다.

ㆍ 커넥트 수신 URL 주소를 http(s)://웹서버URL/pbconnect 로 설정했을 때를 가정한 샘플코드입니다.

import java.io.BufferedReader;
import javax.servlet.http.HttpServletRequest;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

@Controller
public class HomeController {

  @ResponseBody
  @RequestMapping(value = "pbconnect", method = RequestMethod.POST)
  public String webhook(HttpServletRequest request){

    StringBuffer strBuffer = new StringBuffer();
    String line = null;

    try {
      BufferedReader reader = request.getReader();
      while ((line = reader.readLine()) != null) {
         strBuffer.append(line);
      }
    } catch (Exception e) {
      System.out.println("Error reading JSON string: " + e.toString());

      // 오류정보를 Return 처리. 팝빌 커넥트 실행내역에서 확인가능
      return e.toString();
    }

    // Reqeust Body 출력
    System.out.println(strBuffer.toString());

    // Request Body JSON 처리.
    // 자세한 Request Body 항목은 하단의 [커넥트 이벤트 메시지 구성] 참조
    JsonParser parser = new JsonParser();
    JsonObject jsonObject = (JsonObject)parser.parse(strBuffer.toString());
    System.out.println("eventType : " + jsonObject.get("eventType"));
    System.out.println("eventDT : " + jsonObject.get("eventDT"));

    // 커넥트 수신을 성공으로 처리하기 위해 JSON String 구성
    return "{'result':'OK'}";
  }
}

실시간으로 제공하는 커넥트 이벤트 목록

1) 현금영수증 발행 / 발행취소 알림

2) 국세청 전송시작 알림

3) 국세청 전송결과(전송성공 또는 전송실패) 알림

현금영수증 커넥트 설정 방법

1) [팝빌 사이트 로그인] > [현금영수증] 메뉴 선택 > 왼쪽 메뉴탭 하단의 [환경설정 - 커넥트 관리] 메뉴 선택

2) 커넥트 유형 'Rest' 선택

3) 콜백 URL 입력 후 저장

▶ 콜백 URL은 80 또는 443 포트를 사용할 수 있으며 별도의 포트를 사용해야 하는 경우 기술지원센터로 문의하여 주시기 바랍니다.

현금영수증 커넥트 적용 예시

아래의 영상은 Request Body를 콘솔에 출력하는 예제입니다. 이벤트 메시지 Body는 JSON 포맷으로 구성되며, 상태코드(stateCode) 항목을 통해 현금영수증 상태를 확인할 수 있습니다. 영상은 현금영수증 발행 / 발행취소 발생하는 이벤트 메시지에 대한 예시 영상입니다.

현금영수증 커넥트 이벤트 메시지 구성

1) 이벤트 메시지 Header 구성
항목명 설명 예시
Accept 서버 응답 미디어타입 text/plain, */*
pb-Webhook-Type 이벤트 유형 CASHBILL.STATE
pb-Webhook-MID 이벤트 식별값 016100000008-d12b47c886924c079aebe7a
Content-Type Requset Body Type application/json
Content-Length Request Body Length 157
Host 호스트 정보 13.125.250.38:8080
Connection keep-alive
Authorization 커텍트 인증 - BASIC 이용 Basic dGVzdDp0ZXN0MTIzNA==
X-API-Key 커넥트 인증 - API KEY 이용 test1234
User-Agent 요청 정보 Popbill webhook executor (CASHBILL.STATE)
2) 이벤트 메시지 Body 구성
항목명 설명 타입 길이 Nullable 비고
corpNum 가맹점 사업자번호 String 10 -
eventType 이벤트 유형 String 30 - Issue - 발행 Cancel - 발행취소 NTS - 국세청 처리
eventDT 이벤트 실행일시 String 14 - yyyyMMddHHmmss
mgtKey 가맹점 관리번호 String 24 O
stateMemo 상태메모 String 200 O
stateCode 상태코드 Number 3 - [부록] "현금영수증 상태코드"
stateDT 상태변경일시 String 14 - yyyyMMddHHmmss
confirmNum 국세청 승인번호 String 9 - 국세청 전송중 상태(303)로 변경시 할당
ntsresultCode 국세청 처리결과 상태코드 String 4 O [부록] "국세청 처리결과 상태코드"
ntssendDT 국세청 전송일시 String 14 O yyyyMMddHHmmss
ntsresultDT 국세청 처리결과 수신일시 String 14 O yyyyMMddHHmmss
ntsresultMessage 국세청 처리결과 메시지 String 100 O
itemKey 팝빌 관리번호 (팝빌에서 자동부여) String 18 -

커넥트 응답 메시지 구성

커넥트 이벤트 실행에 대해 수신 성공 처리를 위해서는 응답 메시지 Body 를 아래와 같이 두가지 응답 타입 중 한가지를 반환하도록 처리하면 됩니다.

유형 String 타입 JSON 타입
Body 메시지 "OK" { "result":"OK" }

커넥트 이벤트 실행내역 확인 및 재실행

정상적 커넥트 이벤트를 처리하지 못한 경우 실행내역에서 이벤트를 재실행할 수 있습니다.

1) [팝빌 사이트 로그인] > [현금영수증] 메뉴 선택 > 왼쪽 메뉴 하단의 [환경설정 - 커넥트 관리] 메뉴 선택 > [실행내역] 탭 선택

2) 재실행 할 메시지 확인 후 재실행

기술지원센터

팝빌 기술지원은 유선, 메일, 원격지원 등 다양한 채널을 통해 제공됩니다.

T. 1600-9854 E. code@linkhub.co.kr

연동문의