# 정보확인 ## 1. GetInfo - 상태 확인 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | | GET | | | - 세금계산서 1건의 상태 및 요약정보를 확인합니다. - 리턴값 `stateCode`를 통해 세금계산서의 상태코드를 확인합니다. [\[참고\] 팝빌 상태코드](https://developers.popbill.com/api-reference/taxinvoice/response-code#state-code) ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/taxinvoice/getting-started/authorization "_blank") - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - MgtKeyType `type: string` `length: -` `required: Y` `description: 문서번호 유형 (택 1)` - `SELL`: 매출 - `BUY`: 매입 - `TRUSTEE`: 위수탁 - MgtKey `type: string` `length: 24` `required: Y` `description: 파트너가 할당한 문서번호` **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/Taxinvoice/{MgtKeyType}/{MgtKey}' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - itemKey `type: string` `length: 18` `description: 팝빌에서 할당한 식별번호` - taxType `type: string` `length: 2` `description: 과세형태` - `과세` - `영세` - `면세` - writeDate `type: string` `length: 8` `description: 작성일자` - 형식 : yyyyMMdd - regDT `type: string` `length: 14` `description: 임시저장 일시` - 형식 : yyyyMMddHHmmss - issueType `type: string` `length: 3` `description: 발행형태` - `정발행` - `역발행` - `위수탁` - supplyCostTotal `type: string` `length: 18` `description: 공급가액 합계` - 정수만 입력 가능\ 마이너스 금액 입력 가능, 소수점 아래 자동 절사 - taxTotal `type: string` `length: 18` `description: 세액 합계` - 정수만 입력 가능\ 마이너스 금액 입력 가능, 소수점 아래 자동 절사 - purposeType `type: string` `length: 2` `description: 영수/청구` - `영수` - `청구` - `없음` - issueDT `type: string` `length: 14` `description: 발행일시` - 형식 : yyyyMMddHHmmss - lateIssueYN `type: boolean` `length: -` `description: 지연발행 여부` - `true`: 지연발행 - `false`: 정상발행 - openYN `type: boolean` `length: -` `description: 개봉 여부` - `true`: 개봉 - `false`: 미개봉 - {issueType}="정발행" or "위수탁" 경우 공급받는자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리 - {issueType}="역발행" 경우 공급자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리 - openDT `type: string` `length: 14` `description: 개봉일시` - 형식 : yyyyMMddHHmmss - stateMemo `type: string` `length: 200` `description: 상태메모` - stateCode `type: string` `length: 3` `description: 상태코드` - [\[참고\] 팝빌 상태코드](https://developers.popbill.com/api-reference/taxinvoice/response-code#state-code) - stateDT `type: string` `length: 14` `description: 상태 변경일시` - 형식 : yyyyMMddHHmmss - ntsconfirmNum `type: string` `length: 18` `description: 국세청승인번호` - 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당 - ntsresult `type: string` `length: 6` `description: 국세청 전송결과` - ntssendDT `type: string` `length: 14` `description: 국세청 전송일시` - 형식 : yyyyMMddHHmmss - ntsresultDT `type: string` `length: 14` `description: 국세청 결과 수신일시` - 형식 : yyyyMMddHHmmss - ntssendErrCode `type: string` `length: 6` `description: 국세청 결과코드` - [\[참고\] 국세청 결과코드](https://developers.popbill.com/api-reference/taxinvoice/response-code#nts-result) - modifyCode `type: number` `length: 1` `description: 수정세금계산서 발행시 입력한 사유코드` - [\[참고\] 수정세금계산서](https://developers.popbill.com/guide/taxinvoice/introduction/modified-taxinvoice) - interOPYN `type: boolean` `length: -` `description: 연동문서 여부` - `true`: API를 통해 발행한 연동문서 - `false`: 팝빌 사이트를 통해 발행한 문서 - invoicerCorpName `type: string` `length: 200` `description: 공급자 상호` - invoicerCorpNum `type: string` `length: 10` `description: 공급자 사업자번호` - invoicerMgtKey `type: string` `length: 24` `description: 공급자 문서번호` - 파트너가 할당한 문서번호 - invoicerPrintYN `type: boolean` `length: -` `description: 공급자 인쇄여부` - `true`: 인쇄 - `false`: 미인쇄 - invoiceeCorpName `type: string` `length: 200` `description: 공급받는자 상호` - invoiceeCorpNum `type: string` `length: 13` `description: 공급받는자 사업자번호` - invoiceeMgtKey `type: string` `length: 24` `description: 공급받는자 문서번호` - 파트너가 할당한 문서번호 - invoiceePrintYN `type: boolean` `length: -` `description: 공급받는자 인쇄여부` - `true`: 인쇄 - `false`: 미인쇄 - closeDownState `type: number` `length: 1` `description: 공급받는자 휴폐업상태` - `null`: 미확인 - `0`: 미등록 - `1`: 사업중 - `2`: 폐업 - `3`: 휴업 - `4`: 확인실패 - closeDownStateDate `type: string` `length: 8` `description: 공급받는자 휴폐업일자` - 형식 : yyyyMMdd - trusteeCorpName `type: string` `length: 200` `description: 수탁자 상호` - trusteeCorpNum `type: string` `length: 10` `description: 수탁자 사업자번호` - trusteeMgtKey `type: string` `length: 24` `description: 수탁자 문서번호` - 파트너가 할당한 문서번호 - trusteePrintYN `type: boolean` `length: -` `description: 수탁자 인쇄여부` - `true`: 인쇄 - `false`: 미인쇄 **응답 예시** ```json { "invoiceePrintYN": false, "openYN": false, "taxType": "과세", "invoicerCorpNum": "1234567890", "invoicerMgtKey": "MKGTKEY-0002", "invoicerCorpName": "공급자 상호", "invoicerPrintYN": false, "invoiceeCorpName": "공급받는자 상호", "trusteePrintYN": false, "taxTotal": "1000", "supplyCostTotal": "10000", "purposeType": "영수", "ntsconfirmNum": "202510168888888800000002", "closeDownState": 0, "lateIssueYN": false, "stateCode": 300, "interOPYN": true, "itemKey": "025102114360700001", "issueDT": "20251021143607", "stateDT": "20251021143608", "regDT": "20251021143608", "invoiceeCorpNum": "1234567890", "issueType": "정발행", "writeDate": "20251016" } ``` ## 2. GetInfos - 다수건 상태 확인 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ------------------------------------------------------------ | ------------------------------------------------------- | | POST | | | - 다수건의 세금계산서 상태 및 요약 정보를 확인합니다. (1회 호출에 최대 1,000건 확인 가능) - 리턴값의 변수 `stateCode`를 통해 세금계산서의 상태코드를 확인합니다. [\[참고\] 팝빌 상태코드](https://developers.popbill.com/api-reference/taxinvoice/response-code#state-code) > 문서번호를 통해 세금계산서 목록을 구현하는 경우 활용합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/taxinvoice/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - MgtKeyType `type: string` `length: -` `required: Y` `description: 문서번호 유형 (택 1)` - `SELL`: 매출 - `BUY`: 매입 - `TRUSTEE`: 위수탁 **요청 본문** - \- `type: array` `length: 1,000` `required: Y` `description: 문서번호 목록` - 최대 : 1,000건 **요청 예시** ```bash curl --request POST \ --url 'https://{domain}/Taxinvoice/{MgtKeyType}' \ --header 'Authorization: Bearer {token}' \ --data '["TEST0001", "TEST0002"]' ``` ### Response **응답 본문** - itemKey `type: string` `length: 18` `description: 팝빌에서 할당한 식별번호` - taxType `type: string` `length: 2` `description: 과세형태` - `과세` - `영세` - `면세` - writeDate `type: string` `length: 8` `description: 작성일자` - 형식 : yyyyMMdd - regDT `type: string` `length: 14` `description: 임시저장 일시` - 형식 : yyyyMMddHHmmss - issueType `type: string` `length: 3` `description: 발행형태` - `정발행` - `역발행` - `위수탁` - supplyCostTotal `type: string` `length: 18` `description: 공급가액 합계` - 정수만 입력 가능\ 마이너스 금액 입력 가능, 소수점 아래 자동 절사 - taxTotal `type: string` `length: 18` `description: 세액 합계` - 정수만 입력 가능\ 마이너스 금액 입력 가능, 소수점 아래 자동 절사 - purposeType `type: string` `length: 2` `description: 영수/청구` - `영수` - `청구` - `없음` - issueDT `type: string` `length: 14` `description: 발행일시` - 형식 : yyyyMMddHHmmss - lateIssueYN `type: boolean` `length: -` `description: 지연발행 여부` - `true`: 지연발행 - `false`: 정상발행 - openYN `type: boolean` `length: -` `description: 개봉 여부` - `true`: 개봉 - `false`: 미개봉 - {issueType}="정발행" or "위수탁" 경우 공급받는자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리 - {issueType}="역발행" 경우 공급자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리 - openDT `type: string` `length: 14` `description: 개봉일시` - 형식 : yyyyMMddHHmmss - stateMemo `type: string` `length: 200` `description: 상태메모` - stateCode `type: string` `length: 3` `description: 상태코드` - [\[참고\] 팝빌 상태코드](https://developers.popbill.com/api-reference/taxinvoice/response-code#state-code) - stateDT `type: string` `length: 14` `description: 상태 변경일시` - 형식 : yyyyMMddHHmmss - ntsconfirmNum `type: string` `length: 18` `description: 국세청승인번호` - 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당 - ntsresult `type: string` `length: 6` `description: 국세청 전송결과` - ntssendDT `type: string` `length: 14` `description: 국세청 전송일시` - 형식 : yyyyMMddHHmmss - ntsresultDT `type: string` `length: 14` `description: 국세청 결과 수신일시` - 형식 : yyyyMMddHHmmss - ntssendErrCode `type: string` `length: 6` `description: 국세청 결과코드` - [\[참고\] 국세청 결과코드](https://developers.popbill.com/api-reference/taxinvoice/response-code#nts-result) - modifyCode `type: number` `length: 1` `description: 수정세금계산서 발행시 입력한 사유코드` - [\[참고\] 수정세금계산서](https://developers.popbill.com/guide/taxinvoice/introduction/modified-taxinvoice) - interOPYN `type: boolean` `length: -` `description: 연동문서 여부` - `true`: API를 통해 발행한 연동문서 - `false`: 팝빌 사이트를 통해 발행한 문서 - invoicerCorpName `type: string` `length: 200` `description: 공급자 상호` - invoicerCorpNum `type: string` `length: 10` `description: 공급자 사업자번호` - invoicerMgtKey `type: string` `length: 24` `description: 공급자 문서번호` - 파트너가 할당한 문서번호 - invoicerPrintYN `type: boolean` `length: -` `description: 공급자 인쇄여부` - `true`: 인쇄 - `false`: 미인쇄 - invoiceeCorpName `type: string` `length: 200` `description: 공급받는자 상호` - invoiceeCorpNum `type: string` `length: 13` `description: 공급받는자 사업자번호` - invoiceeMgtKey `type: string` `length: 24` `description: 공급받는자 문서번호` - 파트너가 할당한 문서번호 - invoiceePrintYN `type: boolean` `length: -` `description: 공급받는자 인쇄여부` - `true`: 인쇄 - `false`: 미인쇄 - closeDownState `type: number` `length: 1` `description: 공급받는자 휴폐업상태` - `null`: 미확인 - `0`: 미등록 - `1`: 사업중 - `2`: 폐업 - `3`: 휴업 - `4`: 확인실패 - closeDownStateDate `type: string` `length: 8` `description: 공급받는자 휴폐업일자` - 형식 : yyyyMMdd - trusteeCorpName `type: string` `length: 200` `description: 수탁자 상호` - trusteeCorpNum `type: string` `length: 10` `description: 수탁자 사업자번호` - trusteeMgtKey `type: string` `length: 24` `description: 수탁자 문서번호` - 파트너가 할당한 문서번호 - trusteePrintYN `type: boolean` `length: -` `description: 수탁자 인쇄여부` - `true`: 인쇄 - `false`: 미인쇄 **응답 예시** ```json [ { "invoiceePrintYN": false, "openYN": false, "taxType": "과세", "invoicerCorpNum": "1234567890", "invoicerMgtKey": "MKGTKEY-0002", "invoicerCorpName": "공급자 상호", "invoicerPrintYN": false, "invoiceeCorpName": "공급받는자 상호", "trusteePrintYN": false, "taxTotal": "1000", "supplyCostTotal": "10000", "purposeType": "영수", "ntsconfirmNum": "202510168888888800000002", "closeDownState": 0, "lateIssueYN": false, "stateCode": 300, "interOPYN": true, "itemKey": "025102114360700001", "issueDT": "20251021143607", "stateDT": "20251021143608", "regDT": "20251021143608", "invoiceeCorpNum": "1234567890", "issueType": "정발행", "writeDate": "20251016" } ] ``` ## 3. GetDetailInfo - 상세정보 확인 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | | GET | | | - 세금계산서 1건의 상세정보를 확인합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/taxinvoice/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - MgtKeyType `type: string` `length: -` `required: Y` `description: 문서번호 유형 (택 1)` - `SELL`: 매출 - `BUY`: 매입 - `TRUSTEE`: 위수탁 - MgtKey `type: string` `length: 24` `required: Y` `description: 파트너가 할당한 문서번호` **Query 파라미터** - Detail `type: -` `length: -` `required: Y` `description: 상세 정보` - 빈값으로 입력 **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/Taxinvoice/{MgtKeyType}/{MgtKey}?Detail' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - ntsconfirmNum `type: string` `length: 24` `description: 국세청승인번호` - 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당 - issueType `type: string` `length: 3` `description: 발행형태` - `정발행` - `역발행` - `위수탁` - taxType `type: string` `length: 2` `description: 과세형태` - `과세` - `영세` - `면세` - chargeDirection `type: string` `length: 3` `description: 과금방향` - `정과금`: 공급자 과금 - `역과금`: 공급받는자 과금 - serialNum `type: string` `length: 30` `description: 일련번호` - kwon `type: number` `length: 4` `description: 책번호 "권" 항목` - ho `type: number` `length: 4` `description: 책번호 "호" 항목` - writeDate `type: string` `length: 8` `description: 작성일자` - 형식 : yyyyMMdd - purposeType `type: string` `length: 2` `description: 영수/청구` - `영수` - `청구` - `없음` - supplyCostTotal `type: string` `length: 18` `description: 공급가액 합계` - taxTotal `type: string` `length: 18` `description: 세액 합계` - totalAmount `type: string` `length: 18` `description: 합계금액` - cash `type: string` `length: 18` `description: 현금` - chkBill `type: string` `length: 18` `description: 수표` - credit `type: string` `length: 18` `description: 외상` - note `type: string` `length: 18` `description: 어음` - remark1 `type: string` `length: 150` `description: 비고1` - {invoiceeType}="외국인"\ 경우 외국인등록번호 또는 여권번호 필수 입력 - remark2 `type: string` `length: 150` `description: 비고2` - remark3 `type: string` `length: 150` `description: 비고3` - invoicerMgtKey `type: string` `length: 24` `description: 공급자 문서번호` - 문서 관리를 위해 파트너가 할당하는 고유 식별번호 - invoicerCorpNum `type: string` `length: 10` `description: 공급자 사업자번호` - invoicerTaxRegID `type: string` `length: 4` `description: 공급자 종사업장 식별번호` - invoicerCorpName `type: string` `length: 200` `description: 공급자 상호` - invoicerCEOName `type: string` `length: 100` `description: 공급자 대표자 성명` - invoicerAddr `type: string` `length: 300` `description: 공급자 주소` - invoicerBizType `type: string` `length: 100` `description: 공급자 업태` - invoicerBizClass `type: string` `length: 100` `description: 공급자 종목` - invoicerContactName `type: string` `length: 100` `description: 공급자 담당자 성명` - invoicerDeptName `type: string` `length: 100` `description: 공급자 담당자 부서명` - invoicerTEL `type: string` `length: 20` `description: 공급자 담당자 연락처` - invoicerHP `type: string` `length: 20` `description: 공급자 담당자 휴대폰` - invoicerEmail `type: string` `length: 100` `description: 공급자 담당자 메일` - invoicerSMSSendYN `type: boolean` `length: -` `description: 공급자 알림문자 전송 여부` - `true`: 전송 - `false`: 미전송 - 수신자 : 공급받는자 휴대폰번호 {invoiceeHP1} - invoiceeMgtKey `type: string` `length: 24` `description: 공급받는자 문서번호` - 문서 관리를 위해 파트너가 할당하는 고유 식별번호 - invoiceeType `type: string` `length: 3` `description: 공급받는자 유형` - `사업자` - `개인` - `외국인` - invoiceeCorpNum `type: string` `length: 13` `description: 공급받는자 등록번호` - {invoiceeType}="사업자" 경우 사업자번호 - {invoiceeType}="개인" 경우 주민등록번호 - {invoiceeType}="외국인" 경우 "9999999999999" - invoiceeTaxRegID `type: string` `length: 4` `description: 공급받는자 종사업장 식별번호` - invoiceeCorpName `type: string` `length: 200` `description: 공급받는자 상호` - invoiceeCEOName `type: string` `length: 100` `description: 공급받는자 대표자 성명` - invoiceeAddr `type: string` `length: 300` `description: 공급받는자 주소` - invoiceeBizType `type: string` `length: 100` `description: 공급받는자 업태` - invoiceeBizClass `type: string` `length: 100` `description: 공급받는자 종목` - closeDownState `type: number` `length: 1` `description: 공급받는자 휴폐업상태` - `null`: 미확인 - `0`: 미등록 - `1`: 사업중 - `2`: 폐업 - `3`: 휴업 - `4`: 확인실패 - 세금계산서 발행시 거래처 사업자등록 상태를 조회하여 결과값 반환 - closeDownStateDate `type: string` `length: 8` `description: 공급받는자 휴폐업일자` - 형식 : yyyyMMdd - invoiceeContactName1 `type: string` `length: 100` `description: 공급받는자 담당자 성명` - invoiceeDeptName1 `type: string` `length: 100` `description: 공급받는자 담당자 부서명` - invoiceeTEL1 `type: string` `length: 20` `description: 공급받는자 담당자 연락처` - invoiceeHP1 `type: string` `length: 20` `description: 공급받는자 담당자 휴대폰` - invoiceeEmail1 `type: string` `length: 100` `description: 공급받는자 담당자 메일` - invoiceeSMSSendYN `type: boolean` `length: -` `description: 공급받는자 알림문자 전송 여부` - `true`: 전송 - `false`: 미전송 - 수신자 : 공급자 휴대폰번호 {invoicerHP} - trusteeMgtKey `type: string` `length: 24` `description: 수탁자 문서번호` - 수탁자의 문서 관리를 위해 파트너가 할당하는 식별번호 - trusteeCorpNum `type: string` `length: 10` `description: 수탁자 사업자번호` - trusteeTaxRegID `type: string` `length: 4` `description: 수탁자 종사업장 식별번호` - trusteeCorpName `type: string` `length: 200` `description: 수탁자 상호` - trusteeCEOName `type: string` `length: 100` `description: 수탁자 대표자 성명` - trusteeAddr `type: string` `length: 300` `description: 수탁자 주소` - trusteeBizType `type: string` `length: 100` `description: 수탁자 업태` - trusteeBizClass `type: string` `length: 100` `description: 수탁자 종목` - trusteeContactName `type: string` `length: 100` `description: 수탁자 담당자 성명` - trusteeDeptName `type: string` `length: 100` `description: 수탁자 담당자 부서명` - trusteeTEL `type: string` `length: 20` `description: 수탁자 담당자 연락처` - trusteeHP `type: string` `length: 20` `description: 수탁자 담당자 휴대폰` - trusteeEmail `type: string` `length: 100` `description: 수탁자 담당자 메일` - trusteeSMSSendYN `type: boolean` `length: -` `description: 수탁자 알림문자 전송 여부` - `true`: 전송 - `false`: 미전송 - 수신자 : 공급받는자 휴대폰번호 {invoiceeHP1} - modifyCode `type: number` `length: 1` `description: 수정 사유코드` - 수정세금계산서 작성시 필수 [\[참고\] 수정세금계산서](https://developers.popbill.com/guide/taxinvoice/introduction/modified-taxinvoice) - orgNTSConfirmNum `type: string` `length: 24` `description: 당초 국세청승인번호` - 수정세금계산서 작성시 반환 - businessLicenseYN `type: boolean` `length: -` `description: 팝빌에 등록된 사업자등록증 첨부 여부` - `true`: 첨부 - `false`: 미첨부 - bankBookYN `type: boolean` `length: -` `description: 팝빌에 등록된 통장사본 첨부 여부` - `true`: 첨부 - `false`: 미첨부 - detailList `type: array` `length: -` `description: 품목 상세정보` - 최대 : 99개 - serialNum `type: number` `length: 2` `description: 일련번호` - purchaseDT `type: string` `length: 8` `description: 거래일자` - 형식 : yyyyMMdd - itemName `type: string` `length: 100` `description: 품명` - spec `type: string` `length: 60` `description: 규격` - qty `type: string` `length: 12` `description: 수량` - -99999999.99 \~ 999999999.99\ 소수점 아래 2번째 자리까지 입력 가능 - unitCost `type: string` `length: 18` `description: 단가` - -99999999999999.99 \~ 999999999999999.99\ 소수점 아래 2번째 자리까지 입력 가능 - supplyCost `type: string` `length: 18` `description: 공급가액` - 정수만 입력 가능\ 마이너스 금액 입력 가능, 소수점 자동 절사 - tax `type: string` `length: 18` `description: 세액` - 정수만 입력 가능\ 마이너스 금액 입력 가능, 소수점 자동 절사 - remark `type: string` `length: 100` `description: 비고` - addContactList `type: array` `length: -` `description: 공급받는자 추가담당자 정보` - 최대 : 5명 - serialNum `type: number` `length: 1` `description: 일련번호` - contactName `type: string` `length: 100` `description: 담당자 성명` - email `type: string` `length: 100` `description: 메일` **응답 예시** ```json { "writeSpecification": false, "writeDate": "20251016", "chargeDirection": "정과금", "issueType": "정발행", "issueTiming": "직접발행", "taxType": "과세", "invoicerCorpNum": "1234567890", "invoicerMgtKey": "MKGTKEY-0002", "invoicerTaxRegID": "0001", "invoicerCorpName": "공급자 상호", "invoicerCEOName": "공급자 대표자 성명", "invoicerAddr": "공급자 주소", "invoicerBizClass": "공급자 종목", "invoicerBizType": "공급자 업태", "invoicerContactName": "공급자 담당자 성명", "invoicerDeptName": "공급자 담당자 부서명", "invoicerTEL": "010-1234-5678", "invoicerHP": "010-1234-5678", "invoicerEmail": "test@test.com", "invoicerSMSSendYN": false, "invoiceeCorpNum": "1234567890", "invoiceeType": "사업자", "invoiceeTaxRegID": "0001", "invoiceeCorpName": "공급받는자 상호", "invoiceeCEOName": "공급받는자 대표자 성명", "invoiceeAddr": "공급받는자 주소", "invoiceeBizType": "공급받는자 업태", "invoiceeBizClass": "공급받는자 종목", "invoiceeContactName1": "공급받는자 담당자 성명", "invoiceeDeptName1": "공급받는자 담당자 부서명", "invoiceeTEL1": "010-1234-5678", "invoiceeHP1": "010-1234-5678", "invoiceeEmail1": "test@test.com", "invoiceeSMSSendYN": false, "trusteeSMSSendYN": false, "taxTotal": "1000", "supplyCostTotal": "10000", "totalAmount": "11000", "purposeType": "영수", "businessLicenseYN": false, "bankBookYN": false, "faxsendYN": false, "ntsconfirmNum": "202510168888888800000002", "detailList": [ { "serialNum": 1, "purchaseDT": "20251016", "itemName": "품명", "spec": "규격", "qty": "1", "unitCost": "10000", "supplyCost": "10000", "tax": "1000", "remark": "비고" } ], "addContactList": [ { "serialNum": 1, "contactName": "담당자 성명", "email": "test@test.com" } ], "closeDownState": 0 } ``` ## 4. CheckMgtKeyInUse - 문서번호 사용 여부 확인 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | | GET | | | - 파트너가 세금계산서 관리 목적으로 할당하는 문서번호의 사용여부를 확인합니다. - 응답 본문의 itemKey 필드에 값이 존재하면 사용 중인 문서번호이며, 값이 존재하지 않으면 사용 가능한 문서번호 입니다. - 이미 사용 중인 문서번호는 중복 사용이 불가하고, 세금계산서가 삭제된 경우에만 문서번호의 재사용이 가능합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/taxinvoice/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - MgtKeyType `type: string` `length: -` `required: Y` `description: 문서번호 유형 (택 1)` - `SELL`: 매출 - `BUY`: 매입 - `TRUSTEE`: 위수탁 - MgtKey `type: string` `length: 24` `required: Y` `description: 파트너가 할당한 문서번호` **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/Taxinvoice/{MgtKeyType}/{MgtKey}' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - itemKey `type: string` `length: 18` `description: 팝빌에서 할당한 식별번호` **응답 예시** ```json { "itemKey": "025102114360700001" } ``` ## 5. GetXML - 상세정보 확인(XML) | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | | GET | | | - 세금계산서 1건의 상세정보를 XML로 반환합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/taxinvoice/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - MgtKeyType `type: string` `length: -` `required: Y` `description: 문서번호 유형 (택 1)` - `SELL`: 매출 - `BUY`: 매입 - `TRUSTEE`: 위수탁 - MgtKey `type: string` `length: 24` `required: Y` `description: 파트너가 할당한 문서번호` **Query 파라미터** - XML `type: -` `length: -` `required: Y` `description: XML` - 빈값으로 입력 **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/Taxinvoice/{MgtKeyType}/{MgtKey}?XML' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` - retObject `type: string` `length: -` `description: 전자세금계산서 XML 문서` **응답 예시** ```json { "code": 1, "message": "확인완료", "retObject": "\n | | - 검색조건에 해당하는 세금계산서를 조회합니다. (최대 조회기간 : 6개월) > 매개변수 Page, PerPage, Order를 이용하여 페이징 기능을 구현할 수 있습니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/taxinvoice/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - MgtKeyType `type: string` `length: -` `required: Y` `description: 문서번호 유형 (택 1)` - `SELL`: 매출 - `BUY`: 매입 - `TRUSTEE`: 위수탁 **Query 파라미터** - DType `type: string` `length: 1` `required: Y` `description: 검색일자 유형 (택 1)` - `R`: 등록일자 - `W`: 작성일자 - `I`: 발행일자 - SDate `type: string` `length: 8` `required: Y` `description: 검색 시작일자` - 형식 : yyyyMMdd - EDate `type: string` `length: 8` `required: Y` `description: 검색 종료일자` - 형식 : yyyyMMdd - State `type: string` `length: -` `required: N` `description: 세금계산서 상태코드` - 2, 3번째 자리에 와일드카드(\*) 사용가능. 예) 3\*\*,60\* [\[참고\] 팝빌 상태코드](https://developers.popbill.com/api-reference/taxinvoice/response-code#state-code) - 기본값 : 전체조회 - Type `type: string` `length: -` `required: N` `description: 세금계산서 문서 유형 (다중 선택 가능)` - `N`: 세금계산서 - `M`: 수정세금계산서 - 다중 선택시 콤마(',')로 구분. 예) N,M - 기본값 : 전체조회 - TaxType `type: string` `length: -` `required: N` `description: 과세형태 (다중 선택 가능)` - `T`: 과세 - `N`: 면세 - `Z`: 영세 - 다중 선택시 콤마(',')로 구분. 예) T,N - 기본값 : 전체조회 - IssueType `type: string` `length: -` `required: N` `description: 발행형태 (다중 선택 가능)` - `N`: 정발행 - `R`: 역발행 - `T`: 위수탁 - 다중 선택시 콤마(',')로 구분. 예) N,R - 기본값 : 전체조회 - LateOnly `type: boolean` `length: -` `required: N` `description: 지연발행 여부` - `true`: 지연발행 - `false`: 정상발행 - 기본값 : 전체조회 - TaxRegIDType `type: string` `length: 1` `required: N` `description: 종사업장번호의 주체 (택 1)` - `S`: 공급자 - `B`: 공급받는자 - `T`: 수탁자 - 기본값 : 전체조회 - TaxRegID `type: string` `length: -` `required: N` `description: 종사업장번호` - 다수건 검색시 콤마(',')로 구분. 예) 1234,1000 - 기본값 : 전체조회 - TaxRegIDYN `type: string` `length: 1` `required: N` `description: 종사업장번호 유무` - `0`: 없음 - `1`: 있음 - 기본값 : 전체조회 - QString `type: string` `length: -` `required: N` `description: 조회 검색어 ('-' 제외)` - 상호명 조회시 거래처상호 입력 - 사업자 조회시 사업자번호 입력 - 개인 조회시 주민등록번호 입력 - 외국인 조회시 "9999999999999" 입력 - 기본값 : 전체조회 - Page `type: number` `length: -` `required: N` `description: 목록 페이지번호` - 기본값 : 1 - PerPage `type: number` `length: -` `required: N` `description: 페이지당 표시할 목록 건수` - 최대 : 1,000건 - 기본값 : 500건 - Order `type: string` `length: 1` `required: N` `description: 조회 기준일자 유형을 기준으로 하는 목록 정렬 방향` - `D`: 내림차순 : 기본값 - `A`: 오름차순 - InterOPYN `type: string` `length: 1` `required: N` `description: 세금계산서 작성유형` - `0`: 팝빌 사이트를 통해 작성한 세금계산서 - `1`: API로 작성한 세금계산서 - 기본값 : 전체조회 - RegType `type: string` `length: -` `required: N` `description: 전자세금계산서 등록 유형 (다중 선택 가능)` - `P`: 팝빌에서 등록(발행) - `H`: 홈택스 또는 ASP에서 등록(발행) - 다중 선택시 콤마(',')로 구분. 예) P,H - 기본값 : 전체조회 - CloseDownState `type: string` `length: -` `required: N` `description: 휴폐업상태 (다중 선택 가능)` - `N`: 미확인 - `0`: 미등록 - `1`: 사업중 - `2`: 폐업 - `3`: 휴업 - `4`: 확인실패 - 다중 선택시 콤마(',')로 구분. 예) N,0 - 기본값 : 전체조회 - MgtKey `type: string` `length: -` `required: N` `description: 문서번호` - 세금계산서의 문서번호 또는 국세청승인번호 중 검색하고자 하는 정보 입력 - 기본값 : 전체조회 **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/Taxinvoice/{MgtKeyType}?DType={DType}&SDate={SDate}&EDate={EDate}' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - code `type: number` `length: -` `description: API 처리에 대한 응답코드` - `1`: 성공 - message `type: string` `length: -` `description: API 처리에 대한 응답메시지` - total `type: number` `length: -` `description: 총 검색결과 건수` - perPage `type: number` `length: -` `description: 페이지당 목록 건수` - pageNum `type: number` `length: -` `description: 페이지 번호` - pageCount `type: number` `length: -` `description: 페이지 개수` - list `type: array` `length: -` `description: 세금계산서 상태/요약정보` - 함수 [\[GetInfo – 상태 확인\]](#GetInfo)의 리턴값 구성과 동일 - 최대 : 1,000건 - itemKey `type: string` `length: 18` `description: 팝빌에서 할당한 식별번호` - taxType `type: string` `length: 2` `description: 과세형태` - `과세` - `영세` - `면세` - writeDate `type: string` `length: 8` `description: 작성일자` - 형식 : yyyyMMdd - regDT `type: string` `length: 14` `description: 임시저장 일시` - 형식 : yyyyMMddHHmmss - issueType `type: string` `length: 3` `description: 발행형태` - `정발행` - `역발행` - `위수탁` - supplyCostTotal `type: string` `length: 18` `description: 공급가액 합계` - 정수만 입력 가능 - 마이너스 금액 입력 가능, 소수점 아래 자동 절사 - taxTotal `type: string` `length: 18` `description: 세액 합계` - 정수만 입력 가능 - 마이너스 금액 입력 가능, 소수점 아래 자동 절사 - purposeType `type: string` `length: 2` `description: 영수/청구` - `영수` - `청구` - `없음` - issueDT `type: string` `length: 14` `description: 발행일시` - 형식 : yyyyMMddHHmmss - lateIssueYN `type: boolean` `length: -` `description: 지연발행 여부` - `true`: 지연발행 - `false`: 정상발행 - openYN `type: boolean` `length: -` `description: 개봉 여부` - `true`: 개봉 - `false`: 미개봉 - {issueType}="정발행" or "위수탁" 경우 공급받는자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리 - {issueType}="역발행" 경우 공급자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리 - openDT `type: string` `length: 14` `description: 개봉일시` - 형식 : yyyyMMddHHmmss - stateMemo `type: string` `length: 200` `description: 상태메모` - stateCode `type: string` `length: 3` `description: 상태코드` - [\[참고\] 팝빌 상태코드](https://developers.popbill.com/api-reference/taxinvoice/response-code#state-code) - stateDT `type: string` `length: 14` `description: 상태 변경일시` - 형식 : yyyyMMddHHmmss - ntsconfirmNum `type: string` `length: 18` `description: 국세청승인번호` - 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당 - ntsresult `type: string` `length: 6` `description: 국세청 전송결과` - ntssendDT `type: string` `length: 14` `description: 국세청 전송일시` - 형식 : yyyyMMddHHmmss - ntsresultDT `type: string` `length: 14` `description: 국세청 결과 수신일시` - 형식 : yyyyMMddHHmmss - ntssendErrCode `type: string` `length: 6` `description: 국세청 결과코드` - [\[참고\] 국세청 결과코드](https://developers.popbill.com/api-reference/taxinvoice/response-code#nts-result) - modifyCode `type: number` `length: 1` `description: 수정세금계산서 발행시 입력한 사유코드` - [\[참고\] 수정세금계산서](https://developers.popbill.com/guide/taxinvoice/introduction/modified-taxinvoice) - interOPYN `type: boolean` `length: -` `description: 연동문서 여부` - `true`: API를 통해 발행한 연동문서 - `false`: 팝빌 사이트를 통해 발행한 문서 - invoicerCorpName `type: string` `length: 200` `description: 공급자 상호` - invoicerCorpNum `type: string` `length: 10` `description: 공급자 사업자번호` - invoicerMgtKey `type: string` `length: 24` `description: 공급자 문서번호` - 파트너가 할당한 문서번호 - invoicerPrintYN `type: boolean` `length: -` `description: 공급자 인쇄여부` - `true`: 인쇄 - `false`: 미인쇄 - invoiceeCorpName `type: string` `length: 200` `description: 공급받는자 상호` - invoiceeCorpNum `type: string` `length: 13` `description: 공급받는자 사업자번호` - invoiceeMgtKey `type: string` `length: 24` `description: 공급받는자 문서번호` - 파트너가 할당한 문서번호 - invoiceePrintYN `type: boolean` `length: -` `description: 공급받는자 인쇄여부` - `true`: 인쇄 - `false`: 미인쇄 - closeDownState `type: number` `length: 1` `description: 공급받는자 휴폐업상태` - `null`: 미확인 - `0`: 미등록 - `1`: 사업중 - `2`: 폐업 - `3`: 휴업 - `4`: 확인실패 - closeDownStateDate `type: string` `length: 8` `description: 공급받는자 휴폐업일자` - 형식 : yyyyMMdd - trusteeCorpName `type: string` `length: 200` `description: 수탁자 상호` - trusteeCorpNum `type: string` `length: 10` `description: 수탁자 사업자번호` - trusteeMgtKey `type: string` `length: 24` `description: 수탁자 문서번호` - 파트너가 할당한 문서번호 - trusteePrintYN `type: boolean` `length: -` `description: 수탁자 인쇄여부` - `true`: 인쇄 - `false`: 미인쇄 **응답 예시** ```json { "code": 1, "total": 14, "perPage": 500, "pageNum": 1, "pageCount": 1, "list": [ { "invoicerPrintYN": false, "invoiceeCorpName": "공급받는자 상호", "invoiceePrintYN": false, "trusteePrintYN": false, "taxTotal": "10000", "supplyCostTotal": "100000", "lateIssueYN": false, "stateCode": 100, "taxType": "과세", "purposeType": "영수", "itemKey": "025102220380000001", "interOPYN": true, "writeDate": "20251022", "issueType": "정발행", "openYN": false, "invoicerCorpNum": "1234567890", "invoicerMgtKey": "20251022-10", "invoicerCorpName": "공급자 상호", "invoiceeCorpNum": "8888888888", "regDT": "20251022203801", "stateDT": "20251022203801" } ], "message": "검색 완료" } ``` ## 7. GetLogs - 상태 변경이력 확인 | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- | | GET | | | - 세금계산서의 상태에 대한 변경이력을 확인합니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/taxinvoice/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Path 파라미터** - MgtKeyType `type: string` `length: -` `required: Y` `description: 문서번호 유형 (택 1)` - `SELL`: 매출 - `BUY`: 매입 - `TRUSTEE`: 위수탁 - MgtKey `type: string` `length: 24` `required: Y` `description: 파트너가 할당한 문서번호` **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/Taxinvoice/{MgtKeyType}/{MgtKey}/Logs' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - docLogType `type: number` `length: 3` `description: 로그타입` - `100`: 임시저장 - `101`: 수정 - `102`: 개봉 - `103`: 수신확인 - `111`: 메일 재전송 - `112`: 문자 재전송 - `113`: 팩스 재전송 - `122`: 문자 전송결과 - `123`: 팩스 전송결과 - `124`: 사업자등록상태 확인 - `125`: 문서번호 할당 - `220`: 역발행요청 - `221`: 역발행요청 거부 - `222`: 역발행요청 취소 - `230`: 발행 - `240`: 발행취소 - `250`: 국세청전송 요청 - `251`: 국세청전송 대기중 - `252`: 국세청전송 진행중 - `253`: 국세청전송 접수 - `254`: 국세청전송 성공 - `255`: 국세청전송 실패 - log `type: string` `length: 2000` `description: 이력정보` - procType `type: string` `length: 3` `description: 처리형태` - `연동`: API를 통해 처리함 - `일반`: 팝빌 사이트를 통해 처리함 - `시스템`: 팝빌이 처리함 - procCorpName `type: string` `length: 70` `description: 처리회사명` - procContactName `type: string` `length: 30` `description: 처리담당자` - procMemo `type: string` `length: 200` `description: 처리메모` - regDT `type: string` `length: 14` `description: 등록일시` - 형식 : yyyyMMddHHmmss - ip `type: string` `length: 39` `description: 아이피` **응답 예시** ```json [ { "ip": "192.***.*.104", "log": "임시저장 되었습니다.", "regDT": "20251021143608", "docLogType": 100, "procType": "연동", "procCorpName": "회사명", "procContactName": "담당자 성명2" } ] ``` ## 8. GetURL - 문서함 팝업 URL | HTTP Method | 테스트(Sandbox) | 운영(Production) | | ----------- | ----------------------------------------------- | ------------------------------------------ | | GET | | | ![문서함 팝업 URL 미리보기](https://developers.popbill.com/images/reference/taxinvoice/getURL.png) **전자세금계산서 문서함의 팝업 URL을 반환합니다.** - 권장 사이즈 : width = 1,280px (최소 1,000px) / height = 800px - 반환되는 URL은 30초 동안만 사용이 가능합니다. - 반환되는 URL은 팝빌회원의 로그인 세션을 포함하고 있으니 사용에 유의하여 주시기 바랍니다. ### Request **요청 헤더** - Authorization `required: Y` `description: 인증 토큰` - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/taxinvoice/getting-started/authorization) - Accept-Language `required: N` `description: 응답 언어 설정` - `ko-KR`: 기본값 - `en-US` - Accept-Encoding `required: N` `description: 응답 압축 방식` - `gzip` - X-PB-UserID `required: N` `description: 팝빌회원 아이디` **Query 파라미터** - TG `type: string` `length: -` `required: Y` `description: 접근 메뉴 (택 1)` - `TBOX`: 임시 문서함 - `SWBOX`: 매출 발행 대기함 - `SBOX`: 매출 문서함 - `PWBOX`: 매입 발행 대기함 - `PBOX`: 매입 문서함 - `WRITE`: 정발행 작성 **요청 예시** ```bash curl --request GET \ --url 'https://{domain}/Taxinvoice?TG={TG}' \ --header 'Authorization: Bearer {token}' ``` ### Response **응답 본문** - url `type: string` `length: -` `description: 세금계산서 문서함 팝업 URL` **응답 예시** ```json { "url": "https://test.popbill.com/App/API?T=IRXSGITDREOTPOIRLPUHCB4BSBC4...NX7BMAR3=" } ```