레퍼런스노드 레퍼런스액션액션국내 비즈니스국내 비즈니스 팝빌
팝빌 API를 통한 전자세금계산서 발행/조회, 현금영수증 발행/취소, 홈택스 세금계산서 수집을 처리합니다.
| 항목 | 내용 |
|---|
| 카테고리 | 국내 비즈니스 |
| 연동 필요 | 팝빌 API 인증 (LinkID + SecretKey) |
| 지원 리소스 | 전자세금계산서, 현금영수증, 홈택스 세금계산서 수집 |
팝빌은 전자세금계산서, 현금영수증, 홈택스 수집 등 세금/증빙 관련 API를 제공하는 서비스입니다. 모든 작업에 사업자번호(하이픈 제외 10자리)가 필수입니다.
| 작업 | 설명 |
|---|
| 목록 조회 | 조건별 세금계산서 목록 검색 (날짜/상태/과세형태 필터) |
| 상세 조회 | 문서번호로 세금계산서 상세 정보 조회 |
| 발행 | 세금계산서 저장 및 즉시 발행 (국세청 전송) |
| 옵션 | 설명 |
|---|
| 문서유형 | 매출 / 매입 / 위수탁 |
| 날짜 유형 | 작성일자 / 발행일자 / 전송일자 |
| 상태 필터 | 임시저장, 발행대기, 발행완료, 역발행대기, 거부, 취소 등 |
| 과세형태 | 과세 / 면세 / 영세 |
| 항목 | 설명 | 필수 |
|---|
| 발행유형 | 매출 / 매입 / 위수탁 | O |
| 작성일자 | 세금계산서 작성일 | O |
| 과세형태 | 과세 / 면세 / 영세 | O |
| 영수/청구 | 영수 또는 청구 | O |
| 공급가액 | 공급가액 합계 | O |
| 세액 | 세액 합계 | O |
| 공급자 정보 | 사업자번호, 상호, 대표자명, 이메일 | O |
| 공급받는자 정보 | 사업자번호, 상호, 대표자명, 이메일 | O |
| 품목 목록 | JSON 배열 (품명, 단가, 수량, 공급가액, 세액) | - |
| 작업 | 설명 |
|---|
| 목록 조회 | 조건별 현금영수증 목록 검색 |
| 상세 조회 | 문서번호로 현금영수증 상세 정보 조회 |
| 발행 | 현금영수증 저장 및 즉시 발행 |
| 취소 발행 | 기존 현금영수증 취소 (전체/부분 취소) |
| 항목 | 설명 | 필수 |
|---|
| 거래구분 | 소득공제용 / 지출증빙용 | O |
| 거래일자 | 거래일자 | O |
| 공급가액 | 공급가액 | O |
| 부가세 | 부가세 | O |
| 합계금액 | 공급가액 + 부가세 + 봉사료 | O |
| 구매자 식별번호 | 휴대폰, 주민번호, 사업자번호, 카드번호 중 택 1 | O |
| 가맹점 정보 | 사업자번호, 상호, 대표자명 | O |
| 옵션 | 설명 |
|---|
| 당초 승인번호 | 취소할 현금영수증의 국세청 승인번호 (9자리) |
| 부분 취소 | 전체 취소 또는 부분 취소 선택 |
| 취소 금액 | 부분 취소 시 공급가액, 부가세, 봉사료, 합계금액 입력 |
| 작업 | 설명 |
|---|
| 수집 결과 조회 | 수집 완료된 세금계산서 검색 |
| 수집 요청 | 홈택스 매입/매출 내역 수집 시작 |
| 수집 상태 확인 | 수집 작업의 진행 상태 조회 |
| 상세 조회 | 국세청 승인번호로 수집된 세금계산서 상세 조회 |
홈택스 수집은 비동기 처리됩니다. 수집 요청 후 작업 ID를 받아 상태를 확인하고, 완료 후 결과를 조회하세요.
| 코드 | 상태 |
|---|
100 | 임시저장 |
200 | 발행대기 |
300 | 발행완료 |
303 | 발행완료 (국세청 전송 성공) |
400 | 역발행대기 |
500 | 거부 |
600 | 취소 |
// 세금계산서 목록 조회
{{actions.popbill.list}}
{{actions.popbill.list[0].invoicerCorpName}}
{{actions.popbill.list[0].supplyCostTotal}}
{{actions.popbill.total}}
// 세금계산서 발행
{{actions.popbill.code}} // 응답 코드 (1: 성공)
{{actions.popbill.ntsConfirmNum}} // 국세청 승인번호
// 홈택스 수집 요청
{{actions.popbill.jobID}} // 수집 작업 ID
트리거: 데이터모델 행 변경 (주문 확정)
액션: 팝빌 - 세금계산서 발행
├── 사업자번호: "1234567890"
├── 발행유형: "매출"
├── 공급가액: {{trigger.row.supplyCost}}
├── 세액: {{trigger.row.tax}}
├── 공급자: 자사 정보
├── 공급받는자: {{trigger.row.buyerInfo}}
└── 품목: {{trigger.row.items}}
트리거: 일정 (매일 오전 8시)
액션 1: 팝빌 - 홈택스 수집 요청
├── 사업자번호: "1234567890"
├── 수집 유형: "매입"
├── 시작일: {{$today.minus(1, 'day')}}
└── 종료일: {{$today}}
액션 2: 대기 (5분)
액션 3: 팝빌 - 수집 상태 확인
└── 작업 ID: {{actions.popbill.jobID}}
액션 4: 팝빌 - 수집 결과 조회
└── 작업 ID: {{actions.popbill.jobID}}
액션 5: 데이터모델 행 추가
└── 수집 데이터 저장
트리거: 결제 완료 웹훅
조건: {{trigger.body.paymentMethod}} === "현금"
액션 1: 팝빌 - 현금영수증 발행
├── 거래구분: "소득공제용"
├── 합계금액: {{trigger.body.totalAmount}}
└── 구매자 식별번호: {{trigger.body.customerPhone}}
액션 2: 슬랙 메시지
└── 메시지: "현금영수증 발행 완료: {{trigger.body.totalAmount}}원"
팝빌 세금계산서 검색은 최대 6개월 범위까지 조회 가능합니다. 장기 데이터가 필요한 경우 여러 번 나눠서 조회하세요.
| 항목 | 요금 |
|---|
| 전자세금계산서 | 건당 200원 (일반회원 기준) |
| 홈택스 수집 | 별도 요금 |
| 기본료 | 없음 (종량제) |
| 연동 개발비 | 무료 |
- 세금계산서/현금영수증 발행 실패 시 사유를 확인하고 재시도하세요
- 홈택스 수집은 비동기이므로 반드시 상태 확인 후 결과를 조회하세요
- 인증서 만료 시 홈택스 수집이 실패할 수 있으므로 인증서 만료일을 모니터링하세요