팝빌 커넥트 서비스

팝빌 커넥트 서비스란 문자 전송결과를 실시간으로 확인할 수 있는 웹훅 수신(Webhook Incoming) 서비스입니다. 문자 전송을 요청한 시점부터 수신 단말기기가 문자를 받고 전송성공 시그널을 응답할때까지 지연이 발생합니다. 이 때문에 지속적으로 문자 전송결과를 확인해야 하는 불편함 대신에, 지정한 콜백 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. [ 문자 · 팩스 > 커넥트 관리 > 커넥트 등록 ] 접속 4. 커넥트 유형 REST 설정 5. 콜백 URL에 사용할 주소 입력 6. 커넥트 인증 미사용 설정

※ 커넥트 서비스는 80 / 443 / 9854 포트를 이용 할 수 있으며, 다른 포트 이용이 필요한 경우 기술지원센터(1600-9854)로 문의주시기 바랍니다.

커넥트 수신 샘플 가이드

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

문자 커넥트 메시지 구성

1) 커넥트 메시지 Header 구성

항목명	설명	예시
Accept	팝빌이 원하는 미디어타입	text/plain, */*
User-Agent	요청을 보낸 서버 정보	Popbill webhook executor (SMS.STATE)
Pb-Webhook-Type	커넥트 서비스 유형	SMS.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 구성

항목명	설명	타입	길이	비고
receiptNum	접수번호	String	18
requestNum	전송요청번호	String	36
sendNum	발신번호	String	20
sendName	발신자명	String	70
receiveNum	수신번호	String	20
receiveName	수신자명	String	70
state	전송상태 코드	String	1	0 : (접수) / 1 : (대기중) / 2 : (처리중) / 3 : (완료) / 4 : (취소) 중 반환 ※ 전송상태 코드 상태 값은 작아지지 않음 └ 예) 3 => 2 변경 X
result	문자전송 결과코드	String	3	상태코드가 3 인 경우, result 값이 존재[참고] 전송 상태 및 결과 코드
resultDT	전송결과 수신일시	String	14	형식 : yyyyMMddHHmmss
serialNum	일련번호	String	1
receiptDT	접수일시	String	14	형식 : yyyyMMddHHmmss
eventType	이벤트 유형	String	-	"RESULT" / "MANUAL" 중 반환 └ RESULT = 팝빌 시스템에서 문자 전송 결과 확인하여 자동으로 커넥트 실행한 경우 └ MANUAL = 팝빌 사이트에서 사용자가 수동으로 커넥트 실행한 경우
type	문자 유형	String	3	"SMS" / "LMS" / "MMS" 중 반환
content	메시지 내용	String	2000
corpNum	팝빌회원 사업자번호	String	10
tranNet	전송 통신사명	String	3
sendDT	전송일시	String	14	형식 : yyyyMMddHHmmss
eventDT	이벤트 전송일시	String	14	형식 : yyyyMMddHHmmss

※ 문자 전송상태 코드(state) 값을 UPDATE 하는 경우, 전송상태값은 작아지지 않음을 유의하셔야 합니다.

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

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

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