팝빌 커넥트 서비스

팝빌 커넥트 서비스란 홈택스에 신고된 파트너사의 매입/매출 전자세금계산서 정보를 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)로 문의주시기 바랍니다.

커넥트 수신 예제코드 - .NET

1) 커넥트 수신 기능을 구현하기 위한 Web API 프로젝트를 생성합니다.

C#.NET Webhook Connect

2) JSON 포맷의 커넥트 메시지를 매핑하기 위한 프로젝트 Models/ 폴더에 모델 클래스 파일을 추가합니다.

ㆍ추가적인 커넥트 필드 항목은 [커넥트 이벤트 메시지 구성]을 참조하여 추가합니다.

C#.NET Webhook Connect Model
using System;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;

namespace WebApplication1.Models
{
    public class PopbillConnect
    {
        public string eventDT { get; set; }
        public string eventType { get; set; }
        // 하단의 [커넥트 이벤트 메시지 구성]을 참조하여 모델 필드 추가
    }
}

3) POST 메시지를 처리하는 C# APIController 코드를 추가합니다.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using WebApplication1.Models;

namespace WebApplication1.Controllers
{
    public class ValuesController : ApiController
    {

        // POST api/values
        public HttpResponseMessage Post([FromBody]PopbillConnect jsonInfo)
        {
            var response = new HttpResponseMessage();
            response.Headers.Add("ContentType", "text/plain");

            // PopbillConnect 모델에 선언된 필드 매핑
            String eventDT = jsonInfo.eventDT;
            String eventType = jsonInfo.eventType;

            Console.WriteLine(eventType);

            // 커넥트 성공 응답 처리
            response.StatusCode = HttpStatusCode.OK;
            response.Content = new StringContent("OK");

            return response;
        }
    }
}

4) 서버 주소를 팝빌 커넥트 콜백 URL에 등록하고 커넥트 메시지 수신을 테스트합니다.

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

1) 이벤트 메시지 Header 구성
항목명 설명 예시
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
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 비고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"
}

기술지원센터

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

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

연동문의