1.Introduction #

Marketing Place platform will provide you with a complete eSIM wholesale service.

2.Versions #

3.Scope #

3.1 Purpose #

The purpose of this article is to help customers quickly complete MP system integration. It introduces the materials and specifications that need to be prepared during integration, and how to use the integrated services according to the specifications

3.2 Step #

• Step1:apply for / issue offline signatrue and complete the primary conditions for integration

• Step2:carry out service integration and connect API services

• Step3:you can use iccid to order the product

• Step4:you can top up your order using the order returned in step 3

3.3 Key information preparation #

Basic information of Reseller:

Note： Please send the form to the LinksField PM team, who will create enterprise based on the contents of the form.

4.Flow #

4.1 Overview of the apis #

4.2 Order status query #

You can use API to check the status of the orders you have ordered on the platform.

GET /mp-api/api/esim/queryOrderStatus

Input parameters #

Output parameters #

Note: Multiple pieces of data may be returned

Normal Data:

{
  "code": 200,
  "msg": "Success",
  "data": [
    {
      "eid": "89491202308310000235",
      "packageCode": "LP14230831004073",
      "status": "0",
      "actualStartTime": null,
      "plannedEndTime": null
    }
  ],
  "requestId": null
}

Null data:

{
    "code": 200,
    "msg": "Success",
    "data": [{
        "eid": null,
        "packageCode": null,
        "status": null,
        "actualStartTime": null,
        "plannedEndTime": null
    }],
    "requestId": null
}

4.3 Traffic query #

You can use API to check the usage of the orders you have ordered on the platform.

GET /mp-api/api/esim/queryTraffic

Input parameters #

Output parameters #

Note: Multiple pieces of data may be returned

Normal data:

{
  "code": 200,
  "msg": "Success",
  "data": [
    {
      "eid": null,
      "packageCode": "LP14230831004073",
      "packageFlow": null,
      "packageUsedFlow": null,
      "actualStartTime": null,
      "plannedEndTime": null,
      "cycle": "1"
    }
  ],
  "requestId": null
}

Null data:

{
    "code": 200,
    "msg": "Success",
    "data": [{
        "eid": null,
        "packageCode": null,
        "packageFlow": null,
        "packageUsedFlow": null,
        "actualStartTime": null,
        "plannedEndTime": null,
        "cycle": null
    }],
   "requestId": null
}

4.4 Swtich order #

You can use API to change the order status of the orders you have ordered on the platform.

POST /mp-api/api/esim/switchOrder

Input parameters #

Note: OrderCode can determine an order separately

Update: Update September 25, 2023 switchButton added pause and re-enable operations. Set the correct values based on the switchButton example value

Output parameters #

{
    "code": 200,
    "msg": "Success",
    "data": null,
    "requestId": null
}

4.5 Alarm callback #

4.5.1 Specifies the callback interface #

You need to write a request interface (It must be a POST interface) in your service, and then call /mp-api/api/esim/saveAlarmCallbackInterface to save the full URL of your interface into the Links Field configuration.

POST /mp-api/api/esim/saveAlarmCallbackInterface

Body parameters

Responses

{
    "code": 200,
    "msg": "Success",
    "data": "httpUrl",
    "requestId": null
}

4.5.2 Alarm callback #

When the usage reaches the specified threshold, callback push is triggered, and the alarm information is sent to the specified server by querying the callback interface configured with the Reseller.

Callback interface params

4.6 Get product list #

You can query the product and specification info that you have already purchased in MP.

GET /mp-api/api/esim/v2/productList

Input Parameters #

Output Parameters #

{

  "code": 200,

  "msg": "Success",

  "data": [

    {

      "goodsId": 35,

      "goodsName": "Test countryCoverage",

      "productId": 5,
      
      "orderQuantity": "1",

      "productName": "Test QR product",

      "simGroupCode": "SIMGROUP1705126754702139392",

      "simGroupName": "test qr 2",

      "coverCountry": "460",

      "coverCountryName": "China"

    },

    {

      "goodsId": 37,

      "goodsName": "CHINA_Test",

      "productId": 6,

      "orderQuantity": "3,4",

      "productName": "1GB/7days",

      "simGroupCode": "SIMGROUP1706570409388478464",

      "simGroupName": "eSIMGO test group 0926",

      "coverCountry": "460",

      "coverCountryName": "China"

    },

    {

      "goodsId": 35,

      "goodsName": "TEST countryCoverage",

      "productId": 8,

      "orderQuantity": "2",

      "productName": "testtest",

      "simGroupCode": "SIMGROUP1705126754702139392",

      "simGroupName": "test qr 2",

      "coverCountry": "460",

      "coverCountryName": "China"

    }

  ],

  "requestId": null

}

4.7 Get QR code and create order #

You can select a product for eSIM in your MP’s inventory that is currently on sale. We will response the order result and QR code to you after the order is completed.

We support both specified ICCID ordering and unspecified ordering.

POST /mp-api/api/esim/v2/activationCode

Input Parameters #

Note: orderQuantity indicates the number of cycles that can be ordered. If this parameter is not passed, the minimum number of cycles supported by the Product is taken. If the orderQuantity passed to MP is not the number of valid cycles supported by the Product, a friendly prompt is returned: No ICCID found

Output Parameters #

Note:
qrCode is String of the QR which will be scanned by the end-user to download/instal the profile.
orderCode is an unique ID in the MP system. The access party should bind an unique ID in their own system to manage the relations later for the traffic query,service(disable/enable) etc.

{
  "code": 200,
  "msg": null,
  "data": {
    "iccid": "8943108169999589689",
    "qrCode": "LPA:1$rsp-0001.linksfield.net$FJW99-WC5AS-CBYC9-WFTOZ",
    "orderCode": "ORDER_1726522312360550400"
  },

  "requestId": null

}

4.8 Top up #

You can use the order number obtained after the activationCode operation to continue the top-up operation, which will increase the same period and volume based on the order generated by the activationCode operation.
Order states that allow top-up include: not enabled, in use, and suspended. Finished orders do not allow top-up.

POST /mp-api/api/esim/v2/topUp

Input Parameters #

Note: orderCode can be obtained in the response of the activationCode interface.

Output Parameters #

Note:
orderCode is an unique ID in the MP system. The access party should bind an unique ID in their own system to manage the relations later for the traffic query,service(disable/enable) etc.
renewPeriod indicates the number of periods for top-up. This value is derived from the number of periods used by the activationCode interface to generate orders.

{
  "code": 200,
  "msg": "Success",
  "data": {
    "renewPeriod": 1,
    "orderCode": "ORDER_1859115952416571392"
  },
  "requestId": null
}

4.9 History daily traffic query #

You can use API to check the usage of the orders you have ordered on the platform.

GET /mp-api/api/esim/v2/queryHistoryDailyTraffic

Input parameters #

Output parameters #

Note: Multiple pieces of dailyTraffic may be returned

Normal data:

{
  "code": 200,
  "msg": "Success",
  "data": {
      "packageCode": "LP14230831004073",
      "actualStartTime": "2025-03-07 17:11:21",
      "plannedEndTime": "2025-03-13 23:59:59",
      "dailyTraffic": [
        {
          "flowUseTime": "2025-03-07",
          "useFlow": "120000"
        }
      ]
    },
  "requestId": null
}

Null data:

{
    "code": 200,
    "msg": "Success",
    "data": {
      "packageCode": null,
      "actualStartTime": null,
      "plannedEndTime": null,
      "dailyTraffic": [
        {
          "flowUseTime": null,
          "useFlow": null
        }
      ]
    },
   "requestId": null
}