튜토리얼
Ruby 개발환경에서 팝빌 SDK를 추가하여 전자세금계산서 즉시 발행 (RegistIssue) 함수를 구현하는 예시입니다.
1. POPBiLL SDK 추가
팝빌 Ruby SDK를 추가하기 위해 Rails 프로젝트 "Gemfile" 파일에 팝빌 Ruby Gem SDK 정보를 추가하고 bundle install을 진행합니다.
source 'https://rubygems.org'
git_source(:github) { |repo| "https://github.com/#{repo}.git" }
ruby '2.3.0'
# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
gem 'rails', '~> 5.2.3'
# 팝빌 API Service
gem 'popbill', '1.52.0'
# 생략
# ...2. POPBiLL SDK 설정
프로젝트에 전자세금계산서 서비스 기능을 수행할 Controller를 생성합니다.
rails generate controller tutorialController에 연동신청시 발급받은 API Key 를 변수로 선언하고 아래의 코드를 참조하여 전자세금계산서 서비스 객체를 생성 합니다.
require 'popbill/taxinvoice'
class TaxinvoiceController < ApplicationController
# 링크아이디
LinkID = "LinkID"
# 비밀키
SecretKey = "SwWxqU+0TExEXy/9TVjKPExI2VTUMMSLZtJf3Ed8q3I="
# 전자세금계산서 서비스 객체 초기화
TIService = TaxinvoiceService.instance(
TaxinvoiceController::LinkID,
TaxinvoiceController::SecretKey
)
# 연동환경 설정, true-테스트, false-운영(Production), (기본값:false)
TIService.setIsTest(true)
# 인증토큰 IP 검증 설정, true-사용, false-미사용, (기본값:true)
TIService.setIpRestrictOnOff(true)
# 통신 IP 고정, true-사용, false-미사용, (기본값:false)
TIService.setUseStaticIP(false)
# 로컬시스템 시간 사용여부, true-사용, false-미사용, (기본값:true)
TIService.setUseLocalTimeYN(true)
end3. RegistIssue 기능 구현
Controller 코드에 전자세금계산서 즉시 발행 (RegistIssue) 함수 호출 코드를 추가합니다.
def registIssue
# 팝빌회원 사업자번호
corpNum = "1234567890"
# 문서번호, 1~24자리 (숫자, 영문, '-', '_') 조합으로
# 사업자 별로 중복되지 않도록 구성
mgtKey = "20220101-022"
# 세금계산서 정보
taxinvoice = {
######################### 공급자정보 #########################
# [필수] 공급자 사업자번호, '-' 제외 10자리
"invoicerCorpNum" => corpNum,
# 공급자 종사업장 식별번호, 필요시 숫자 4자리 기재
"invoicerTaxRegID" => "",
# [필수] 공급자 상호
"invoicerCorpName" => "상호명",
# [필수] 공급자 대표자 성명
"invoicerCEOName" => "대표자명",
# [필수] 공급자 문서번호, 1~24자리 (숫자, 영문, '-', '_') 조합으로
# 사업자 별로 중복되지 않도록 구성
"invoicerMgtKey" => mgtKey,
# 공급자 주소
"invoicerAddr" => "공급자 주소",
# 공급자 업태
"invoicerBizType" => "공급자 업태",
# 공급자 종목
"invoicerBizClass" => "공급자 종목",
# 공급자 담당자명
"invoicerContactName" => "공급자 담당자명",
# 공급자 담당자 메일주소
"invoicerEmail" => "test@Testcom",
# 공급자 담당자 휴대폰번호
"invoicerHP" => "010-111-222",
# 공급자 담당자 연락처
"invoicerTEL" => "070-4304-2991",
# 발행시 알림문자 전송여부 (정발행에서만 사용가능)
# - 공급받는자 주)담당자 휴대폰번호(invoiceeHP1)로 전송
# - 전송시 포인트가 차감되며 전송실패하는 경우 포인트 환불처리
"invoicerSMSSendYN" => false,
######################### 공급받는자정보 #########################
# [필수] 공급받는자 구분, {사업자, 개인, 외국인} 중 기재
"invoiceeType" => "사업자",
# [필수] 공급받는자 사업자번호, '-' 제외 10자리
"invoiceeCorpNum" => "8888888888",
# 공급받는자 종사업장 식별번호, 필요시 숫자 4자리 기재
"invoiceeTaxRegId" => "",
# [필수] 공급받는자 상호
"invoiceeCorpName" => "공급받는자 상호",
# [필수] 공급받는자 대표자 성명
"invoiceeCEOName" => "대표자 성명",
# 공급받는자 문서번호
"invoiceeMgtKey" => "",
# 공급받는자 주소
"invoiceeAddr" => "공급받는자 주소",
# 공급받는자 종목
"invoiceeBizClass" => "공급받는자 종목",
# 공급받는자 업태
"invoiceeBizType" => "공급받는자 업태",
# 공급받는자 담당자명
"invoiceeContactName1" => "공급받는자담당자명",
# 공급받는자 담당자 메일주소
# 팝빌 개발환경에서 테스트하는 경우에도 안내 메일이 전송되므로,
# 실제 거래처의 메일주소가 기재되지 않도록 주의
"invoiceeEmail1" => "test@Testcom",
# 공급받는자 담당자 연락처
"invoiceeTEL1" => "070-1234-1234",
# 공급받는자 담당자 휴대폰번호
"invoiceeHP1" => "010-123-1234",
# [필수] 작성일자, 표시형식 (yyyyMMdd)
"writeDate" => "20220101",
# [필수] 발행형태, {정발행, 역발행, 위수탁} 중 기재
"issueType" => "정발행",
# [필수] 과세형태, {과세, 영세, 면세} 중 기재
"taxType" => "과세",
# [필수] 과금방향, {정과금, 역과금} 중 기재, '역과금'은 역발행 프로세스에서만 이용가능
# - 정과금(공급자 과금), 역과금(공급받는자 과금)
"chargeDirection" => "정과금",
# [필수] {영수, 청구, 없음} 중 기재
"purposeType" => "영수",
# [필수] 공급가액 합계
"supplyCostTotal" => "20000",
# [필수] 세액 합계
"taxTotal" => "2000",
# [필수] 합계금액, 공급가액 합계 + 세액합계
"totalAmount" => "22000",
# 기재 상 '일련번호' 항목
"serialNum" => "",
# 기재 상 '권' 항목, 숫자만 입력(0~32767)
"kwon" => nil,
# 기재 상 '호' 항목, 숫자만 입력(0~32767)
"ho" => nil,
# 기재 상 '현금' 항목
"cash" => "",
# 기재 상 '수표' 항목
"chkBill" => "",
# 기재 상 '어음' 항목
"note" => "",
# 기재 상 '외상미수금' 항목
"credit" => "",
# 기재 상 '비고' 항목
"remark1" => "비고1",
"remark2" => "비고2",
"remark3" => "비고3",
# 사업자등록증 이미지 첨부여부
"businessLicenseYN" => false,
# 통장사본 이미지 첨부여부
"bankBookYN" => false,
######################### 수정세금계산서 정보 ##########################
# - 수정세금계산서 관련 정보는 연동매뉴얼 또는 개발가이드 링크 참조
# - [참고] 수정세금계산서 작성방법 안내 - http://blog.linkhubcorp.com/650
# [수정세금계산서 작성시 필수] 수정사유코드, 수정사유에 따라 1~6중 선택기재, 미기재시 nil 로 처리
"modifyCode" => nil,
# [수정세금계산서 작성시 필수] 당초승인번호 기재
"orgNTSConfirmNum" => nil,
######################### 상세항목(품목) 정보 #########################
# serialNum(일련번호) 1부터 순차기재 (배열로 99개 까지 가능)
##################################################################
"detailList" => [
{
"serialNum" => 1, # 일련번호, 1부터 순차기재
"purchaseDT" => "20220101", # 거래일자, yyyyMMdd
"itemName" => "테스트1", # 품목명
"spec" => "규격", # 규격
"qty" => "1", # 수량
"unitCost" => "10000", # 단가
"supplyCost" => "10000", # 공급가액
"tax" => "1000", # 세액
"remark" => "비고", # 비고
},
{
"serialNum" => 2, # 일련번호, 1부터 순차기재
"purchaseDT" => "20220101", # 거래일자, yyyyMMdd
"itemName" => "테스트2", # 품목명
"spec" => "규격", # 규격
"qty" => "1", # 수량
"unitCost" => "10000", # 단가
"supplyCost" => "10000", # 공급가액
"tax" => "1000", # 세액
"remark" => "비고", # 비고
},
],
######################### 추가담당자정보 #########################
# 세금계산서 발행안내 메일을 수신받을 공급받는자의 담당자가 다수인 경우 담당자 정보를
# 추가하여 발행안내메일을 다수에게 전송할 수 있습니다. (배열로 5까지 기재 가능)
##############################################################
"addContactList" => [
{
"serialNum" => 1, # 일련번호, 1부터 순차기재
"contactName" => "담당자01", # 담당자명
"email" => "test@Testcom", # 담당자 메일주소
},
{
"serialNum" => 2, # 일련번호, 1부터 순차기재
"contactName" => "담당자02", # 담당자명
"email" => "test@Testcom", # 담당자 메일주소
}
],
}
# 거래명세서 동시작성여부
writeSpecification = false
# 지연발행 강제여부
# - 발행마감일이 지난 세금계산서를 발행하는 경우, 가산세가 부과될 수 있습니다.
# - 가산세가 부과되더라도 발행을 해야하는 경우에는 forceIssue의 값을 true로 선언하면 됩니다.
forceIssue = false
# 거래명세서 동시작성시 거래명세서 문서번호, 미기재시 세금계산서 문서번호로 자동작성
dealInvoiceMgtKey = ''
# 메모
memo = ''
# 발행안내메일 제목, 미기재시 기본양식으로 전송됨
emailSubject = ''
begin
@Response = TutorialController::TIService.registIssue(
corpNum,
taxinvoice,
writeSpecification,
forceIssue,
dealInvoiceMgtKey,
memo,
emailSubject,
)
render "home/response"
rescue PopbillException => pe
@Response = pe
render "home/exception"
end
end4. 결과 확인
함수 호출 반환 결과는 아래와 같습니다.
- 성공 : Response code 로 숫자 1 반환
- 실패 : PopbillException 으로 음의 정수 8자리 숫자값 오류코드와 오류메시지 반환 [오류코드]