跳转到主要内容
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>
请参阅创建访问令牌了解生成和管理令牌的详细步骤。

​
请求与响应格式

  • 所有请求和响应使用JSON格式。
  • POST请求体使用Content-Type: application/json; charset=utf-8。
  • 所有对象键使用驼峰命名法（camelCase）。
  • 响应HTTP状态码始终为200（有效载荷）。无效载荷返回HTTP 422。
每个响应遵循以下结构： 
{
  "message": "Shipment created successfully",
  "code": 0,
  "data": { ... }
}
字段类型描述
messagestring关于请求状态的附加信息
codeinteger状态码（0表示成功）
dataobject | null响应数据。当code不为0时返回null

​
分页

列表端点支持通过查询参数进行分页：
参数默认值最大值描述
page1—页码
pageSize10500每页结果数

​
沙盒测试

您可以使用沙盒基础URL自由测试集成。不会产生任何费用。沙盒数据是隔离的，重置不会影响生产环境。 要在沙盒中添加测试额度，请使用测试信用卡号4242 4242 4242 4242，任意有效期和CVC。

​
错误处理

​
422 无法处理的内容

当必需参数缺失或类型错误时返回： 
{
  "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"
  }
}

​
身份验证错误

{
  "message": "Invalid or revoked access token",
  "code": 1009,
  "data": null
}

{
  "message": "Missing access token",
  "code": 1009,
  "data": null
}

​
错误代码

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