팝빌 커넥트 서비스

팝빌 커넥트 서비스란 팝빌을 통해 발행한 전자세금계산서의 상태 변경을 실시간으로 확인할 수 있는 웹훅 수신(Webhook Incoming) 서비스입니다. 파트너가 세금계산서 상태값을 확인하기 위해 팝빌 SDK 함수를 사용하지 않아도, 지정한 콜백 URL으로 실시간 전송되는 HTTP 메시지를 활용하여 보다 쉽고 편하게 발행한 세금계산서의 상태정보를 확인할 수 있습니다.

커넥트 서비스 프로세스

1) 커넥트 이벤트 발생 : 팝빌은 파트너의 콜백 URL를 확인합니다.

2) HTTP Request : 파트너의 해당 콜백 URL로 HTTP POST Request 메시지를 보냅니다.

3) Request 정보 확인 : 파트너는 HTTP POST Request의 Body에 담긴 JSON 객체 형태의 값을 확인하고 처리합니다.

4) HTTP Response

파트너의 정보 처리가 성공이라면, OK(String) 또는 {"result" : "OK"}(JSON Object) 값을 HTTP Response로 보냅니다. 이 때 HTTP 통신 오류(Read timeout, Gateway timeout, SSL 오류 등)로 인해 커넥트 실패시 5분 간격으로 총 3회 재시도됩니다.

5) Response 결과 확인

팝빌은 Response 결과 값에 따라 커넥트 성공/실패를 판별하며, 실패 건에 대해 모니터링하여 고객사 서버의 장애 감지시 유선으로 안내해 드립니다.

커넥트 프로세스 흐름도

커넥트 유형 및 설정 방법

팝빌에서는 두가지 커넥트 방식을 지원하며 유형에 따른 설정 방법은 하단의 표를 참고하시기 바랍니다.

구분 통합 설정 개별 설정
적용 대상 고객사의 모든 회원 하나의 회원
설정 방법 팝빌에서 일괄 적용
> 이용할 콜백 URL을 메일(code@linkhub.co.kr)로 전송
1. 팝빌 사이트 접속
2. [ 전자세금계산서 > 커넥트 관리 > 커넥트 등록 ] 접속
3. 커넥트 유형 REST 설정
4. 콜백 URL에 사용할 주소 입력
5. 커넥트 인증 미사용 설정

