POPBill Developers
POPBill Developers 끊임없는 고민으로 빈틈없는 기술력을 제공합니다.

팝빌은 2004년부터 시작된 API 연동에 대한 높은 이해도와 뛰어난 기술력을 가지고 개발자를 위한 연동가이드를 만듭니다. 팝빌 API는 전자세금계산서, 현금영수증 뿐만 아니라, 데이터 수집, 금융, 메시징 등 다양한 서비스로 넓혀 나가고 있습니다.

API Reference
전자세금계산서
.NET Core
API Reference 전자세금계산서 .NET Core 객체정보

A. 객체정보

Response

순번 변수명 타입 길이 비고
code long - API 처리에 대한 응답코드
message string - API 처리에 대한 응답메시지

IssueResponse

순번 변수명 타입 길이 비고
code long - API 처리에 대한 응답코드
message string - API 처리에 대한 응답메시지
ntsConfirmNum string 24 국세청 승인번호
└ 세금계산서 발행 시점에 팝빌에서 자동으로 부여

PopbillException

순번 변수명 타입 길이 비고
code long - API 처리 실패에 대한 오류코드 ("-"로 시작하는 8자리 숫자값)
└ [참고] 오류코드
message string - API 처리 실패에 대한 오류메시지

MgtKeyType

순번 변수명 타입 길이 비고
SELL enum - 매출
BUY enum - 매입
TRUSTEE enum - 수탁

Taxinvoice

