팝빌 커넥트 서비스

팝빌 커넥트 서비스란 팝빌을 통해 발행한 전자세금계산서의 상태 변경을 실시간으로 확인할 수 있는 웹훅 수신(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분 간격으로 총 2회 재시도됩니다.

5) Response 결과 확인

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

콜백 URL은 80, 443 또는 9854 포트를 사용할 수 있으며 별도의 포트를 사용해야 하는 경우 또는 다수의 연동회원사 콜백 URL을 동일하게 설정하는 경우 기술지원센터(1600-9854)로 문의하여 주시기 바랍니다.

커넥트 프로세스 흐름도

커넥트 수신 샘플 가이드

커넥트 수신서버 웹 어플리케이션 예제코드는 Java - SpringMVC 전자세금계산서 커넥트 가이드를 참조하시기 바랍니다.

전자세금계산서 커넥트 메시지 구성

1) 커넥트 메시지 Header 구성
항목명 설명 예시
Accept 서버 응답 미디어타입 text/plain, */*
pb-Webhook-Type 이벤트 유형 TAXINVOICE.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 (TAXINVOICE.STATE)
2) 커넥트 메시지 Body 구성
항목명 설명 타입 길이 Nullable 비고
corpNum [정발행] - 공급자 사업자번호
[역발행] - 공급받는자 사업자번호
[위수탁] - 수탁자 사업자번호
String 10 -
invoicerMgtKey 공급자 관리번호 String 24 O
invoiceeMgtKey 공급받는자 관리번호 String 24 O
trusteeMgtKey 수탁자 관리번호 String 24 O
ntsconfirmNum 국세청 승인번호 String 24 O
stateCode 상태코드 Number 3 -
stateMemo 상태메모 String 200 O
stateDT 상태변경일시 String 14 - yyyyMMddHHmmss
eventType 이벤트 유형 String 30 - Issue - 발행 CancelIssue - 발행취소 CLOSEDOWN - 공급받는자 휴폐업조회 NTS - 국세청 처리 (303,304,305) Send - 발행예정 CancelSend - 발행예정 취소 Accept - 발행예정 승인 Deny - 발행예정 거부 Request - 역발행 요청 CancelRequest - 역발행 요청 취소 Refuse - 역발행 요청 거부 OPEN - 안내 메일 개봉
eventDT 이벤트 실행일시 String 14 - yyyyMMddHHmmss
ntssendDT 국세청 전송일시 String 200 O yyyyMMddHHmmss
ntsresultDT 국세청 전송결과 수신일시 String 14 O yyyyMMddHHmmss
ntssendErrCode 국세청 전송결과 코드 String 8 O
closeDownState 공급받는자 휴폐업상태 Number 1 O null - 미확인 / 0 - 미등록 / 1 - 사업중 / 2 - 폐업 / 3 - 휴업
closeDownStateDate 공급받는자 휴폐업일자 String 8 O yyyyMMdd
itemKey 팝빌 관리번호 String 18 - 팝빌에서 자동부여

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

커넥트 이벤트 실행에 대해 수신 성공 처리를 위해서는 응답 메시지 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 : 휴폐업 확정일자
국세청
처리
{ "itemKey": "018081411100600001", "stateCode": 304, "corpNum": "6798700433", "stateDT": "20180814111018", "ntssendDT": "20180814111048", "eventDT": "20180814111048", "eventType": "NTS", "ntsconfirmNum": "201808148888888800000007", "closeDownState": 1 }
- 전자세금계산서에 국세청 처리시 알림
- 이벤트 유형(eventType)에 "NTS" 반환
- 전송성공 상태코드(stateCode)에 303/304/305 반환
- 세금계산서 상태코드 보기

기술지원센터

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

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

연동문의