开始使用

欢迎！本指南将帮助您开始使用我们的 API。

身份验证

所有 API 请求都需要在 Authorization 请求头中包含 API 令牌。令牌应带有 Api-Token 前缀。

Authorization: Api-Token YOUR_API_TOKEN

验证令牌

您可以访问 /api/me 端点来验证您的令牌并获取有关您帐户的信息。

端点： GET /api/me

响应示例 (成功)：

{
  "Succeeded": true,
  "Data": {
    "KeyId": "key_123456",
    "AccountNo": "ACC789",
    "Scopes": ["shipments:read", "shipments:write"]
  }
}

---

响应处理

所有 API 响应都遵循名为 Result 的标准结构。这确保了不同端点之间的一致性，并帮助您统一处理成功和错误情况。

除非在 API 中另有说明，否则如果响应的 Content-Type 为 application/json，响应将始终包装在 Result 中。

成功响应示例

{
  "Succeeded": true,
  "Data": {
    "Id": "ship_123",
    "TrackingNumber": "TN987654321"
  }
}

错误响应示例 (业务领域错误)

{
  "Succeeded": false,
  "Error": {
    "Code": "InvalidAddress",
    "Message": "提供的目的地址无效。"
  }
}

错误响应示例 (验证错误)

{
  "Succeeded": false,
  "Error": {
    "Code": "BAD_REQUEST",
    "Message": "请求无效，模型验证失败。"
  },
  "SystemError": {
    "Message": "请求无效。",
    "ModelState": {
      "request": ["request 字段是必填的。"],
      "$.FieldName": [
        "无法将 JSON 值转换为枚举 MyFieldEnum。路径：$.FieldName | LineNumber: 43 | BytePositionInLine: 45。"
      ]
    },
    "MessageDetail": null,
    "ExceptionMessage": null,
    "ExceptionType": null,
    "StackTrace": null,
    "InnerException": null
  },
  "CapturedValues": {}
}