Integration guide

This guide provides a detailed overview of how to integrate with WorldFirst.

Integration process overview

The integration process is divided into the following steps:

1. Prepare for integration
2. Develop and integrate
3. Conduct acceptance testing
4. Launch into production

Prepare for integration

Review relevant documents

Before starting integration with WorldFirst, review the relevant documentation to understand the subsequent integration steps. The key documents include:

• Integration guide (this document): Outlines the integration process step-by-step.
• API overview: Details the structure of message transmission, including the format of request headers and response headers.
• Sign a request and validate the signature: Explains how to sign requests and verify responses, along with providing signature examples.
• API list: Provides information on available APIs, their call directions, and business purposes.
• Idempotency: Offers an overview of idempotency parameters for API calls.

Design an integration plan

Contact the WorldFirst technical support team to develop a customized integration plan.

Exchange authentication information and other details

The following table outlines the information that must be exchanged between you and WorldFirst in both testing and production environments:

Table 1. Information exchange requirements in both testing and production environments.

Develop and integrate

Develop and integrate in collaboration with the WorldFirst team to fit your business needs. WorldTrade Solution offers functionalities such as file uploads, order creation, payment initiation, order detail retrieval, and shipment request processing. Some APIs are interdependent; therefore, follow the steps below when developing and integrating your product.

Figure 1. Overall API workflow

Step 1. Upload attachments

Invoke the uploadAttachment API to upload relevant files such as product images or shipping documentation. WorldFirst will return the fileKey and fileName parameters, which are needed as inputs for subsequent APIs like creating orders or shipments.

• When uploading attachments for a trade order, set the input parameter bizType to WT_B2B_TRADE_PRODUCT.
• When uploading attachments for a delivery order, use the following values for bizType:

• WT_B2B_DELIVERY_LOGISTICS
• WT_B2B_DELIVERY_OTHER
• WT_B2B_DELIVERY_ENTRY.

Step 2. Create trade order

Call the createTradeOrder API to upload detailed trade order information and generate a WorldFirst order. After an order is successfully created, WorldFirst returns the order link and the order payment link.

• The input parameter requestId is idempotent and must have a unique value for each API call.
• To receive notifications from WorldFirst, ensure you specify the following parameters with valid URLs: payResultNotifyUrl, orderResultNotifyUrl, and deliveryResultNotifyUrl.

If an order fails the WorldFirst risk assessment, WorldFirst will call the notifyTradeOrderCloseResult API with the detailed results.

Step 3. Query order details

After creating an order, you can use the queryTradeOrder API to fetch order details, including payment phases (e.g., deposit/final payment or full payment), payment results, and delivery information.

Step 4. Create delivery order

With the returned messages from Step 1 and Step 2, call the createDelivery API to initiate shipment requests. If the request is successful, WorldFirst will return the delivery batch number.

The input parameter requestId is idempotent and must be unique for every request.

Notification regarding delivery approval or rejection will be sent via the notifyDeliveryAuditResult API.

Step 5. Receive and respond to notifications

WorldFirst calls the following notification APIs and sends audit and payment results to you if you have specified the valid URLs for payResultNotifyUrl, orderResultNotifyUrl, and deliveryResultNotifyUrl parameters during the createTradeOrder API call in Step 2:

1. notifyTradeOrderCloseResult: Called only when an order fails audit approval.
2. notifyPaymentResult: Called only when buyer payments are successful.
3. notifyDeliveryAuditResult: Called for both successful and rejected delivery audits.

• Upon receiving a notification from WorldFirst, you must send a response to confirm receipt.
• Refer to the API overview section for details on the response header structure.
• You must also sign the response message as per Sign a request and validate the signature.

Conduct acceptance testing

Contact the WorldFirst technical team to understand the acceptance testing process, obtain test cases, and produce an integration report.

Launch into production

Once acceptance testing is completed, switch your product build to your production environment. Update any required parameters, such as clientId, keys, and other settings, and proceed to deploy the integration in the production environment.