API概览

万里汇提供集成所需API,集成商可使用POST方法向万里汇发送HTTPS请求并接收对应的响应。下文介绍具体报文结构报文传输流程

版本迭代

万里汇API兼容历史版本。

环境

环境地址为:

  • SG: open-sea.worldfirst.com
  • EU: open-eu.worldfirst.com
  • US: open-na.worldfirst.com

报文结构

在给万里汇发送解决方案相关报文之前,集成商需要认真阅读本文档并了解请求报文和响应报文的结构。此处具体介绍集成商和万里汇之间发送的报文结构、报文内容和报文传输流程。

请求报文结构

下图为请求报文的结构:

image.png

图1:请求报文结构

下例为报文结构的curl示例:

copy
curl --location --request POST 'http://{domain_name}.com/amsin/api/v1/business/inquiryPayOrder' \
--header 'client-id: *****' \
--header 'Content-Type: application/json' \
--header 'signature: algorithm=RSA256,keyVersion=2,signature=KEhXthj4bJ801Hqw8kaLvE*****' \
--header 'request-time: now()' \
--header 'Cookie: JSESSIONID=66A1C5F430EA249ACD*****' \
--data-raw '{"paymentId":"sample_payment_id"}'

请求URL

请求url格式:https://{host}/amsin/api/v1/{restfulPath}

其中:

  1. host为平台分配的标准域名;
  2. restfulPath为接口的路径;

通过restfulPath可以唯一标识一个平台的接口。

请求方法

HTTP的请求方法统一为POST

请求头信息

HTTP请求头主要包含了客户端、加验签、加解密相关的信息,请求头中的内容不区分大小写。

请求头参数

是否必填

范例

Client-Id

Client-Id: *****

Signature

Signature: algorithm=RSA256, keyVersion=2, signature=*****

Content-Type

Content-Type: application/json; charset=UTF-8

Request-Time

Request-Time: 2019-04-04T12:08:56+08:00


注意
:部分API的请求头包含Access-Token 参数,用于 OAuth 授权。详见OAuth授权章节。

Client-Id

客户端ID。此字段代表了客户端身份,万里汇会用此字段关联签名算法的或加密算法的密钥。

Signature

本部分为报文签名的信息,格式为包含多个键值对的复杂结构。其中键值对中的key和value用等号(=)连接,不同键值对之间用逗号(,)连接。

可用的key如下:

  • algorithm:代表了加验签所使用的算法,不区分大小写,默认值为RSA256,目前仅支持RSA256和ECC224;
  • keyVersion:代表了本次加验签所使用的密钥版本,默认值为clientId所关联的最新的密钥版本;
  • signature:是本次请求的签名字符串。

示例如下:

copy
signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ801Hqw8kaLvEKc0****

具体加签方式参见相关文档:加签

Content-Type

本次请求报文的类型以及字符编码信息,具体格式参见:RFC2616,其中的charset会在加验签、加解密算法中使用。

示例如下:

copy
Content-type: application/json; charset=UTF-8

Request-Time

请求的时间。此字段采用ISO 8601 标准时间戳。如:2018-09-03T00:00:00+08:00

请求体

请求体为JSON格式,包含了具体的业务请求信息。不同的接口中请求信息不同,具体参见各个接口的详细介绍。

响应报文结构

下图为响应报文的结构:

image.png

图2:响应报文结构

响应头信息

响应头主要包括以下信息:

响应头参数

是否必填

范例

Signature

Signature: algorithm=RSA256, keyVersion=2, signature=*****

Content-Type

Content-Type: application/json; charset=UTF-8

Client-Id

Client-Id: *****

Response-Time

Response-Time: 2019-04-04T12:08:56+08:00

注:响应头域不区分大小写。

Signature

本部分为报文签名的信息,格式为包含多个键值对的复杂结构。其中键值对中的key和value用等号(=)连接,不同键值对之间用逗号(,)连接。

可用的key如下:

  • algorithm:代表加验签所使用的算法,不区分大小写,默认值为RSA256,目前仅支持RSA256和ECC224;
  • keyVersion:代表本次加验签所使用的密钥版本,默认值为Client-Id所关联的最新的密钥版本;
  • signature:包含本次响应的签名字符串。

Content-Type

本次请求报文的类型以及字符编码信息,具体格式参见:RFC2616,其中的charset会在加验签、加解密算法中使用。

Client-Id

客户端ID。此字段代表了客户端身份,万里汇会用此字段关联签名算法的或加密算法的密钥。

Response-time

响应的时间。此字段采用ISO 8601 标准时间戳。如:2018-09-03T00:00:00+08:00

响应报文内容

包含业务处理或者受理的响应信息,不同业务的响应信息不同,但都会包括result参数,代表此次接口调用的结果。

当调用结果(resultStatus)为“失败(F)”或“未知 (U)”时,结果码(resultCode)代表错误码,结果信息(resultMessage)代表错误信息,可用于分析处理异常,具体参见错误码。

报文传输流程

下图为集成商调用接口并获取响应信息的流程:

image.png

图3:报文传输流程

接口调用流程

按照以下步骤调用接口:

准备工作

  • 发送请求前,使用密钥对信息进行加签。
  • 为避免接收到的响应信息出错,请确认:
    • 确认编码正确
    • 确认幂等性正确

1. 创建请求报文

  • 请求报文需遵循报文的格式要求,包含Client-Id、请求时间、签名等必要信息。
  • 为确保信息传输的安全性,所有请求和响应都必须完成加验签过程。

2. 发送请求报文

在完成创建请求报文之后,集成商可以向万里汇发送请求报文。

3. 接收响应信息

  • 响应信息通常为JSON或XML格式,详细介绍参见响应报文结构部分。
  • 集成商收到响应信息后,需要对响应报文签名进行验证。

4.确认结果状态

每个接口返回的响应信息会有所不同,但都包含result参数,代表此次接口调用的结果。若接口调用出错,则会返回错误码和错误信息,可用于分析处理异常。

@2024 WorldFirst