순번 변수명 타입 길이 필수 비고
ntsconfirmNum string 24 X 국세청 승인번호
└ 세금계산서 발행(전자서명) 시점에 팝빌에서 자동으로 부여
issueType string 3 O 발행형태 : "정발행" / "역발행" / "위수탁" 중 택 1
taxType string 2 O 과세형태 : "과세" / "영세" / "면세" 중 택 1
chargeDirection string 3 O 과금방향 : "정과금" / "역과금" 중 택 1
└ 정과금 = 공급자 과금
└ 역과금 = 공급받는자 과금
※ {issueType} = "역발행" 만 역과금 가능
serialNum string 30 - 일련번호
kwon int? 4 - 책번호 "권" 항목
ho int? 4 - 책번호 "호" 항목
writeDate string 8 O 작성일자 (yyyyMMdd)
purposeType string 2 O 영수/청구 : "영수" / "청구" / "없음" 중 택 1
supplyCostTotal string 18 O 공급가액 합계
└ 정수만 입력 가능
└ 마이너스 금액 입력 가능, 소수점 자동 절사
taxTotal string 18 O 세액 합계
└ 정수만 입력 가능
└ 마이너스 금액 입력 가능, 소수점 자동 절사
totalAmount string 18 O 합계금액
└ 정수만 입력 가능
└ 마이너스 금액 입력 가능, 소수점 자동 절사
cash string 18 - 현금
chkBill string 18 - 수표
credit string 18 - 외상
note string 18 - 어음
remark1 string 150 △ 비고1
└ {invoiceeType} = "외국인" 인 경우 필수, 외국인 등록번호 또는 여권번호 입력
remark2 string 150 - 비고2
remark3 string 150 - 비고3
invoicerMgtKey string 24 △ 공급자 문서번호
└ 정발행시 필수, 공급자의 문서 관리를 위해 파트너가 할당하는 식별번호
└ 영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
invoicerCorpNum string 10 O 공급자 사업자번호
└ 하이픈('-') 제외 10자리 숫자값
invoicerTaxRegID string 4 - 공급자 종사업장 식별번호
└ 4자리 숫자값
invoicerCorpName string 200 O 공급자 상호
invoicerCEOName string 100 O 공급자 대표자 성명
invoicerAddr string 300 - 공급자 주소
invoicerBizType string 100 - 공급자 업태
invoicerBizClass string 100 - 공급자 종목
invoicerContactName string 100 - 공급자 담당자 성명
invoicerDeptName string 100 - 공급자 담당자 부서명
invoicerTEL string 20 - 공급자 담당자 연락처
invoicerHP string 20 - 공급자 담당자 휴대폰
invoicerEmail string 100 - 공급자 담당자 이메일
invoicerSMSSendYN bool? - - 공급자 문자전송 여부
└ {issueType} 값이 "정발행" 인 경우, 세금계산서 발행시 알림문자 전송여부 : true / false 중 택 1
└ true : 전송
└ false : 미전송
└ 공급받는자 담당자 휴대폰번호 {invoiceeHP1} 값으로 문자 전송
└ 전송시 포인트 차감되며, 실패시 환불 처리
invoiceeMgtKey string 24 △ 공급받는자 문서번호
└ 역발행시 필수, 공급받는자의 문서 관리를 위해 파트너가 부여하는 식별번호
└ 영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
invoiceeType string - O 공급받는자 구분 : "사업자" / "개인" / "외국인" 중 택 1
invoiceeCorpNum string - O 공급받는자 사업자번호
└ {invoiceeType} = "사업자" 인 경우, 사업자번호 (하이픈 ('-') 제외 10자리)
└ {invoiceeType} = "개인" 인 경우, 주민등록번호 (하이픈 ('-') 제외 13자리)
└ {invoiceeType} = "외국인" 인 경우, "9999999999999" (하이픈 ('-') 제외 13자리)
invoiceeTaxRegID string 4 - 공급받는자 종사업장 식별번호
└ 4자리 숫자값
invoiceeCorpName string 200 O 공급받는자 상호
invoiceeCEOName string 100 O 공급받는자 대표자 성명
invoiceeAddr string 300 - 공급받는자 주소
invoiceeBizType string 100 - 공급받는자 업태
invoiceeBizClass string 100 - 공급받는자 종목
closeDownState int 1 X 공급받는자 휴폐업상태
└ 세금계산서 발행시 팝빌에서 휴폐업조회 하여 결과값 반환
└ null = 미확인, 0 = 미등록, 1 = 사업중, 2 = 폐업, 3 = 휴업, 4 = 확인실패
closeDownStateDate string 8 X 공급받는자 휴폐업일자
└ {closeDownState} 값이 2 or 3일 경우 결과값 반환 (형식 : yyyyMMdd)
invoiceeContactName1 string 100 - 공급받는자 담당자 성명
invoiceeDeptName1 string 100 - 공급받는자 담당자 부서명
invoiceeTEL1 string 20 - 공급받는자 담당자 연락처
invoiceeHP1 string 20 - 공급받는자 담당자 휴대폰
invoiceeEmail1 string 100 - 공급받는자 담당자 이메일
invoiceeSMSSendYN bool? - - 공급받는자 문자전송 여부
└ {issueType} 값이 "역발행" 인 경우, 세금계산서 역발행 요청시 알림문자 전송여부: true / false 중 택 1
└ true : 전송
└ false : 미전송
└ 공급자 담당자 휴대폰번호 {invoicerHP} 값으로 문자 전송
└ 전송시 포인트 차감되며, 실패시 환불 처리
trusteeMgtKey string 24 △ 수탁자 문서번호
└ 위수탁발행시 필수, 수탁자의 문서 관리를 위해 파트너가 부여하는 식별번호
└ 영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
trusteeCorpNum string 10 △ 수탁자 사업자번호
└ 위수탁발행시 필수, 하이픈('-') 제외 10자리 숫자값
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 - 수탁자 담당자 연락처
trusteeHP string 20 - 수탁자 담당자 휴대폰
trusteeEmail string 100 - 수탁자 담당자 이메일
trusteeSMSSendYN bool? - - 수탁자 문자전송 여부
└ {issueType} 값이 "위수탁" 인 경우, 세금계산서 발행시 알림문자 전송여부: true / false 중 택 1
└ true : 전송
└ false : 미전송(기본값)
└ 공급받는자 담당자 휴대폰번호 {invoiceeHP1} 값으로 문자 전송
└ 전송시 포인트 차감되며, 실패시 환불 처리
modifyCode int? 1 △ 수정 사유코드
└ 수정세금계산서 작성시 필수
└ [참고] 수정세금계산서
orgNTSConfirmNum string 24 △ 원본 세금계산서 국세청 승인번호
└ 수정세금계산서 작성시 필수
businessLicenseYN bool? - - 팝빌에 등록된 사업자등록증 첨부 여부 : true / false 중 택 1
└ true = 첨부, false = 미첨부(기본값)
└ 팝빌 사이트 또는 [GetSealURL - 인감 및 첨부문서 등록 팝업 URL]을 이용하여 등록
bankBookYN bool? - - 팝빌에 등록된 통장사본 첨부 여부 : true / false 중 택 1
└ true = 첨부, false = 미첨부(기본값)
└ 팝빌 사이트 또는 [GetSealURL - 인감 및 첨부문서 등록 팝업 URL]을 이용하여 등록
detailList List<TaxinvoiceDetail> - 품목 상세정보 (최대 99건)
addContactList List<TaxinvoiceAddContact> - 공급받는자 추가담당자 정보 (최대 5명)
└ 여러 담당자에게 세금계산서 안내 메일을 보내야할 경우 사용

