与WanbExpress对接基础技术说明

本文介绍如何与WanbExpress进行对接，如何发送请求，以及返回的数据格式如何。

申请开发者令牌

在开始之前，您需要联系 WanbExpress，以获取开发者令牌。

如何发送请求

WanbExpress 采用的是 RESTfull 风格的 API 设计。因此你需要对HTTP协议有一定了解，并能够运用你熟悉的语言发送HTTP请求。

目前，WanbExpress 的 API 只支持JSON格式的数据返回格式，并且要求 HTTP Accept 请求头只能为 application/json。如无特别说明，请在每一个请求中显式设定此值。

每一个API请求都需要附带上认证信息。认证信息放置在 HTTP 请求头 Authorization 中，认证信息的格式为： Hc-OweDeveloper AccountNo;Token;Nonce

Hc-OweDeveloper 为固定的，而后紧接一个空格
AccountNo是您的客户代码
Token为您的开发者令牌
Nonce为一个随机数，只能为字母、数字、短横线(-)或者下划线(_)等。该随机数不能为空。在未来版本中，WanbExpress 的服务器会限定同一个客户在一定的时间内 Nonce 值不能重复。
AccountNo、Token与Nonce之间用分号(;)分隔。Nonce之后无分号。
若未设置 Authorization 请求头，或者 Authorization 请求头的数据格式有误，服务器返回 HTTP 403 Forbidden。
若AccountNo 与 Token 不合法，服务器返回 HTTP 401 Unauthorized。

下面是一个访问 /api/whoami 的HTTP请求示例：

GET api-sbx.wanbexpress.com/api/whoami HTTP/1.1
Accept: application/json
Authorization: Hc-OweDeveloper TEST;******;D8E671B7323A49FF9223AEB457257F05
Host: api-sbx.wanbexpress.com

POST / PUT 请求

有些API需要从HTTP请求体中获取数据。这类API一般会采用POST或者PUT请求方式，如无特别说明，这类API只接受JSON格式的数据。同时，请在发送请求时，设置 HTTP 请求头 Content-Type 的值为 application/json。

编码

与我司API系统进行交互时，推荐使用 UTF-8 对文本数据进行编码。

请求我司数据时，推荐使用 UTF-8 编码。否则务必在 Content-Type 请求头中指明 charset。例如您使用的是 gb2312 编码，POST JSON 数据时的 Content-Type 就应该为 application/json; charset=gb2312。

解析我司返回数据时，如无特别说明，请使用UTF-8进行数据解码。我司API返回请问头中也会注明使用的编码。例如返回 JSON 数据的接口，Content-Type Response Header 的值一般为 application/json; charset=utf-8。

返回数据格式

无需获取数据类API的返回数据格式

若一个API只是纯粹的执行某个操作，而无需获得额外的数据，返回的数据格式如下，Succeeded 表示操作成功与否。

{
    "Succeeded": true,
    "Error": null
}

需要获取数据类API的返回数据格式

若一个API会返回额外的数据，则会多一个 Data 属性，Data 的值视返回数据的格式不同而不同。例如下面是 TEST 这个账户请求 /api/whoami API 的返回格式。

{
    "Data": "TEST",
    "Succeeded": true,
    "Error": null
}

错误类返回数据格式

违背业务规则类错误的返回数据格式

请求一个API时，若出现了业务规则上的违背，则返回类似如下的数据格式。Succeeded 为 false， Error 部分带有一个 Code 和 Message。您最好记录下Code与Message，以方便与我司的开发人员进行调试与纠错。 SystemError 此时为 null。

需要注意的是，此时返回的 HTTP 状态码仍为 200。

{
    "Succeeded": false,
    "Error": {
        "Code": "0x100000",
        "Message": "地址信息缺失"
    },
    "SystemError": null
}

系统异常类错误的返回数据格式

当服务器出现异常，或者代码中有未处理的异常时，返回的数据格式与违背业务规则时返回的数据格式基本一致，但 HTTP 状态码为 500。同时 SystemError 属性视环境配置返回数据，一般会在需要联合调试的时候才会返回数据。如下所示，SystemError 包含 Message, ExceptionMessage, ExceptionType, StackTrace 和 InnerException 字段。InnerException 的结构与 SystemError 的结构一致（InnerException有可能会出现多层）。

{
    "Succeeded": false,
    "Error": {
        "Code": "0xFFF000",
        "Message": "An error has occured: invalid cast"
    },
    "SystemError": {
        "Message": "An error has occurred.",
        "ExceptionMessage": "invalid cast",
        "ExceptionType": "System.InvalidCastException",
        "StackTrace": "   at xxx 15",
        "InnerException": {
            "Message": "An error has occurred.",
            "ExceptionMessage": "value can't be null",
            "ExceptionType": "System.NullReferenceException",
            "StackTrace": null,
            "InnerException": null
        }
    }
}

关于时间与日期格式

如无特别说明，WanbExpress 的API均返回 UTC 时间，并以ISO 8601标准格式化成字符串输出，如2015-04-01T08:41:51Z。

当您向 WanbExpress 的API发送请求时，如果需要传递时间类别的属性，如无特别说明，也请转换成UTC时间后以 ISO 8601 标准格式化。