콘텐츠로 이동

SDK 환경설정

SDK 사용을 위한 설정 옵션과 통신 환경을 안내합니다.

설정 옵션

섹션 제목: “설정 옵션”

팝빌 SDK는 다양한 환경에서 사용할 수 있도록 다음의 옵션을 제공합니다. 고객사 서비스 환경에 맞춰 옵션을 설정하여 안정적으로 API를 이용할 수 있습니다.

require 'popbill/cashbill'


class CashbillController < ApplicationController


  # API Key
  # - 연동신청 시 발급받은 인증 정보(LinkID, SecretKey로 구성)
  # • LinkID: 파트너를 식별하기 위한 고유 식별자
  # • SecretKey: API 인증토큰 발급에 사용되는 키
  #
  # TODO: 아래 LinkID, SecretKey를 발급받은 정보로 교체해 주세요.
  LinkID = "TESTER"
  SecretKey = "SwWxqU+0TExEXy/9TVjKPExI2VTUMMSLZtJf3Ed8q3I="


  # 현금영수증 서비스 객체 초기화
  CBService = CashbillService.instance(
    CashbillController::LinkID,
    CashbillController::SecretKey
  )


  # 연동환경(테스트/운영) 설정
  # - 연동환경을 테스트 또는 운영으로 설정합니다.
  # • true: 테스트 환경으로 설정
  # • false(default) : 운영 환경으로 설정
  #
  # ※ 운영전환 이후부터 IsTest 설정 변경만으로 자유롭게  환경 전환(테스트<->운영)이 가능합니다.
  CBService.setIsTest(true)


  # 인증토큰 IP 일치 검증 사용 여부
  # - 인증토큰을 발급받은 IP와, 그 토큰을 사용하여 API를 호출하는 IP가 같은지를 검사합니다.
  #   (토큰이 외부로 유출되어도 다른 IP에서는 사용하지 못하도록 막는 보안 장치)
  # • true(사용, default) : 두 IP가 일치할 때만 API 호출 허용
  # • false(미사용) : IP 일치 검사를 생략
  #
  # ※ false는 토큰 발급 시점의 IP와 API 호출 시점의 IP가 달라질 수 있는 환경에서 사용
  #   예) 오토스케일링, 로드밸런서, NAT 등으로 호출 IP가 유동적인 클라우드 환경
  CBService.setIpRestrictOnOff(true)


  # 통신 IP 고정 여부
  # - 고객사의 보안 정책 또는 방화벽으로 인해 고정 IP로 Outbound 통신을 해야 하는 경우 사용합니다.
  # • true(사용) : 고정(Static) IP 사용
  # • false(미사용, default) : 가변(Elastic) IP 사용
  #
  # ※ true 설정 시, 고정된 IP 또는 도메인을 고객사 방화벽 Outbound 목록에 등록이 필요합니다.
  #   (개발자센터 “가이드 > 공통 > 통신” 페이지에서 확인 가능)
  CBService.setUseStaticIP(false)


  # 로컬시스템 시간 사용 여부
  # - 현재시각 기준을 설정합니다.
  # • true(사용, default) : 로컬시스템 시간 사용
  # • false(미사용) : 팝빌 서버의 시간을 사용
  #
  # ※ 현재시각은 주로 인증토큰 발급 및 만료 판단 등에 사용됩니다.
  # ※ 이 설정은 홈택스 수집 기간, 세금계산서 작성일자, 발행일자 같은 업무 데이터의 날짜값을 변경하는 옵션이 아닙니다.
  # ※ 로컬 서버 시간이 정상 동기화되어 있으면 일반적으로 true를 사용하고 서버 시간 오차로 인증 실패가 의심되거나
  #   서버 시간을 신뢰하기 어려운 환경이면 false를 사용합니다.
  CBService.setUseLocalTimeYN(true)


end

IsTest : 연동환경(테스트/운영) 설정

섹션 제목: “IsTest : 연동환경(테스트/운영) 설정”

팝빌 API 연동환경은 테스트 환경과 운영 환경으로 구분되며, 각 환경은 독립된 시스템으로 구성되어 있습니다. IsTest 설정값을 변경하여 연동환경 전환(테스트 ↔ 운영)이 가능합니다.