TaxinvoiceDetail

순번 변수명 타입 길이 필수 비고
serialNum int? 2 O 일련번호
└ 1부터 순차적으로 입력 (최대 99)
purchaseDT string 8 - 거래일자 (형식 : yyyyMMdd)
itemName string 100 - 품명
spec string 60 - 규격
qty string 12 - 수량
└ -99999999.99 ~ 999999999.99
└ 소수점 아래 2번째 자리까지 입력 가능
unitCost string 18 - 단가
└ -99999999999999.99 ~ 999999999999999.99
└ 소수점 아래 2번째 자리까지 입력 가능
supplyCost string 18 - 공급가액
└ 정수만 입력 가능
└ 마이너스 금액 입력 가능, 소수점 자동 절사
tax string 18 - 세액
└ 정수만 입력 가능
└ 마이너스 금액 입력 가능, 소수점 자동 절사
remark string 100 - 비고

TaxinvoiceAddContact

순번 변수명 타입 길이 필수 비고
serialNum int 1 O 일련번호
└ 1부터 순차적으로 입력 (최대 5)
contactName string 100 - 담당자 성명
email string 100 O 이메일

BulkResponse

순번 변수명 타입 길이 비고
code long - API 처리에 대한 응답코드
message string - API 처리에 대한 응답메시지
receiptID string 24 접수아이디
└ 접수 시점에 팝빌에서 자동으로 부여

BulkTaxinvoiceResult

순번 변수명 타입 길이 비고
code long - API 처리에 대한 응답코드
message string - API 처리에 대한 응답메시지
submitID string 36 접수 시점에 고객사에서 부여한 제출아이디
submitCount long - 세금계산서 접수 건수
successCount long - 세금계산서 발행 성공 건수
failCount long - 세금계산서 발행 실패 건수
txState long 1 접수상태 : 0 / 1 / 2 중 반환
└ 0 : 접수
└ 1 : 처리중
└ 2 : 처리완료
txResultCode long - 접수 결과코드
txStartDT string 14 발행처리 시작일시 (형식 : yyyyMMddHHmmss)
txEndDT string 14 발행처리 완료일시 (형식 : yyyyMMddHHmmss)
receiptDT string 14 접수일시 (형식 : yyyyMMddHHmmss)
issueResult List<BulkTaxinvoiceIssueResult> 발행결과
receiptID string 36 접수아이디
└ 접수 시점에 팝빌에서 자동으로 부여

BulkTaxinvoiceIssueResult

