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

# 简介

> 开始使用UniUni平台客户端API

UniUni平台客户端API允许您通过编程方式创建货件、购买面单、管理批次、追踪配送以及接收Webhook通知。

## 环境

我们提供**沙盒**和**生产**两个环境。请先在沙盒环境中测试您的集成，再上线使用。

| 环境 | 基础URL                                         |
| -- | --------------------------------------------- |
| 沙盒 | `https://api-sandbox.ship.uniuni.com/client/` |
| 生产 | `https://api.ship.uniuni.com/prod/client/`    |

所有请求仅支持HTTPS。

## 身份验证

每个请求必须在`Authorization`头中包含您的**API访问令牌**：

```
Authorization: Bearer <YOUR_ACCESS_TOKEN>
```

请参阅[创建访问令牌](/zh/api/create-access-token)了解生成和管理令牌的详细步骤。

## 请求与响应格式

* 所有请求和响应使用**JSON**格式。
* POST请求体使用`Content-Type: application/json; charset=utf-8`。
* 所有对象键使用**驼峰命名法（camelCase）**。
* 响应HTTP状态码始终为`200`（有效载荷）。无效载荷返回HTTP `422`。

每个响应遵循以下结构：

```json theme={null}
{
  "message": "Shipment created successfully",
  "code": 0,
  "data": { ... }
}
```

| 字段        | 类型             | 描述                         |
| --------- | -------------- | -------------------------- |
| `message` | string         | 关于请求状态的附加信息                |
| `code`    | integer        | 状态码（`0`表示成功）               |
| `data`    | object \| null | 响应数据。当`code`不为`0`时返回`null` |

## 分页

列表端点支持通过查询参数进行分页：

| 参数         | 默认值 | 最大值 | 描述    |
| ---------- | --- | --- | ----- |
| `page`     | 1   | —   | 页码    |
| `pageSize` | 10  | 500 | 每页结果数 |

## 沙盒测试

您可以使用沙盒基础URL自由测试集成。不会产生任何费用。沙盒数据是隔离的，重置不会影响生产环境。

要在沙盒中添加测试额度，请使用测试信用卡号**4242 4242 4242 4242**，任意有效期和CVC。

## 错误处理

### 422 无法处理的内容

当必需参数缺失或类型错误时返回：

```json theme={null}
{
  "message": "Invalid payload [...]",
  "errorCode": "PayloadValidationError",
  "statusCode": 422,
  "meta": {
    "issues": [
      {
        "code": "invalid_type",
        "expected": "number",
        "received": "nan",
        "path": ["page"],
        "message": "Expected number, received nan"
      }
    ],
    "name": "ZodError"
  }
}
```

### 身份验证错误

```json theme={null}
{
  "message": "Invalid or revoked access token",
  "code": 1009,
  "data": null
}
```

```json theme={null}
{
  "message": "Missing access token",
  "code": 1009,
  "data": null
}
```

### 错误代码

| 代码     | 原因           |
| ------ | ------------ |
| `0`    | 成功           |
| `1002` | 无效请求         |
| `1006` | 数据库错误        |
| `1009` | 通用错误         |
| `1014` | 资源未找到（面单/批次） |
| `1031` | 追踪查询失败       |