팝빌 커넥트 서비스란 홈택스에 신고된 파트너사의 매입/매출 전자세금계산서 정보를 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@linkhub.co.kr)로 전송 |
1. 팝빌에 커넥트 서비스 사용 요청
2. 팝빌 사이트 접속 3. [ 홈택스연동 > 커넥트 관리 > 커넥트 등록 ] 접속 4. 커넥트 유형 REST 설정 5. 콜백 URL에 사용할 주소 입력 6. 커넥트 인증 미사용 설정 |
※ 커넥트 서비스는 80 / 443 / 9854 포트를 이용 할 수 있으며, 다른 포트 이용이 필요한 경우 기술지원센터(1600-9854)로 문의주시기 바랍니다.
1) 이벤트 메시지 JSON 처리를 위해서 gson Dependency 정보를 추가하여 Maven 업데이트 합니다.
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.3</version>
</dependency>
2) 아래의 코드를 참조하여 POST Request Body 처리 기능을 추가합니다.
ㆍ콜백 URL 주소를 http(s)://웹서버URL/pbconnect 로 설정했을 때를 가정한 샘플코드입니다.
import java.io.BufferedReader;
import javax.servlet.http.HttpServletRequest;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
@Controller
public class HomeController {
@ResponseBody
@RequestMapping(value = "pbconnect", method = RequestMethod.POST)
public String webhook(HttpServletRequest request){
StringBuffer strBuffer = new StringBuffer();
String line = null;
try {
BufferedReader reader = request.getReader();
while ((line = reader.readLine()) != null) {
strBuffer.append(line);
}
} catch (Exception e) {
System.out.println("Error reading JSON string: " + e.toString());
// 오류정보를 Return 처리. 팝빌 커넥트 실행내역에서 확인가능
return e.toString();
}
// Reqeust Body 출력
System.out.println(strBuffer.toString());
// Request Body JSON 처리.
// 자세한 Request Body 항목은 하단의 [커넥트 메시지 구성] 참조
JsonParser parser = new JsonParser();
JsonObject jsonObject = (JsonObject)parser.parse(strBuffer.toString());
System.out.println("writeDate : " + jsonObject.get("writeDate"));
System.out.println("ntsconfirmNum : " + jsonObject.get("ntsconfirmNum"));
// 커넥트 수신을 성공으로 처리하기 위해 JSON String 구성
return "{'result':'OK'}";
}
}
항목명 | 설명 | 예시 |
---|---|---|
Accept | 팝빌이 원하는 미디어타입 | text/plain, */* |
User-Agent | 요청을 보낸 서버 정보 | Popbill webhook executor (HT.TAXINVOICEXML) |
Pb-Webhook-Type | 커넥트 서비스 유형 | HT.TAXINVOICEXML |
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 |
항목명 | 설명 | 타입 | 길이 | 비고 |
---|---|---|---|---|
writeDate | 작성일자 | String | 8 | 형식 : yyyyMMdd |
ntsconfirmNum | 국세청 승인번호 | String | 24 | |
issueDT | 발행일시 | String | 14 | 형식 : yyyyMMddHHmmss |
invoiceType | 전자세금계산서 종류 | Number | 3 |
101 : (일반 세금계산서)
102 : (영세율 세금계산서) 103 : (위수탁 세금계산서) 104 : (수입 세금계산서) 105 : (위수탁 영세율 세금계산서) 201 : (수정 일반 세금계산서) 202 : (수정 영세율 세금계산서) 203 : (수정 위수탁 세금계산서) 204 : (수정 수입 세금계산서) 205 : (수정 영세율 위수탁 세금계산서) 301 : (일반 계산서) 303 : (위수탁 계산서) 304 : (수입 계산서) 401 : (수정 일반 계산서) 403 : (수정 위수탁 계산서) 404 : (수정 수입 계산서) 중 반환 |
taxType | 과세형태 | String | 2 | "과세" / "영세" / "면세" 중 반환 |
taxTotal | 세액 합계 | String | 18 | |
supplyCostTotal | 공급가액 합계 | String | 18 | |
totalAmount | 합계금액 | String | 18 | |
purposeType | 영수/청구 | String | 2 | "영수" / "청구" / "없음" 중 반환 |
serialNum | 일련번호 | String | 30 | |
cash | 현금 | String | 18 | |
chkBill | 수표 | String | 18 | |
credit | 외상 | String | 18 | |
note | 어음 | String | 18 | |
remark1 | 비고1 | String | 150 | |
remark2 | 비고2 | String | 150 | |
remark3 | 비고3 | String | 150 | |
invoicerCorpNum | 공급자 사업자번호 | String | 10 | |
invoicerMgtKey | 공급자 문서번호 | String | 24 | |
invoicerTaxRegID | 공급자 종사업장 식별번호 | String | 4 | 4자리 숫자값 |
invoicerCorpName | 공급자 상호 | String | 200 | |
invoicerCEOName | 공급자 대표자 성명 | String | 100 | |
invoicerAddr | 공급자 주소 | String | 300 | |
invoicerBizType | 공급자 업태 | String | 100 | |
invoicerBizClass | 공급자 종목 | String | 100 | |
invoicerContactName | 공급자 담당자 성명 | String | 100 | |
invoicerDeptName | 공급자 담당자 부서명 | String | 100 | |
invoicerTEL | 공급자 담당자 연락처 | String | 20 | |
invoicerEmail | 공급자 담당자 이메일 | String | 100 | |
invoiceeCorpNum | 공급받는자 사업자번호 | String | 10 | |
invoiceeType | 공급받는자 구분 | String | 3 | "사업자" / "개인" / "외국인" 중 반환 |
invoiceeMgtKey | 공급받는자 문서번호 | String | 24 | |
invoiceeTaxRegID | 공급받는자 종사업장 식별번호 | String | 4 | 4자리 숫자값 |
invoiceeCorpName | 공급받는자 상호 | String | 200 | |
invoiceeCEOName | 공급받는자 대표자 성명 | String | 100 | |
invoiceeAddr | 공급받는자 주소 | String | 300 | |
invoiceeBizType | 공급받는자 업태 | String | 100 | |
invoiceeBizClass | 공급받는자 종목 | String | 100 | |
invoiceeContactName1 | 공급받는자 주)담당자 성명 | String | 100 | |
invoiceeDeptName1 | 공급받는자 주)담당자 부서명 | String | 100 | |
invoiceeTEL1 | 공급받는자 주)담당자 연락처 | String | 20 | |
invoiceeEmail1 | 공급받는자 주)담당자 이메일 | String | 100 | |
invoiceeContactName2 | 공급받는자 부)담당자 성명 | String | 100 | |
invoiceeDeptName2 | 공급받는자 부)담당자 부서명 | String | 100 | |
invoiceeTEL2 | 공급받는자 부)담당자 연락처 | String | 20 | |
invoiceeEmail2 | 공급받는자 부)담당자 이메일 | String | 100 | |
trusteeCorpNum | 수탁자 사업자번호 | String | 10 | |
trusteeMgtKey | 수탁자 문서번호 | String | 24 | |
trusteeTaxRegID | 수탁자 종사업장번호 | String | 4 | 4자리 숫자값 |
trusteeCorpName | 수탁자 상호 | String | 200 | |
trusteeCEOName | 수탁자 대표자 성명 | String | 100 | |
trusteeAddr | 수탁자 주소 | String | 300 | |
trusteeBizType | 수탁자 업태 | String | 100 | |
trusteeBizClass | 수탁자 종목 | String | 100 | |
trusteeContactName | 수탁자 담당자 성명 | String | 100 | |
trusteeDeptName | 수탁자 담당자 부서명 | String | 100 | |
trusteeTEL | 수탁자 담당자 연락처 | String | 20 | |
trusteeEmail | 수탁자 담당자 이메일 | String | 100 | |
modifyCode | 수정 사유코드 | Number | 1 |
1 : (기재사항 착오정정)
2 : (공급가액 변동) 3 : (환입) 4 : (계약의 해지) 5 : (내국신용장 사후개설) 6 : (착오에 의한 이중발행) 중 반환 |
orgNTSConfirmNum |
원본 전자세금계산서
국세청 승인번호 |
String | 24 | |
detailList | 상세항목 배열 | Array | 99 | |
┖ serialNum | 일련번호 | Number | 2 | |
┖ purchaseDT | 거래일자 | String | 8 | 형식 : yyyyMMdd |
┖ itemName | 품명 | String | 100 | |
┖ spec | 규격 | String | 60 | |
┖ qty | 수량 | String | 12 | |
┖ unitCost | 단가 | String | 18 | |
┖ supplyCost | 공급가액 | String | 18 | |
┖ tax | 세액 | String | 18 | |
┖ remark | 비고 | String | 100 |
커넥트 이벤트 실행에 대해 수신 성공 처리를 위해서는 응답 메시지 Body 를 아래와 같이 두가지 응답 타입 중 한가지를 반환하도록 처리하면 됩니다.
유형 | String 타입 | JSON 타입 |
---|---|---|
Body 메시지 | "OK" |
{
"result":"OK" } |
커넥트 실행내역 확인 및 재실행