순번 변수명 타입 길이 비고
invoicerMgtKey string 24 공급자 문서번호
└ 파트너가 팝빌에 세금계산서를 임시저장 또는 발행시 할당한 문서번호
trusteeMgtKey string 24 수탁자 문서번호
└ 파트너가 할당한 문서번호
code long - API 처리에 대한 응답코드
ntsconfirmNum string 24 국세청승인번호
issueDT string 14 발행일시 (형식 : yyyyMMddHHmmss)

TISearchResult

순번 변수명 타입 길이 비고
code long - API 처리에 대한 응답코드
message string - API 처리에 대한 응답메시지
total string - 총 검색결과 건수
perPage string - 페이지당 검색개수
pageNum string - 페이지 번호
pageCount string - 페이지 개수
list List<TaxinvoiceInfo> 세금계산서 상태/요약정보 (최대 1,000건)
└ 함수 [GetInfo – 상태 확인]의 리턴값 구성과 동일

TaxinvoiceInfo

순번 변수명 타입 길이 비고
itemKey string 18 팝빌에서 세금계산서 관리 목적으로 할당한 식별번호
taxType string 2 과세형태 : "과세" / "영세" / "면세" 중 반환
writeDate string 8 작성일자 (형식 : yyyyMMdd)
regDT string 14 임시저장 일시 (형식 : yyyyMMddHHmmss)
issueType string 3 발행형태 : "정발행" / "역발행" / "위수탁" 중 반환
supplyCostTotal string 18 공급가액 합계
└ 합계 정수만 입력 가능
└ 마이너스 금액 입력 가능, 소수점 아래 자동 절사
taxTotal string 18 세액 합계
└ 정수만 입력 가능
└ 마이너스 금액 입력 가능, 소수점 아래 자동 절사
purposeType string 2 영수/청구 : "영수" / "청구" / "없음" 중 반환
issueDT string 14 발행일시 (형식 : yyyyMMddHHmmss)
lateIssueYN string - 지연발행 여부 : "true" / "false" 중 반환
└ "true" : 지연발행
└ "false" : 정상발행
openYN bool? - 개봉 여부 : true / false 중 반환
└ {issueType} 값이 "정발행" or "위수탁" 인 경우, 공급받는자가 전자세금계산서 보기 버튼을 클릭한 경우 개봉 처리
└ {issueType} 값이 "역발행" 인 경우, 공급자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리
openDT string 14 개봉일시 (형식 : yyyyMMddHHmmss)
stateMemo string 200 상태메모
stateCode int 3 상태코드
└ [참고] 팝빌 상태코드
stateDT string 14 상태 변경일시 (형식 : yyyyMMddHHmmss)
ntsconfirmNum string 24 국세청 승인번호
ntsresult string 6 국세청 전송결과
ntssendDT string 14 국세청 전송일시 (형식 : yyyyMMddHHmmss)
ntsresultDT string 14 국세청 결과 수신일시 (형식 : yyyyMMddHHmmss)
ntssendErrCode string 6 결과코드
└ [참고] 국세청 결과코드
modifyCode int? 1 수정세금계산서 발행시 입력한 사유코드
└ [참고] 수정세금계산서
interOPYN bool? - 연동문서 여부 : true / false 중 반환
└ true : API를 통해 발행한 연동문서
└ false : 팝빌 사이트를 통해 발행한 문서
invoicerCorpName string 200 공급자 상호
invoicerCorpNum string 10 공급자 사업자번호
invoicerMgtKey string 24 공급자 문서번호
└ 파트너가 팝빌에 세금계산서를 임시저장 또는 발행시 할당한 문서번호
invoicerPrintYN bool? - 공급자 인쇄여부 : true / false 중 반환
invoiceeCorpName string 200 공급받는자 상호
invoiceeCorpNum string 10 공급받는자 사업자번호
invoiceeMgtKey string 24 공급받는자 문서번호
└ 파트너가 할당한 문서번호
invoiceePrintYN bool? - 공급받는자 인쇄여부 : true / false 중 반환
closeDownState int? 1 공급받는자 휴폐업상태
  • null미확인
  • 0미등록
  • 1사업중
  • 2폐업
  • 3휴업
  • 4확인실패
