팝빌 전자명세서 커넥트

전자명세서 커넥트 서비스란 팝빌을 통해 발행한 전자명세서의 상태변경 정보를 실시간으로 확인할 수 있는 웹훅 수신(Webhook Incoming) 서비스입니다. 기존 제공되던 API 방식과 달리 전자명세서 상태를 확인하기 위해 상태확인 함수를 호출하지 않아도 지정한 콜백 URL을 통해 실시간으로 수신되는 HTTP 이벤트 메시지를 활용하여 보다 쉽고 편하게 발행한 전자명세서의 상태정보를 확인할 수 있습니다.

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

1) 전자명세서 발행 / 발행취소 알림

2) 수신자 승인 / 거부 알림

커넥트 서비스 프로세스

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

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

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

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

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

커넥트 프로세스 흐름도

커넥트 수신 예제코드 - Classic ASP

ㆍ 팝빌 커넥트 수신 VBScript 예제코드입니다.

ㆍ 팝빌 ASP SDK 예제코드에 포함된 ./Popbill/Linkhub/json2.asp를 사용하여 커넥트 JSON Message를 처리합니다.

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

'DocumentRoot/connect.asp

<!--#include file="Popbill/Linkhub/json2.asp"-->

<%

If Request.TotalBytes > 0 Then

  Dim RequestBodyBytes
  RequestBodyBytes = Request.TotalBytes

  'JSON String을 JSON Object로 변환
  Set parse = JSON.parse(BytesToStr(Request.BinaryRead(RequestBodyBytes)))

  eventDT = parse.eventDT '커넥트 실행일시
  eventType = parse.eventType '커넥트 유형
  '추가적인 항목은 [커넥트 이벤트 메시지 구성] 참조

  '커넥트 수신 성공처리를 위해 Response Message "OK" String 반환
  Response.Write "OK"

End If

'Byte 형태의 POST Request Body Message를 String으로 변환하는 함수
Function BytesToStr(bytes)
  Dim Stream
  Set Stream = Server.CreateObject("Adodb.Stream")
    Stream.Type = 1 'adTypeBinary
    Stream.Open
    Stream.Write bytes
    Stream.Position = 0
    Stream.Type = 2 'adTypeText
    Stream.Charset = "UTF-8"
    BytesToStr = Stream.ReadText
    Stream.Close
  Set Stream = Nothing
End Function

%>

전자명세서 커넥트 설정 방법

1) [팝빌 사이트 로그인] > [전자명세서] 메뉴 선택 > 왼쪽 메뉴탭 하단의 [환경설정 - 커넥트 관리] 선택

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

3) 콜백 URL 입력 후 저장

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

전자명세서 커넥트 적용 예시

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

전자명세서 커넥트 이벤트 메시지 구성

1) 이벤트 메시지 Header 구성
항목명 설명 예시
Accept 서버 응답 미디어타입 text/plain, */*
pb-Webhook-Type 이벤트 유형 STATEMENT.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 (STATEMENT.STATE)
2) 이벤트 메시지 Body 구성
항목명 설명 타입 길이 Nullable 비고
corpNum 발행자 사업자번호 String 10 -
eventType 이벤트 유형 String 30 - Issue - 발행 Cancel - 발행취소 Accept - 승인 Deny - 거부
eventDT 이벤트 실행일시 String 14 - yyyyMMddHHmmss
itemCode 전자명세서 구분 Number 3 - 121 - 거래명세서 122 - 청구서 123 - 견적서 124 - 발주서 125 - 입금표 126 - 영수증
mgtKey 파트너가 부여한 문서번호 String 24 O
stateMemo 상태메모 String 200 O
stateCode 상태코드 String 3 - [부록] "전자명세서 상태코드"
stateDT 상태변경일시 String 14 - yyyyMMddHHmmss
itemKey 팝빌 관리번호 (팝빌에서 자동부여) String 18 -
invoiceNum 팝빌에서 부여한 고유번호 String 24 O

커넥트 응답 메시지 구성

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

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

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

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

1) [팝빌 사이트 로그인] > [전자명세서] 메뉴 선택 > 왼쪽 메뉴 하단의 [환경설정 - 커넥트 관리] 메뉴 선택 > [실행내역] 탭 선택

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

기술지원센터

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

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

연동문의