※ 커넥트 서비스는 80 / 443 / 9854 포트를 이용 할 수 있으며, 다른 포트 이용이 필요한 경우 기술지원센터(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) 커넥트 메시지 Header 구성
항목명 설명 예시
Accept 팝빌이 원하는 미디어타입 text/plain, */*
User-Agent 요청을 보낸 서버 정보 Popbill webhook executor (TAXINVOICE.STATE)
pb-Webhook-Type 커넥트 서비스 유형 TAXINVOICE.STATE
pb-Webhook-MID 이벤트 식별값 016120000002-1777d55c2c41492ab06826d
pb-Webhook-Corpnum 팝빌 사업자번호 6798700433
Content-Type 커넥트 메시지의 Body 타입 application/json
Host 요청 대상이 되는 호스트 정보 docs.popbill.com
Connection 팝빌과 고객사 간에 커넥트 연결 옵션 keep-alive
Content-Length 커넥트 메시지의 Body 길이 243
Authorization 커텍트 인증 - BASIC 이용시
Requset Header에 추가되는 항목
Basic VEVTVDoxMjM=
x-api-key 커넥트 인증 - API KEY 이용시
Requset Header에 추가되는 항목
TEST
2) 커넥트 메시지 Body 구성
항목명 설명 타입 길이 필수 비고
corpNum 사업자번호 String 10 O [정발행] - 공급자 사업자번호
[역발행] - 공급받는자 사업자번호
[위수탁] - 수탁자 사업자번호
invoicerMgtKey 공급자 관리번호 String 24 -
invoiceeMgtKey 공급받는자 관리번호 String 24 -
trusteeMgtKey 수탁자 관리번호 String 24 -
ntsconfirmNum 국세청 승인번호 String 24 O
stateCode 상태코드 Number 3 O ※ 세금계산서 상태 값은 작아지지 않음
└ 예) 303 => 301 변경 X
[참고] 세금계산서 상태코드 보기
stateMemo 상태메모 String 200 -
stateDT 상태변경일시 String 14 O 형식 : yyyyMMddHHmmss
eventType 이벤트 유형 String 30 O Issue : (발행)
CancelIssue : (발행취소)
CLOSEDOWN : (공급받는자 휴폐업조회)
NTS : (전송중, 전송성공, 전송실패)
Request : (역발행 요청)
CancelRequest : (역발행 요청 취소)
Refuse : (역발행 요청 거부)
OPEN : (세금계산서 확인 - 안내메일)
* 안내 메일의 전자세금계산서 보기 버튼을 클릭한 경우에 OPEN 이벤트가 발생
eventDT 이벤트 실행일시 String 14 O 형식 : yyyyMMddHHmmss
ntssendDT 국세청 전송일시 String 200 - 형식 : yyyyMMddHHmmss
ntsresultDT 국세청 전송결과 수신일시 String 14 - 형식 : yyyyMMddHHmmss
ntssendErrCode 국세청 전송 결과코드 String 8 - [참고] 국세청 전송 결과코드 보기
closeDownState 공급받는자 휴폐업상태 Number 1 - null / 0 / 1 / 2 / 3 중 반환
└ null = 미확인, 0 = 미등록
└ 1 = 사업중, 2 = 폐업, 3 = 휴업
closeDownStateDate 공급받는자 휴폐업일자 String 8 - 형식 : yyyyMMdd
itemKey 팝빌번호 String 18 O 팝빌에서 세금계산서 관리 목적으로 할당한 식별번호

커넥트 응답 메시지(처리 결과 메시지) 구성

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

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

커넥트 이벤트 메시지 Request Body 예시

이벤트
형식
HTTP Request Body 설명
발행 {
"itemKey": "018081413254200001",
"stateCode": 300,
"corpNum": "6798700433",
"stateDT": "20180814132542",
"invoicerMgtKey": "20180814-03",
"eventDT": "20180814132542",
"eventType": "Issue",
"ntsconfirmNum": "20180814888888880000000f",
"stateMemo": "즉시발행 메모"
}

- 세금계산서 발행시 할당한 문서번호(invoicerMgtKey)를 통해 식별
- 발행시 국세청 승인번호(ntsconfirmNum) 할당
- 이벤트 유형(eventType)에 "Issue" 값 반환
- 발행완료 상태코드(stateCode)에 300 값 반환
휴폐업
조회 결과
{
"itemKey": "018081410581200001",
"stateCode": 300,
"corpNum": "6798700433",
"stateDT": "20180814105815",
"eventDT": "20180814105815",
"eventType": "CLOSEDOWN",
"closeDownState": 2,
"closeDownStateDate": "20141031"
}

- 세금계산서 발행 후 실시간으로 공급받는자 휴폐업 조회 결과 정보 제공
- 이벤트 유형(eventType)에 "CLOSEDOWN" 값 반환
- closeDownState : null-미확인 / 0-미등록 / 1-사업중 / 2-폐업 / 3-휴업
- closeDownStateDate : 휴폐업 확정일자
국세청
처리
{
"invoicerMgtKey": "df3452345",
"stateDT": "20200303174041",
"eventType": "NTS",
"closeDownState": 0,
"itemKey": "020030310220500001",
"ntsconfirmNum": "20200303888888880000007f",
"corpNum": "1234567890",
"ntssendDT": "20200303174050",
"stateCode": 303,
"eventDT": "20200303174050"
}

- 전자세금계산서에 국세청 처리시 알림
- 이벤트 유형(eventType)에 "NTS" 반환
- 전송성공 상태코드(stateCode)에 303/304/305 반환
- [참고] 세금계산서 상태코드

※ 세금계산서 상태(stateCode) 값을 UPDATE 하는 경우, 상태값은 작아지지 않음을 유의하셔야 합니다.

기술지원센터

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

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

연동문의