> ## Documentation Index
> Fetch the complete documentation index at: https://devzone.nayax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TCP通信

## 连接与协议

VPOS 系统充当 **TCP/IP 服务器，** 使用 **5050 端口**。您的系统（POS/FCC）充当客户端，必须主动发起连接。通信通过持久套接字进行双向通信。

> [!NOTE]
>
> 单连接规则
>
> 该终端仅支持一个活动连接；新的套接字连接尝试将自动关闭之前的连接。
>
> 该协议采用命令-响应模式。所有客户端命令都必须包含 `requestId`,终端会在其响应中回传该 ID,以便于交易跟踪。

### TCP消息格式

为确保数据完整性，通过 TCP 套接字发送的每条消息（包括命令和响应）都必须使用一个两字节长度的前缀。这可以准确地告诉接收方，数据流中接下来有多少字节的 JSON 数据。

| 字节 | 场地 | 描述 |
| :- | :- | :- |
| 0-1 | 长度前缀 | JSON 消息的长度（以字节为单位，不包括前缀本身）。 |
| 2-N | JSON 内容 | 实际消息有效载荷，采用 UTF-8 格式。 |

#### 编码示例

对于像 `{"command":"pay","amount":5000}` 这样的 JSON 命令(总计 30 字节):

二进制表示：

```text theme={null}
[0x00][0x1E]{"command":"pay","amount":5000}
```

> [!NOTE]
>
> 大端序（网络顺序）
>
> 长度前缀与最高有效字节 (MSB) 一起首先发送。
>
> ```text theme={null}
> Calculation: $(MSB \times 256) + LSB = \text{Total Bytes}$
>
> Example: A 300-byte message results in 0x01, 0x2C. 1*256+44 = 300.
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.