> 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/api-and-sdk-zh/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                | 端口  |
| ----------------- | --- |
| 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                                          | 端口  |
| ------------------- | ---------------------------- | ------------------------------------------- | --- |
| 便捷登录、消息发送、Toss 积分发放 | 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 端口才能正常通信。

### 允许 CORS

若要在迷你应用中与服务器通信，需要在服务器的 CORS 允许 Origin 中添加迷你应用的 Origin。\
需要允许的 Origin 会根据 SDK 版本和应用日期而不同。

#### SDK 3.x

{% hint style="info" %}
**SDK 3.x Origin 变更说明**

从 2026 年 8 月 25 日（周二）之后上传的 SDK 3.x bundle 开始，将使用 SDK 2.x 中使用的 Origin 提供服务。\
如需与外部服务器通信，请在服务器的 CORS 允许 Origin 中添加以下 Origin。

* `https://<appName>.apps.tossmini.com` ：实际服务环境

* `https://<appName>.private-apps.tossmini.com` ：控制台 QR 测试环境
  {% endhint %}

* `https://<appName>.web.tossmini.com` ：实际服务环境

* `https://<appName>.private-web.tossmini.com` ：控制台 QR 测试环境

#### SDK 1.x \~ 2.x

* `https://<appName>.apps.tossmini.com` ：实际服务环境
* `https://<appName>.private-apps.tossmini.com` ：控制台 QR 测试环境

### 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 更多的请求 [Channel Talk](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/api-and-sdk-zh/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.