# SDK 환경설정

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

## 설정 옵션

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

```vb
Private Sub Form_Load()


  ' 계좌조회 서비스 객체 초기화
  easyFinBankService.Initialize LinkID, SecretKey


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


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


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

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

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

| 구분         | 테스트 (Sandbox)                                                                                                                                                       | 운영 (Production)                                                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| IsTest 설정값 | true                                                                                                                                                                | false (기본값)                                                                                                                                                         |
| 사이트        | https\://test.popbill.com                                                                                                                                           | https\://www\.popbill.com                                                                                                                                           |
| API Key    | **동일한 API Key(LinkID, SecretKey) 이용** ※ 테스트 환경과 운영 환경의 API Key 분리가 필요한 경우 문의하여 주시기 바랍니다. [\[연동신청\]](https://developers.popbill.com/customer-center/partner-request) | **동일한 API Key(LinkID, SecretKey) 이용** ※ 테스트 환경과 운영 환경의 API Key 분리가 필요한 경우 문의하여 주시기 바랍니다. [\[연동신청\]](https://developers.popbill.com/customer-center/partner-request) |

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

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

- **VBA SDK**
  1. “taxinvoice\_example.accdb(mdb)” 파일의 Form\_Load() 프로시저 IsTest Property 값을 True 에서 False 로 변경합니다.

### IPRestrictOnOff : 인증토큰 IP 검증 설정

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

| 구분                  | 검증         | 미검증   |
| ------------------- | ---------- | ----- |
| IPRestrictOnOff 설정값 | true (기본값) | false |

![팝빌 API 호출시 사용되는 토큰의 IP를 검증](https://developers.popbill.com/images/guide/getting-started/img_iprestrict.webp)

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

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

| 구분              | 고정(Static) IP | 가변(Elastic) IP |
| --------------- | ------------- | -------------- |
| UseStaticIP 설정값 | true          | false (기본값)    |

## 통신

팝빌 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 (방화벽)

방화벽 설정은 “Elastic IP(가변 IP)” 또는 “Static IP(고정 IP)” 선택하여 적용할 수 있습니다.\
어떤 IP가 적용되는지는 SDK의 [\[UseStaticIP - 통신 IP 고정(방화벽)\]](https://developers.popbill.com/reference/easyfinbank/vba/getting-started/sdk-configration#set-static-ip) 설정값에 따라 적용됩니다.

> 팝빌에서 발급받은 API Key를 사용할 수 있는 파트너 Source IP는 IP Whitelisting 등록을 통해 안전하게 제한할 수 있습니다. [\[연동문의\]](https://developers.popbill.com/customer-center/inquiry)

#### Elastic IP (기본값)

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

| 구분                 | URL                                 | Port    |
| ------------------ | ----------------------------------- | ------- |
| 팝빌 인증 (공통)         | https\://auth.linkhub.co.kr         | TCP:443 |
| 팝빌 운영 (Production) | https\://popbill.linkhub.co.kr      | TCP:443 |
| 팝빌 테스트 (Sandbox)   | https\://popbill-test.linkhub.co.kr | TCP:443 |

#### Static IP

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

| 구분                 | URL                                        | IP                          | Port    |
| ------------------ | ------------------------------------------ | --------------------------- | ------- |
| 팝빌 인증 (공통)         | https\://static-auth.linkhub.co.kr         | 52.78.164.186 13.124.222.90 | TCP:443 |
| 팝빌 운영 (Production) | https\://static-popbill.linkhub.co.kr      | 52.78.164.186 13.124.222.90 | TCP:443 |
| 팝빌 테스트 (Sandbox)   | https\://static-popbill-test.linkhub.co.kr | 52.78.164.186 13.124.222.90 | TCP:443 |