SuitsDocs
레퍼런스노드 레퍼런스액션액션국내 비즈니스국내 비즈니스

팝빌

팝빌 API를 통한 전자세금계산서 발행/조회, 현금영수증 발행/취소, 홈택스 세금계산서 수집을 처리합니다.

개요

항목내용
카테고리국내 비즈니스
연동 필요팝빌 API 인증 (LinkID + SecretKey)
지원 리소스전자세금계산서, 현금영수증, 홈택스 세금계산서 수집

팝빌은 전자세금계산서, 현금영수증, 홈택스 수집 등 세금/증빙 관련 API를 제공하는 서비스입니다. 모든 작업에 사업자번호(하이픈 제외 10자리)가 필수입니다.


작업 종류

전자세금계산서

작업설명
목록 조회조건별 세금계산서 목록 검색 (날짜/상태/과세형태 필터)
상세 조회문서번호로 세금계산서 상세 정보 조회
발행세금계산서 저장 및 즉시 발행 (국세청 전송)

목록 조회 필터 옵션

옵션설명
문서유형매출 / 매입 / 위수탁
날짜 유형작성일자 / 발행일자 / 전송일자
상태 필터임시저장, 발행대기, 발행완료, 역발행대기, 거부, 취소 등
과세형태과세 / 면세 / 영세

발행 필수 입력

항목설명필수
발행유형매출 / 매입 / 위수탁O
작성일자세금계산서 작성일O
과세형태과세 / 면세 / 영세O
영수/청구영수 또는 청구O
공급가액공급가액 합계O
세액세액 합계O
공급자 정보사업자번호, 상호, 대표자명, 이메일O
공급받는자 정보사업자번호, 상호, 대표자명, 이메일O
품목 목록JSON 배열 (품명, 단가, 수량, 공급가액, 세액)-

현금영수증

작업설명
목록 조회조건별 현금영수증 목록 검색
상세 조회문서번호로 현금영수증 상세 정보 조회
발행현금영수증 저장 및 즉시 발행
취소 발행기존 현금영수증 취소 (전체/부분 취소)

발행 필수 입력

항목설명필수
거래구분소득공제용 / 지출증빙용O
거래일자거래일자O
공급가액공급가액O
부가세부가세O
합계금액공급가액 + 부가세 + 봉사료O
구매자 식별번호휴대폰, 주민번호, 사업자번호, 카드번호 중 택 1O
가맹점 정보사업자번호, 상호, 대표자명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원 (일반회원 기준)
홈택스 수집별도 요금
기본료없음 (종량제)
연동 개발비무료

에러 처리

  • 세금계산서/현금영수증 발행 실패 시 사유를 확인하고 재시도하세요
  • 홈택스 수집은 비동기이므로 반드시 상태 확인 후 결과를 조회하세요
  • 인증서 만료 시 홈택스 수집이 실패할 수 있으므로 인증서 만료일을 모니터링하세요

참고 자료