WorldFirst DocsWorldFirst DocsDOCS

API概览

万里汇提供集成所需API，集成商可使用 POST 方法向万里汇发送HTTPS请求并接收对应的响应。

有关所有可用 API 的完整列表，请参阅 API 列表 章节。

版本迭代

万里汇API兼容历史版本，存量客户也可适应新的 API 版本。

报文结构

请求报文结构

API请求体由以下结构组成：

参数名

描述

请求 URL

https://{domain_name}.com/amsin/api/v1/{restfulPath}

  • domain_name 为平台分配的标准域名；
  • restfulPath 为接口的路径，通过restfulPath可以唯一标识一个平台的接口。

注意：

以下域名可用于与万里汇集成：

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

请求方法

POST

请求头信息

请求头信息由以下参数组成：

  • Signature
  • Content-Type
  • Client-Id
  • Request-Time

有关更多详细信息，请参阅下表。

请求体

请求体为JSON格式，包含了具体的业务请求信息。例如：

{"quoteBizScene": "REF_QUOTES"}

请求头由以下字段组成：

字段名

示例

描述

Signature

signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrTpMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3JrbRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%*****

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

Content-Type

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

  • 本次请求报文的类型以及字符编码信息，具体格式参见：RFC2616；
  • charset 主要在加验签、加解密算法中使用。

Client-Id

Client-Id: ****

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

Request-Time

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

请求的时间。此字段采用ISO 8601 标准时间戳。

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

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

copy
curl -X POST \
  http://{domain_name}.com/amsin/api/v1/payments/inquiryQuotes \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -H 'Client-Id: *****' \
  -H 'Request-Time: 2019-04-04T12:08:56+05:30' \
  -H 'Signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjx*****' \
  -d '{
  "quoteBizScene": "REF_QUOTES"
}'

下图为请求报文的结构：

image.png

图1：请求报文结构

响应报文结构

API响应体由以下结构组成：

参数名

描述

响应头信息

响应头信息由以下参数组成：

  • Signature
  • Content-Type
  • Client-Id
  • Response-Time

有关更多详细信息，请参阅下表。

响应体

响应体为JSON格式。

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

HTTP 响应状态

示例：200 OK

下图为响应报文的结构：

image.png

图2：响应报文结构

报文传输流程

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

image.png

图3：报文传输流程

1. 创建请求报文

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

2. 发送请求报文

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

3. 接收响应信息

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

4.确认结果状态

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

@2024 WorldFirst