/v2/pds/merchant/operator/sync

2023-05-31 12:13

POST /v2/pds/merchant/operator/sync

When a merchant adds an operator, changes the role of an operator, or remove an operator for a mini program, Mini Program Platform calls this API to synchronized the updated operator's information to the corresponding SaaS.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field	Data type	Required	Description	Example
appId	String	Yes	The unique ID assigned by Mini Program Platform to identify a mini program. Maximum length: 32 characters Characters not allowed: special characters such as @ # ?
operator	Operator	Yes	The merchant operator information that needs to be synchronized.
extendInfo	String	No	Any other information about the API calling. Maximum length: 4096 characters Characters not allowed: special characters such as @ # ? Can be `Null`	{ "key": "value" }

Response parameters

Field	Data type	Required	Description	Example
result	Result	Yes	Indicates the request result such as status and error codes.	See Response sample for details.

How to return the result

Follow the instructions below to return the result (specified in the result parameter) according to your business processing results:

If the request is successful, set the value of result.resultStatus to S and the value of result.resultCode to SUCCESS.

success: Specify the value of this parameter as true or false to indicate whether the super app receives a notification successfully.

If the status of the request is unknown, set the value of result.resultStatus to U and the value of result.resultCode to UNKNOWN_EXCEPTION.
If the request failed, set the value of result.resultStatus to F and specify the value of result.resultCode according to the failure reason.

For more information about how to define your result codes, see the Result codes section below.

Result codes

Check the table below for possible result codes:

Result code	Result status	Result message
SUCCESS	S	Success
PROCESS_FAIL	F	A general business failure occurred. Do not retry.
PARAM_ILLEGAL	F	Illegal parameters. For example, non-numeric input, invalid date.
INVALID_API	F	The called API is invalid or not active.
ACCESS_DENIED	F	Access is denied
REQUEST_TRAFFIC_EXCEED_LIMIT	F	The request traffic exceeds the limit.
UNKNOWN_EXCEPTION	U	An API call failed, which is caused by unknown reasons.

Samples

The data flow below illustrates how Mini Program Platform synchronizes app operator infomation to the super app server:

Request

The following examples are requests for different scenarios:

Add an operator

copy
{
  "appId": "210201015061XXXX",
 "operator":{
        "operatorId":"2102xxxxxxxx",
        "operatorName":"J**k",
        "status":"ACTIVE",
        "platformId":"GCASH",
        "merchantId":"2188120004706924",
        "roles":[
            {
                "roleCode":"ADMIN",
                "permissions":[
                    "P_CREATE_ORDER",
                    "P_UPDATE_ORDER"
                ]
            }
        ]
    }
}

Change the role of an operator

copy
{
  "appId": "210201015061XXXX",
 "operator":{
        "operatorId":"2102xxxxxxxx",
        "operatorName":"J**k",
        "status":"ACTIVE",
        "platformId":"GCASH",
        "merchantId":"2188120004706924",
        "roles":[
            {
                "roleCode":"DEVELOPER",
                "permissions":[
                    "P_CREATE_ORDER",
                    "P_UPDATE_ORDER"
                ]
            }
        ]
    }
}

Remove an operator

copy
{
  "appId": "210201015061XXXX",
    "operator":{
        "operatorId":"2102xxxxxxxx",
        "operatorName":"J**k",
        "status":"INACTIVE",
        "platformId":"GCASH",
        "merchantId":"2188120004706924"
    }
}

Response

The following sample codes demonstrate the possible responses:

Successful

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success.",
    "resultStatus": "S"
  }
}

Failed or unknown

copy
{
 "result": {
    "resultCode": "UNKNOWN_EXCEPTION",
    "resultStatus": "F",
    "resultMessage": "Failed due to unknown reason."
 }
}

result.resultStatus is F or U, which shows the request to send the notifications is failed or unknown.
Return the result as defined in the Result codes section.