closeDownStateDate string 8 공급받는자 휴폐업일자 (형식 : yyyyMMdd)
trusteeCorpName string 200 수탁자 상호
└ 위수탁발행시 필수
trusteeCorpNum string 10 수탁자 사업자번호
trusteeMgtKey string 24 수탁자 문서번호
└ 파트너가 할당한 문서번호
trusteePrintYN bool? - 수탁자 인쇄여부 : true / false 중 반환

TaxinvoiceXML

순번 변수명 타입 길이 비고
code int 3 API 처리에 대한 응답코드
message string 2000 API 처리에 대한 응답메시지
retObject string 3 전자세금계산서 XML 문서

TaxinvoiceLog

순번 변수명 타입 길이 비고
docLogType int 3 로그타입
  • 100임시저장
  • 101수정
  • 102개봉
  • 103수신확인
  • 111메일 재전송
  • 112문자 재전송
  • 113팩스 재전송
  • 122문자 전송결과
  • 123팩스 전송결과
  • 124휴폐업 확인
  • 125문서번호 할당
  • 220역발행요청
  • 221역발행요청 거부
  • 222역발행요청 취소
  • 230발행
  • 240발행취소
  • 250국세청전송 요청
  • 251국세청전송 대기중
  • 252국세청전송 진행중
  • 253국세청전송 접수
  • 254국세청전송 성공
  • 255국세청전송 실패
log string 2000 이력정보
procType string 3 처리형태 : "연동" / "일반" / "시스템" 중 반환
└ "연동" : (API로 처리함)
└ "일반" : (팝빌 사이트에서 처리함)
└ "시스템" : (팝빌이 처리함) 중 반환
procCorpName string 70 처리회사명
procContactName string 30 처리담당자
procMemo string 200 처리메모
regDT string 14 등록일시 (형식 : yyyyMMddHHmmss)
ip string 39 아이피

AttachedFile

순번 변수명 타입 길이 비고
serialNum int 1 첨부파일 일련번호
attachedFile string 255 파일아이디
└ 팝빌이 첨부파일 관리를 위해 할당한 식별번호
└ 함수 [DeleteFile – 첨부파일 삭제]호출을 위한 필수값
displayName string 255 첨부파일명
regDT string 14 첨부일시

EmailConfig

순번 변수명 타입 길이 비고
emailType string 32 발송 메일 유형
  • 정발행
    • TAX_ISSUE공급받는자에게 전자세금계산서가 발행 되었음을 알려주는 메일
    • TAX_ISSUE_INVOICER공급자에게 전자세금계산서가 발행 되었음을 알려주는 메일
    • TAX_CHECK공급자에게 전자세금계산서가 수신확인 되었음을 알려주는 메일
    • TAX_CANCEL_ISSUE공급받는자에게 전자세금계산서가 발행취소 되었음을 알려주는 메일
  • 역발행
    • TAX_REQUEST공급자에게 세금계산서를 전자서명 하여 발행을 요청하는 메일
    • TAX_CANCEL_REQUEST공급받는자에게 세금계산서가 취소 되었음을 알려주는 메일
    • TAX_REFUSE공급받는자에게 세금계산서가 거부 되었음을 알려주는 메일
  • 위수탁 발행
    • TAX_TRUST_ISSUE공급받는자에게 전자세금계산서가 발행 되었음을 알려주는 메일
    • TAX_TRUST_ISSUE_TRUSTEE수탁자에게 전자세금계산서가 발행 되었음을 알려주는 메일
    • TAX_TRUST_ISSUE_INVOICER공급자에게 전자세금계산서가 발행 되었음을 알려주는 메일
    • TAX_TRUST_CANCEL_ISSUE공급받는자에게 전자세금계산서가 발행취소 되었음을 알려주는 메일
    • TAX_TRUST_CANCEL_ISSUE_INVOICER공급자에게 전자세금계산서가 발행취소 되었음을 알려주는 메일
  • 처리결과
    • TAX_CLOSEDOWN거래처의 휴폐업 여부를 확인하여 안내하는 메일
    • TAX_NTSFAIL_INVOICER전자세금계산서 국세청 전송실패를 안내하는 메일
  • 정기발송
    • ETC_CERT_EXPIRATION팝빌에 등록된 인증서의 만료예정을 안내하는 메일
