API overview

WorldFirst offers a set of Application Programming Interfaces (APIs) that provides the ability for integration. You can use POST method to send HTTPS requests and receive responses accordingly.

Versioning

WorldFirst APIs are backward compatible. Earlier clients are adaptable to newer API releases.

Message structure

Request structure

An API Request is composed of the following structure:

Name

Description

Request URL

https://{host}/amsin/api/v1/{restfulPath}

  • host is the standard domain name assigned by Platform.
  • restfulPath is the path to the interface.

Request Method

POST

Request header

Composed of :

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

Refer to the table down below for more details.

Request body

Request body is in JSON format. Sample:

{"quoteBizScene": "REF_QUOTES"}

A request header contains the following fields:

Name

Sample

Description

Signature

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

  • algorithm: Specifies the digital signature algorithm that is used to generate the signature. The value is not case-sensitive. RSA256 and ECC224 are supported, and RSA256 is used by default.
  • keyVersion: Specifies the key version that is used to generate or validate the signature. By default, the value is the latest version of the key associated with client-Id.
  • signature: Contains the signature value of the request.

Content-Type

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

  • content-Type indicates the media type of the body of the request, as defined by RFC2616.
  • charset is used for generating/validating the signature and encrypting/decrypting content.

Client-Id

Client-Id: ****

Identify a client that is associated with the keys that are used for signature and encryption.

Request-Time

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

Specifies the time when the request is sent, as defined by ISO 8601.

The following curl example depicts the general structure of a message:

copy
curl -X POST \
  http://xxx.com/amsin/api/v1/payments/inquiryQuotes \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -H 'Client-Id: 5J5Y307NSG5GB7*****' \
  -H 'Request-Time: 2019-04-04T12:08:56+05:30' \
  -H 'Signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrTpMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3JrbRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%*****' \
  -d '{
  "quoteBizScene": "REF_QUOTES"
}'

The following figure illustrates the request structure:

image

Figure 1. Request structure

Response structure

An API Response is composed of the following structure:

Name

Description

Request header

Composed of :

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

Refer to the table down below for more details.

Request body

In JSON format.

  • A result parameter is included in the response body, which includes a resultStatus, resultCode, and resultMessage. Use these parameters for troubleshooting.

HTTP Response Status

Sample: 200 OK

The following figures illustrate the response structure:

image

Figure 2. Response structure

Procedures to make an API call

The following figure illustrates the message transmission workflow from Partner to WorldFirst:

1641885041937-855b42c5-c9e7-48a3-91c8-2d55fd945ae7.png

Figure 3. Message transmission workflow

Step 1. Construct a request

  • Properly construct a request with matching structures.
  • Sign the request.
  • Enable the Base64 encoding.

Step 2. Send a request

Assemble the request and send it to the WorldFirst server.

Step 3. Check the response

Validate the signature of the response after receiving the response message.

Step 4. Check the status code

In the event that an error occurs, an error response is returned, in which the result object indicates the error code and error message for the purpose of troubleshooting.

@2024 WorldFirst