> For the complete documentation index, see [llms.txt](https://onestore-dev.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onestore-dev.gitbook.io/dev/chi/tools/webshop/server.md).

# 服务器列表联动

When the user enters the ONEshop detail page, ONEshop retrieves and displays the game server list in real time.

{% hint style="info" %}
If items must be delivered to a specific server, the developer must provide a Server List API.

The server list is shown to users only when you set the identifier field type to `Server List` under `ONEconsole > Webshop > Developer > Player Identity Field`. For details, see [Player Identity Field](https://onestore-dev.gitbook.io/dev/eng/webshop/player-id-fields).

* Only one Server List type can be set per title, and the field key is fixed as `serviceServerId`.
* This API is called in real time on the ONEshop detail page, and the returned list is displayed as is, in the order returned. However, the returned list is cached per title for 1 minute.
* When the user selects a server and completes a purchase, the server information is included in the validation request and the PNS.
  {% endhint %}

**Request URI**

{% hint style="warning" %}
**Notice**

According to the ONEshop security policy, only the **HTTPS protocol and port 443** are supported. Using any other configuration may result in improper operation.
{% endhint %}

<table data-header-hidden><thead><tr><th width="184.9678955078125"></th><th></th></tr></thead><tbody><tr><td><strong>HTTP Type</strong></td><td>HTTPS</td></tr><tr><td><strong>HTTP Method</strong></td><td><mark style="color:$primary;"><code>POST</code></mark></td></tr><tr><td><strong>URL</strong></td><td>You can register the server URL in <code>ONEconsole > Webshop > Developer > Server Integration</code>. For setup instructions, refer to the <a href="https://onestore-dev.gitbook.io/dev/eng/webshop/integration">Server Integration</a> guide.</td></tr><tr><td><strong>Header</strong></td><td><p>Content-Type: application/json; charset=UTF-8</p><p>Accept: application/json</p></td></tr></tbody></table>

**Request**

<table><thead><tr><th width="195.8836669921875">Name</th><th width="124.5450439453125">Type</th><th width="123.193603515625">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>param.clientId</code></td><td>String</td><td>M</td><td>ONEshop Title ID (e.g., <code>WS00000001</code>)</td></tr><tr><td><code>signature</code></td><td>String</td><td>M</td><td><p>Signature to prevent tampering</p><ul><li>You can find the signature key in the License tab of <code>ONEconsole > Webshop > Developer > Server Integration</code>.</li><li>The signing target is the string <code>{"param":{"clientId":"..."}}</code>, which is the request body excluding <code>signature</code>.</li><li>The algorithm, verification key, and verification method are the same as for the validation request. For details, see <a href="https://onestore-dev.gitbook.io/dev/eng/tools/webshop/validation#signature">Signature Verification</a>.</li></ul></td></tr></tbody></table>

**Example**

```bash
curl -X POST "https://example.com/server-list" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -H "Accept: application/json" \
  -d '{
    "param": {
      "clientId": "WS00000001"
    },
    "signature": "ajkfl;askfjkladfjksl"
  }'
```

**Response**

<table><thead><tr><th width="288.869873046875">Name</th><th width="124.5450439453125">Type</th><th width="121.3316650390625">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>result.code</code></td><td>String</td><td>M</td><td><p>"0000": Success</p><p>"2000": Error</p></td></tr><tr><td><code>result.message</code></td><td>String</td><td>M</td><td></td></tr><tr><td><code>serverList[]</code></td><td>List</td><td>M</td><td>Server List</td></tr><tr><td><code>serverList[].serviceServerName</code></td><td>String</td><td>M</td><td><p>Server Name<br></p><ul><li>The server name displayed to the user.</li><li>The request does not include the user's language or country information, and the server list is cached per title for 1 minute, so all users see the same list. Respond with a name that users in every sales country can recognize (e.g., <code>Asia 01</code>).</li></ul></td></tr><tr><td><code>serverList[].serviceServerId</code></td><td>String</td><td>M</td><td>Server ID (up to 100 bytes). When the user selects it, it is passed as <code>serviceServerId</code> in the validation request and the PNS.</td></tr></tbody></table>

**Example**

```json
{
  "result": {
    "code": "0000",
    "message": "ONEshop(WS00000001) servers retrieved successfully"
  },
  "serverList": [
    {
      "serviceServerId": "asia01",
      "serviceServerName": "아시아 서버"
    },
    {
      "serviceServerId": "north_america01",
      "serviceServerName": "북미 서버"
    },
    {
      "serviceServerId": "europe01",
      "serviceServerName": "유럽 서버"
    },
    {
      "serviceServerId": "africa01",
      "serviceServerName": "아프리카 서버"
    }
  ]
}
```