팝빌 홈택스연동 전자세금계산서 커넥트

홈택스연동 전자세금계산서 커넥트 서비스는 홈택스에 신고된 사업자의 매입/매출 전자세금계산서 정보를 1시간 단위로 지정된 콜백 URL을 통해 수신할 수 있는 웹훅 수신(Webhook Incoming) 서비스 입니다. 커넥트 서비스 사용 설정 후 매 정시마다 전자세금계산서 정보를 수신 할 수 있습니다.

커넥트 서비스 프로세스

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

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

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

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

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

커넥트 프로세스 흐름도

커넥트 수신 샘플 가이드

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

홈택스연동 전자세금계산서 커넥트 설정 방법

1) [팝빌 사이트 로그인] > [홈택스연동] 메뉴 선택 > 왼쪽 메뉴탭 하단의 [환경설정 - 커넥트 관리] 선택

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

3) 콜백 URL 입력 후 저장

※ 최초 커넥트 설정(오전 9:30)한 시점으로 그 다음 정시(오전 10:00) 부터 1시간 간격으로 세금계산서 정보를 수신할 수 있습니다.
최초 수신(오전 10:00) 정보는 커넥트 설정 기준일 00:00 시부터 등록된 세금계산서 내용을 수신합니다.
1시간 간격으로 커넥트를 수신하기 위해, 반드시 부서사용자 인증 정보를 등록해주셔야 합니다.

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

홈택스연동 전자세금계산서 커넥트 이벤트 메시지 구성

1) 이벤트 메시지 Header 구성
항목명 설명 예시
Accept 서버 응답 미디어타입 text/plain, */*
pb-Webhook-Type 이벤트 유형 TAXINVOICE.STATE
pb-Webhook-CorpNum 팝빌 연동회원 사업자번호 6798700433
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 (TAXINVOICE.STATE)
2) 이벤트 메시지 Body 구성
항목명 설명 타입 길이 비고
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 비고1 String 150
remark3 비고1 String 150
invoicerCorpNum 공급자 사업자번호 String 10
invoicerMgtKey 공급자 문서관리번호 String 24
invoicerTaxRegID 공급자 종사업장 식별번호 String 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
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
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" }

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

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

1) [팝빌 사이트 로그인] > [홈택스연동] 메뉴 선택 > 왼쪽 메뉴 하단의 [커넥트 관리] 메뉴 선택 > [전자세금계산서 실행내역] 탭 선택

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

기술지원센터

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

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

연동문의