sendYN bool? - 전송여부 : true / false 중 반환
└ true : 전송
└ false : 미전송

TaxinvoiceCertificate

순번 변수명 타입 길이 비고
regDT string 14 등록일시 (형식 : yyyyMMddHHmmss)
└ 인증서를 팝빌 인증서버에 등록한 시간
expireDT string 14 만료일시 (형식 : yyyyMMddHHmmss)
└ 팝빌 인증서버에 등록된 인증서의 만료일시
issuerDN string 200 인증서 발급자 DN
subjectDN string 200 등록된 인증서 DN
issuerName string 12 인증서 종류 : "전자세금용 공동인증서" / "팝빌 특목용 공동인증서" / "기타" 중 반환
oid string 30 OID
regContactName string 100 등록 담당자 성명
└ 팝빌 인증서버에 인증서를 등록한 담당자 성명
regContactID string 50 등록 담당자 아이디
└ 팝빌 인증서버에 인증서를 등록한 담당자 팝빌회원 아이디

ChargeInfo

순번 변수명 타입 길이 비고
unitCost string 12 발행단가
chargeMethod string 3 과금유형 : "연동" / "파트너" 중 반환
rateSystem string 3 과금제도 : "종량제" 반환

JoinForm

순번 변수명 타입 길이 필수 비고
ID string 50 O 아이디
└ 6자 이상 50자 이하
Password string 20 O 비밀번호
└ 8자 이상 20자 이하
└ 영문, 숫자, 특수문자 조합
LinkID string 20 O 파트너 링크아이디
└ 연동신청시 팝빌에서 발급받은 링크아이디
CorpNum string 10 O 사업자번호
└ 하이픈 '-' 제외 10자리 숫자값
CEOName string 100 O 대표자 성명
CorpName string 200 O 회사명
Addr string 300 O 사업장 주소
BizType string 100 O 업태
BizClass string 100 O 종목
ContactName string 100 O 담당자 성명
ContactEmail string 100 O 담당자 이메일
ContactTEL string 20 O 담당자 휴대폰

CorpInfo

순번 변수명 타입 길이 필수 비고
ceoname string 100 O 대표자 성명
corpName string 200 O 회사명
addr string 300 O 주소
bizType string 100 O 업태
bizClass string 100 O 종목

Contact

순번 변수명 타입 길이 필수 비고
id string 50 O 아이디
└ 6자 이상 50자 이하
Password string 20 △ 비밀번호
└ 8자 이상 20자 이하
└ 영문, 숫자, 특수문자 조합
personName string 100 O 담당자 성명
tel string 20 O 담당자 휴대폰
email string 100 O 담당자 이메일
regDT string 14 X 등록일시 (형식 : yyyyMMddHHmmss)
searchRole int 1 - 담당자 권한 : 1 / 2 / 3 중 반환
└ 1 : 개인권한
└ 2 : 읽기권한
└ 3 : 회사권한
mgrYN bool? - X 관리자 여부 : true / false 중 반환
└ true : 관리자
└ false : 담당자
└ 팝빌 사이트 [마이페이지] > [회사정보] > [담당자 관리]에서 수정 가능
state int 1 X 계정상태 : 1 반환
└ 1 : 사용중

EmailPublicKey

순번 변수명 타입 길이 비고
confirmNum string 8 유통사업자 승인번호
email string 40 유통사업자 이메일