POPBill Developers
API Reference

A. 객체정보

Response

순번변수명타입길이설명
code int - API 처리에 대한 응답코드
1성공
message str - API 처리에 대한 응답메시지

IssueResponse

순번변수명타입길이설명
code int - API 처리에 대한 응답코드
1성공
message str - API 처리에 대한 응답메시지
ntsConfirmNum str 24 국세청승인번호
세금계산서 발행 시점에 팝빌에서 자동으로 할당

PopbillException

순번변수명타입길이설명
code int - API 처리 실패에 대한 오류코드
음의 정수 8자리 숫자값 [참고] 오류코드
message str - API 처리 실패에 대한 오류메시지

MgtKeyType

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

Taxinvoice - 입력부

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

Taxinvoice - 출력부

순번변수명타입길이설명
ntsconfirmNum str 24 국세청승인번호
세금계산서 발행 시점에 팝빌에서 자동으로 할당
issueType str 3 발행형태
정발행
역발행
위수탁
taxType str 2 과세형태
과세
영세
면세
chargeDirection str 3 과금방향
정과금 공급자 과금
역과금 공급받는자 과금
serialNum str 30 일련번호
kwon int 4 책번호 "권" 항목
ho int 4 책번호 "호" 항목
writeDate str 8 작성일자
형식 : yyyyMMdd
purposeType str 2 영수/청구
영수
청구
없음
supplyCostTotal str 18 공급가액 합계
taxTotal str 18 세액 합계
totalAmount str 18 합계금액
cash str 18 현금
chkBill str 18 수표
credit str 18 외상
note str 18 어음
remark1 str 150 비고1
remark2 str 150 비고2
remark3 str 150 비고3
invoicerMgtKey str 24 공급자 문서번호
문서 관리를 위해 파트너가 할당하는 고유 식별번호
invoicerCorpNum str 10 공급자 사업자번호 ('-' 제외)
invoicerTaxRegID str 4 공급자 종사업장 식별번호
종사업장 식별번호는 4자리 숫자로만 구성
invoicerCorpName str 200 공급자 상호
invoicerCEOName str 100 공급자 대표자 성명
invoicerAddr str 300 공급자 주소
invoicerBizType str 100 공급자 업태
invoicerBizClass str 100 공급자 종목
invoicerContactName str 100 공급자 담당자 성명
invoicerDeptName str 100 공급자 담당자 부서명
invoicerTEL str 20 공급자 담당자 연락처
invoicerHP str 20 공급자 담당자 휴대폰
invoicerEmail str 100 공급자 담당자 이메일
invoicerSMSSendYN bool - 공급자 알림문자 전송 여부
True전송
False미전송
수신자 : 공급받는자 휴대폰번호 {invoiceeHP1}
invoiceeMgtKey str 24 공급받는자 문서번호
문서 관리를 위해 파트너가 할당하는 고유 식별번호
invoiceeType str 3 공급받는자 유형
사업자
개인
외국인
invoiceeCorpNum str 13 공급받는자 등록번호 ('-' 제외)
- {invoiceeType}="사업자" 경우 사업자번호
- {invoiceeType}="개인" 경우 주민등록번호
- {invoiceeType}="외국인" 경우 "9999999999999"
invoiceeTaxRegID str 4 공급받는자 종사업장 식별번호
종사업장 식별번호는 4자리 숫자로만 구성
invoiceeCorpName str 200 공급받는자 상호
invoiceeCEOName str 100 공급받는자 대표자 성명
invoiceeAddr str 300 공급받는자 주소
invoiceeBizType str 100 공급받는자 업태
invoiceeBizClass str 100 공급받는자 종목
closeDownState int 1 공급받는자 휴폐업상태
  • None미확인
  • 0미등록
  • 1사업중
  • 2폐업
  • 3휴업
  • 4확인실패
