튜토리얼
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/statement'
class StatementController < ApplicationController
# 링크아이디
LinkID = "LinkID"
# 비밀키
SecretKey = "SwWxqU+0TExEXy/9TVjKPExI2VTUMMSLZtJf3Ed8q3I="
# 전자명세서 서비스 객체 초기화
STMTService = StatementService.instance(
StatementController::LinkID,
StatementController::SecretKey
)
# 연동환경 설정, true-테스트, false-운영(Production), (기본값:false)
STMTService.setIsTest(true)
# 인증토큰 IP 검증 설정, true-사용, false-미사용, (기본값:true)
STMTService.setIpRestrictOnOff(true)
# 통신 IP 고정, true-사용, false-미사용, (기본값:false)
STMTService.setUseStaticIP(false)
# 로컬시스템 시간 사용여부, true-사용, false-미사용, (기본값:true)
STMTService.setUseLocalTimeYN(true)
end3. RegistIssue 기능 구현
Controller 코드에 전자명세서 즉시 발행 (RegistIssue) 함수 호출 코드를 추가합니다.
def registIssue
# 팝빌회원 사업자번호
corpNum = "1234567890"
# 전자명세서 종류코드, 121-거래명세서, 122-청구서, 123-견적서, 124-발주서, 125-입금표, 126-영수증
itemCode = 121
# 전자명세서 문서번호
mgtKey = "20220101-021"
# 전자명세서 정보
statement = {
# [필수] 전자명세서 종류코드, 121-거래명세서, 122-청구서, 123-견적서, 124-발주서, 125-입금표, 126-영수증
"itemCode" => itemCode,
# 맞춤양식코드, 공백처리시 기본양식으로 작성
"formCode" => "",
# [필수] 문서번호, 숫자, 영문, '-', '_' 조합 (최대24자리)으로 사업자별로 중복되지 않도록 구성
"mgtKey" => mgtKey,
# [필수] 기재상 작성일자, 날짜형식(yyyyMMdd)
"writeDate" => "20220101",
# [필수] 과세형태, {과세, 영세, 면세} 중 기재
"taxType" => "과세",
# [필수] {영수, 청구, 없음} 중 기재
"purposeType" => "영수",
# [필수] 공급가액 합계
"supplyCostTotal" => "20000",
# [필수] 세액 합계
"taxTotal" => "2000",
# 합계금액, 공급가액 합계 + 세액 합계
"totalAmount" => "22000",
# 기재 상 일련번호
"serialNum" => "",
# 사업자등록증 이미지 첨부여부
"businessLicenseYN" => false,
# 통장사본 이미지 첨부여부
"bankBookYN" => false,
# 발행시 알림문자 전송여부
"smssendYN" => false,
# 비고
"remark1" => "비고1",
"remark2" => "비고2",
"remark3" => "비고3",
######################### 발신자 정보 #########################
# 발신자 사업자번호
"senderCorpNum" => "1234567890",
# 발신자 상호
"senderCorpName" => "발신자 상호",
# 발신자 대표자 성명
"senderCEOName" => "발신자 대표자명",
# 발신자 종사업장 식별번호, 필요시 기재, 형식은 숫자 4자리
"senderTaxRegID" => "",
# 발신자 주소
"senderAddr" => "발신자 주소",
# 발신자 종목
"senderBizClass" => "발신자 종목",
# 발신자 업태
"senderBizType" => "발신자 업태",
# 발신자 담당자 성명
"senderContactName" => "발신자 담당자명",
# 발신자 담당자 메일주소
"senderEmail" => "test@test.com",
# 발신자 담당자 연락처
"senderTEL" => "070-4304-2991",
# 발신자 담당자 휴대폰번호
"senderHP" => "010-1234-1234",
######################### 수신자 정보 #########################
# 수신자 사업자번호
"receiverCorpNum" => "8888888888",
# 수신자 상호
"receiverCorpName" => "수신자 상호",
# 수신자 대표자 성명
"receiverCEOName" => "수신자 대표자 성명",
# 수신자 주소
"receiverAddr" => "수신자 주소",
# 수신자 종목
"receiverBizClass" => "종목",
# 수신자 업태
"receiverBizType" => "업태",
# 수신자 담당자 성명
"receiverContactName" => "수신자 담당자명",
# 수신자 담당자 메일주소
# 팝빌 개발환경에서 테스트하는 경우에도 안내 메일이 전송되므로,
# 실제 거래처의 메일주소가 기재되지 않도록 주의
"receiverEmail" => "test2@test.com",
# 수신자 담당자 연락처
"receiverTEL" => "070-4304-2999",
# 수신자 담당자 휴대폰번호
"receiverHP" => "010-111-222",
######################### 상세항목(품목) 정보 #########################
# serialNum(일련번호) 1부터 순차기재 (배열 길이 제한 없음)
##################################################################
"detailList" => [
{
"serialNum" => 1, # 일련번호 1부터 순차기재
"purchaseDT" => "20220101", # 거래일자 yyyyMMdd
"itemName" => "테스트1", # 품명
"spec" => "규격", # 규격
"unit" => "단위", # 단위
"qty" => "1", # 수량
"unitCost" => "10000", # 단가
"supplyCost" => "10000", # 공급가액
"tax" => "1000", # 세액
"remark" => "비고", # 비고
},
{
"serialNum" => 2, # 일련번호, 1부터 순차기재
"purchaseDT" => "20220101", # 거래일자 yyyyMMdd
"itemName" => "테스트1", # 품명
"spec" => "규격", # 규격
"unit" => "단위", # 단위
"qty" => "1", # 수량
"unitCost" => "10000", # 단가
"supplyCost" => "10000", # 공급가액
"tax" => "1000", # 세액
"remark" => "비고", # 비고
},
],
######################### 전자명세서 추가속성 #########################
"propertyBag" => {
"CBalance" => "15000",
"Deposit" => "5000",
"CBalance" => "20000",
}
} # end of statement Hash
begin
@Response = TutorialController::STMTService.registIssue(
corpNum,
statement,
)
render "home/response"
rescue PopbillException => pe
@Response = pe
render "home/exception"
end
end4. 결과 확인
함수 호출 반환 결과는 아래와 같습니다.
- 성공 : Response code 로 숫자 1 반환
- 실패 : PopbillException 으로 음의 정수 8자리 숫자값 오류코드와 오류메시지 반환 [오류코드]