> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/integration/server-api.md).

# 서버 API 이용하기

앱인토스 API를 이용하기 전에 필요한 서버 통신 설정을 안내해요.

### 서버 mTLS 인증서 발급받기

앱인토스 API를 사용하려면 반드시 **mTLS(mutable Transport Layer Security, 양방향 전송 계층 보안)** 인증서를 설정해야 해요.

mTLS는 클라이언트와 서버가 서로의 신원을 확인하는 방식이에요. 일반 HTTPS는 서버만 인증하지만, mTLS는 **파트너사 서버와 앱인토스 서버가 서로를 인증**해요.

이 인증서를 설정해야 다음을 보장할 수 있어요.

* 통신 구간 암호화
* 허용된 서버만 API 호출 가능
* 위·변조 방지

발급받은 인증서는 다음과 같이 관리하세요.

* 인증서와 키 파일은 유출되지 않도록 안전하게 보관하세요.
* 인증서가 만료되기 전에 재발급하세요.
* 무중단 교체가 필요하면 인증서를 두 개 이상 등록해 둘 수 있어요.

아직 인증서를 준비하지 않았다면 서버 mTLS 인증서 발급받기 문서의 mTLS 인증서 발급 방법을 먼저 확인하세요.

### 통신 방화벽 확인하기

서버에서 Inbound, Outbound 방화벽을 관리하고 있다면 아래 IP와 포트를 반드시 허용해야 해요. 허용하지 않으면 API 호출이 실패하거나 콜백을 받지 못해요.

#### 가맹점이 허용해야 하는 Inbound IP

앱인토스 → 가맹점

| IP                | Port |
| ----------------- | ---- |
| 117.52.3.11       | 443  |
| 211.115.96.11     | 443  |
| 106.249.5.11      | 443  |
| 117.52.3.80\~87   | 443  |
| 211.115.96.80\~87 | 443  |
| 106.249.5.80\~87  | 443  |

앱인토스가 가맹점 서버로 요청을 보낼 때 사용하는 IP예요. 예를 들어 콘솔에 등록한 콜백 URL로 구독 상태 변경 콜백이나 데이터 제공 동의 회수 콜백을 받을 때 필요해요.

#### 가맹점이 허용해야 하는 Outbound IP

가맹점 → 앱인토스

| 기능                        | 도메인                          | IP                                          | Port |
| ------------------------- | ---------------------------- | ------------------------------------------- | ---- |
| 간편 로그인, 메시지 발송, 토스 포인트 지급 | apps-in-toss-api.toss.im     | 117.52.3.192, 211.115.96.192, 106.249.5.192 | 443  |
| 간편 결제                     | pay-apps-in-toss-api.toss.im | 117.52.3.195, 211.115.96.195, 106.249.5.195 | 443  |

가맹점 서버에서 앱인토스 API를 호출할 때 필요한 설정이에요. HTTPS 443 포트를 열어야 정상적으로 통신할 수 있어요.

### API 공통 규격

#### 도메인 정보

* <https://apps-in-toss-api.toss.im>
* <https://pay-apps-in-toss-api.toss.im>

#### API 공통 응답 형식

모든 API는 공통된 응답 구조를 사용해요. `resultType` 값으로 성공 여부를 먼저 확인하세요.

**성공 응답**

```json
{
  "resultType": "SUCCESS",
  "success": {
    "sample": "data"
  }
}
```

* `resultType`이 `"SUCCESS"`이면 요청이 정상 처리된 상태예요.
* 실제 응답 데이터는 `success` 객체 안에 들어 있어요.
* 각 API마다 `success` 내부 구조는 달라요.

**실패 응답**

```json
{
  "resultType": "FAIL",
  "error": {
    "errorCode": "INVALID_PARAMETER",
    "reason": "요청에 실패했습니다."
  }
}
```

* `resultType`이 `"FAIL"`이면 요청 처리에 실패한 상태예요.
* `errorCode`는 오류 유형을 나타내는 코드예요.
* `reason`에는 사람이 읽을 수 있는 오류 설명이 들어 있어요.
* 잘못된 파라미터를 보내면 `INVALID_PARAMETER`와 같은 코드로 에러를 발생시켜요.

응답을 처리할 때는 반드시 `resultType`을 먼저 검사한 뒤, 성공과 실패 로직을 나눠 구현하세요.

### 요청 제한 정책

앱인토스 API는 안정적인 서비스 운영을 위해 요청 수를 제한해요.

#### 기본 제한

* 분당 3,000 QPM
* QPM은 Queries Per Minute의 약자로, 1분 동안 호출할 수 있는 API 요청 수를 의미해요.
* 미니앱 기준으로 분당 최대 3,000건까지 요청할 수 있어요.

이 한도를 초과하면 일정 시간 동안 추가 요청이 차단될 수 있어요.

#### QPM 상향이 필요한 경우

기본 3,000 QPM보다 많은 요청이 필요한 경우 [채널톡](https://apps-in-toss.channel.io/workflows/787658)으로 상향을 요청할 수 있어요.

요청할 때는 다음 정보를 함께 전달하세요.

* 사용 목적
* 예상 트래픽 규모
* 피크 시간대 요청량

비즈니스 목적과 트래픽 규모를 검토한 뒤 한도를 조정해요. 대량 트래픽이 예상된다면 서비스 오픈 전에 미리 협의하는 것이 좋아요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/integration/server-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.