팝빌 커넥트 서비스

팝빌 커넥트 서비스란 팝빌을 통해 발행한 전자세금계산서의 상태 변경을 실시간으로 확인할 수 있는 웹훅 수신(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)로 문의주시기 바랍니다.

커넥트 수신 예제코드 - Node.js

ㆍNode.js에 내장된 http 모듈의 createServer 함수를 사용한 커넥트 수신 예제코드입니다.

ㆍ커넥트 이벤트 메시지의 추가적인 항목은 하단의 [커넥트 메시지 구성]을 참조하시기 바랍니다.

var http = require('http');

http.createServer(function(req, res) {

    var jsonData = "";

    req.on('data', function(chunk) {
        jsonData += chunk;
    });

    req.on('end', function(){

        // JSON Parse, 추가적인 항목은 하단의 [커넥트 메시지 구성]을 참조하여 필드 추가
        var reqObj = JSON.parse(jsonData);
        console.log(reqObj);
        console.log(reqObj['eventDT']);
        console.log(reqObj['eventType']);

        // Response 성공 처리.
        res.writeHead(200);
        res.end('{"result":"OK"}');
    });
}).listen(80);

ㆍ위의 코드를 실행한 서버에서 전자세금계산서 발행 처리에 대한 커넥트 이벤트 Request를 콘솔에 출력한 예시입니다.

Nodejs Webhook Connect Model

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

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

연동문의