세금계산서 발행시 거래처 사업자등록상태조회 하여 결과값 반환
closeDownStateDate str 8 공급받는자 휴폐업일자
형식 : yyyyMMdd
invoiceeContactName1 str 100 공급받는자 담당자 성명
invoiceeDeptName1 str 100 공급받는자 담당자 부서명
invoiceeTEL1 str 20 공급받는자 담당자 연락처
invoiceeHP1 str 20 공급받는자 담당자 휴대폰
invoiceeEmail1 str 100 공급받는자 담당자 이메일
invoiceeSMSSendYN bool - 공급받는자 알림문자 전송 여부
True전송
False미전송
수신자 : 공급자 휴대폰번호 {invoicerHP}
trusteeMgtKey str 24 수탁자 문서번호
수탁자의 문서 관리를 위해 파트너가 할당하는 식별번호
trusteeCorpNum str 10 수탁자 사업자번호 ('-' 제외)
trusteeTaxRegID str 4 수탁자 종사업장 식별번호
종사업장 식별번호는 4자리 숫자로만 구성
trusteeCorpName str 200 수탁자 상호
trusteeCEOName str 100 수탁자 대표자 성명
trusteeAddr str 300 수탁자 주소
trusteeBizType str 100 수탁자 업태
trusteeBizClass str 100 수탁자 종목
trusteeContactName str 100 수탁자 담당자 성명
trusteeDeptName str 100 수탁자 담당자 부서명
trusteeTEL str 20 수탁자 담당자 연락처
trusteeHP str 20 수탁자 담당자 휴대폰
trusteeEmail str 100 수탁자 담당자 이메일
trusteeSMSSendYN bool - 수탁자 알림문자 전송여부
True전송
False미전송
수신자 : 공급받는자 휴대폰번호 {invoiceeHP1}
modifyCode int 1 수정 사유코드
수정세금계산서 작성시 반환 [참고] 수정세금계산서
orgNTSConfirmNum str 24 당초 국세청승인번호
수정세금계산서 작성시 반환
businessLicenseYN bool - 팝빌에 등록된 사업자등록증 첨부 여부
True첨부
False미첨부
bankBookYN bool - 팝빌에 등록된 통장사본 첨부 여부
True첨부
False미첨부
detailList List<TaxinvoiceDetail> 품목 상세정보
최대 : 99개
addContactList List<TaxinvoiceAddContact> 공급받는자 추가담당자 정보
최대 : 5명

TaxinvoiceDetail

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

TaxinvoiceAddContact

순번변수명타입길이필수설명
serialNum int 1 Y 일련번호
1부터 순차적으로 입력
최대 : 5
contactName str 100 N 담당자 성명
email str 100 Y 이메일

BulkResponse

순번변수명타입길이설명
code int - API 처리에 대한 응답코드
1성공
message str - API 처리에 대한 응답메시지
receiptID str 36 접수아이디
접수 시점에 팝빌에서 자동으로 할당

BulkTaxinvoiceResult

순번변수명타입길이설명
code int - API 처리에 대한 응답코드
1성공
message str - API 처리에 대한 응답메시지
submitID str 36 접수 시점에 고객사에서 할당한 제출아이디
submitCount int - 세금계산서 접수 건수
successCount int - 세금계산서 발행 성공 건수
failCount int - 세금계산서 발행 실패 건수
txState int 1 접수상태
0접수
1처리중
2처리완료
txResultCode int - 접수 결과코드
- 성공 : 1
- 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
txStartDT str 14 발행처리 시작일시
형식 : yyyyMMddHHmmss
txEndDT str 14 발행처리 완료일시
형식 : yyyyMMddHHmmss
receiptDT str 14 접수일시
형식 : yyyyMMddHHmmss
issueResult BulkTaxinvoiceIssueResult[ ] 발행결과
receiptID str 36 접수아이디
접수 시점에 팝빌에서 자동으로 할당

BulkTaxinvoiceIssueResult

순번변수명타입길이설명
invoicerMgtKey str 24 공급자 문서번호
공급자의 문서 관리를 위해 파트너가 할당한 식별번호
trusteeMgtKey str 24 수탁자 문서번호
파트너가 할당한 문서번호
code int - API 처리에 대한 응답코드
1성공
message str - API 처리에 대한 응답메시지
ntsconfirmNum str 24 국세청승인번호
세금계산서 발행 시점에 팝빌에서 자동으로 할당
issueDT str 14 발행일시
형식 : yyyyMMddHHmmss

TISearchResult

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

TaxinvoiceInfo

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

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 str 2000 이력정보
procType str 3 처리형태
연동API를 통해 처리함
일반팝빌 사이트를 통해 처리함
시스템팝빌이 처리함
procCorpName str 70 처리회사명
procContactName str 30 처리담당자
procMemo str 200 처리메모
regDT str 14 등록일시
형식 : yyyyMMddHHmmss
ip str 39 아이피

TaxinvoiceXML

순번변수명타입길이설명
code int - API 처리에 대한 응답코드
1성공
message str - API 처리에 대한 응답메시지
retObject str - 전자세금계산서 XML 문서

AttachedFile

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

EmailSendConfig

순번변수명타입길이설명
emailType str 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미전송

TaxinvoiceCertificate

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