팝빌 커넥트 서비스

팝빌 커넥트 서비스란 홈택스에 신고된 파트너사의 매입/매출 현금영수증 정보를 1시간 단위로 받아 볼 수 있는 웹훅 수신(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@linkhubcorp.com)로 전송
1. 팝빌에 커넥트 서비스 사용 요청
2. 팝빌 사이트 접속
3. [ 홈택스연동 > 커넥트 관리 > 커넥트 등록 ] 접속
4. 커넥트 유형 REST 설정
5. 콜백 URL에 사용할 주소 입력
6. 커넥트 인증 미사용 설정

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

커넥트 수신 예제코드- PHP

ㆍ아래의 코드를 참조하여 POST Request Body 처리 기능을 추가합니다.

ㆍ커넥트 수신 URL 주소를 http(s)://웹서버URL/pbconnect.php 로 설정했을 때를 가정한 샘플코드입니다.

// $DOCUMENT_ROOT/pbconnect.php

<?php

  ini_set("allow_url_fopen", true);

  // 팝빌 커넥트 Request Body
  $json_string = file_get_contents('php://input');

  // 커넥트 메시지 Json parse
  $connect_message = json_decode($json_string, true);

  // 추가적인 커넥트 메시지 항목은 하단의 [커넥트 이벤트 메시지 구성] 참조
  $connect_message['invoiceType']; // 현금영수증 유형
  $connect_message['ntsconfirmNum']; // 현금영수증 국세청 승인번호

  // 커넥트 Request에 대한 응답 메시지 반환
  echo "{'result':'OK'}";
?>

홈택스연동 현금영수증 커넥트 이벤트 메시지 구성

1) 이벤트 메시지 Header 구성
항목명 설명 예시
Accept 팝빌이 원하는 미디어타입 text/plain, */*
User-Agent 요청을 보낸 서버 정보 Popbill webhook executor (HT.CASHBILL)
Pb-Webhook-Type 커넥트 서비스 유형 HT.CASHBILL
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 구성
항목명 설명 타입 길이 비고
ntsconfirmNum 국세청 승인번호 String 9
tradeDate 거래일자 String 8 형식 : yyyyMMdd
tradeDT 거래일시 String 14 형식 : yyyyMMddHHmmss
tradeType 문서형태 String 4 "승인거래" / "취소거래" 중 반환
tradeUsage 거래구분 String 5 "소득공제용" / "지출증빙용" 중 반환
totalAmount 거래금액 String 9
supplyCost 공급가액 String 9
tax 부가세 String 9
serviceFee 봉사료 String 9
invoiceType 매입/매출 String 2 "매입" / "매출" 중 반환
franchiseCorpNum 발행자 사업자번호 String 10 하이픈 ('-') 제외
franchiseCorpName 발행자 상호 String 200 매입 현금영수증일 경우 반환
franchiseCorpType 발행자 사업자유형 String 1 매입 현금영수증일 경우, "1" : (일반과세자) /
"2" : (간이과세자) / "3" : (법인과세자) 중 반환
identityNum 식별번호 String 4 마지막 4자리만 반환
identityNumType 식별번호유형 String 1 "1" : (주민등록번호) / "2" : (사업자번호) /
"3" : (휴대전화번호) / "4" : (신용카드번호) 중 반환
customerName 구매자(고객) 성명 String 70
cardOwnerName 카드소유자 성명 String 70
deductionType 공제유형 String 1 "1" or "2" : (공제) / "3" or "4" : (불공제) 중 반환

※ 현금영수증의 국세청 승인번호는 중복 될 수 있기 때문에 국세청 승인번호(ntsconfirmNum), 거래일자(tradeDate)를 기본키로 사용해야 합니다.

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

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

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

기술지원센터

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

T. 1600-9854   E. code@linkhubcorp.com

연동문의