구분테스트 (Sandbox)운영 (Production)
IsTest 설정값truefalse (기본값)
사이트https://test.popbill.comhttps://www.popbill.com
API Key동일한 API Key(LinkID, SecretKey) 이용
※ 테스트 환경과 운영 환경의 API Key 분리가 필요한 경우 문의하여 주시기 바랍니다. [연동신청]		동일한 API Key(LinkID, SecretKey) 이용
※ 테스트 환경과 운영 환경의 API Key 분리가 필요한 경우 문의하여 주시기 바랍니다. [연동신청]
국세청 신고가상으로 처리실제 국세청 신고

운영전환 이후부터 IsTest 설정 변경만으로 자유롭게 환경 전환(테스트 ↔ 운영)이 가능합니다.

운영 전환을 위한 SDK 환경설정 변경 방법

  • Ruby on Rails SDK
    1. “Controller” 파일의 isTest Property 값을 true 에서 false 로 변경합니다.

IPRestrictOnOff : 인증토큰 IP 검증 설정

섹션 제목: “IPRestrictOnOff : 인증토큰 IP 검증 설정”

팝빌 API는 인증서버로부터 Bearer Token을 발급받아 호출이 가능합니다. 보안 강화를 위해 기본적으로 토큰 발급 요청 IP와 API 호출 IP가 일치 여부를 검증하고 있으며, 검증 기능은 IPRestrictOnOff 설정값으로 제어할 수 있습니다.

구분검증미검증
IPRestrictOnOff 설정값true (기본값)false
팝빌 API 호출시 사용되는 토큰의 IP를 검증 팝빌 API 호출시 사용되는 토큰의 IP를 검증

UseStaticIP : 통신 IP 고정(방화벽)

섹션 제목: “UseStaticIP : 통신 IP 고정(방화벽)”

고객사 보안정책(방화벽 등)으로 인해 Outbound 트래픽의 고정 IP 설정이 필요한 경우, 팝빌 SDK 설정의 UseStaticIP 값을 변경하여 고정 IP를 사용할 수 있습니다.

구분고정(Static) IP가변(Elastic) IP
UseStaticIP 설정값truefalse (기본값)

통신

섹션 제목: “통신”

팝빌 API는 REST 기반으로 HTTP 요청이 가능한 모든 운영체제(OS), 데이터베이스(DB) 환경에서 사용할 수 있습니다.
API 호출과 응답에 사용되는 문자 인코딩은 UTF-8 Character Set을 지원합니다.

통신 정책

섹션 제목: “통신 정책”

API 연동을 위한 기본 규격은 다음과 같습니다.

  • HTTPS RESTful API
  • TLS v1.3, v1.2 지원
  • JSON(JavaScript Object Notation) 기반 메시지 포맷

IP 및 URL (방화벽)

섹션 제목: “IP 및 URL (방화벽)”

방화벽 설정은 “Elastic IP(가변 IP)” 또는 “Static IP(고정 IP)” 선택하여 적용할 수 있습니다.
어떤 IP가 적용되는지는 SDK의 [UseStaticIP - 통신 IP 고정(방화벽)] 설정값에 따라 적용됩니다.

팝빌에서 발급받은 API Key를 사용할 수 있는 파트너 Source IP는 IP Whitelisting 등록을 통해 안전하게 제한할 수 있습니다. [연동문의]

Elastic IP (기본값)

섹션 제목: “Elastic IP (기본값)”

Elastic IP는 AWS의 ALB(Application Load Balancer)를 통해 탄력적으로 변하는 가변(Dynamic) IP입니다.
SDK의 설정값 “UseStaticIP=false”로 설정하면 Elastic IP가 적용됩니다.

구분URLPort
팝빌 인증 (공통)https://auth.linkhub.co.krTCP:443
팝빌 운영 (Production)https://popbill.linkhub.co.krTCP:443
팝빌 테스트 (Sandbox)https://popbill-test.linkhub.co.krTCP:443

Static IP

섹션 제목: “Static IP”

고객사 Outbound 트래픽에 고정 IP 설정이 필요한 경우 사용합니다.
SDK의 설정값 “UseStaticIP=true”로 설정하면 Static IP가 적용됩니다.

구분URLIPPort
팝빌 인증 (공통)https://static-auth.linkhub.co.kr52.78.164.186
13.124.222.90		TCP:443
팝빌 운영 (Production)https://static-popbill.linkhub.co.kr52.78.164.186
13.124.222.90		TCP:443
팝빌 테스트 (Sandbox)https://static-popbill-test.linkhub.co.kr52.78.164.186
13.124.222.90		TCP:443