API auth basics

Request Method

• Must application/json !!
• Must application/json !!
• Must application/json !!

Public Parameters

API calls must contain these http headers.

Name	Type	Optional	Example	Memo
accessKey	String	no	fme2na3kdi3ki	Customer level access key, identify single nxcloud.com customer
ts	String	no	1655710885431	Current timestamp in ms, must between 60 seconds with standard time.
bizType	String	no	1	business type
action	String	no	send	API business operation, refer to each single api description
sign	String	no	6e9506557d1f289501d333ee2c365826	API signature，Sign algorithm

bizType Parameters

Value	Memo
1	Phone number detection
2	whatsapp messages

Sign algorithm

Call nxcloud.com API need this siganiture.
Please use hex(md5(headersStr + bodyStr + accessSecretStr))

1. headersStr ：All required fields (beside sign), sort ASCII asc, each as key=val, join with & to gt final string. accessKey=YOUR_ACCESS_KEY&action=ACTION&bizType=BIZ_TYPE&ts=CURRENT_TIMESTAMP
2. bodyStr：then add &body={'body1':''}. Notice:
   1. skip it if body is empty. (When uploading files)
   2. the json body used in the final request, and calc the sign, must be the same one,
3. accessSecretStr：your access secret，ends with &accessSecret=YOUR_ACCESS_SECRET. Notice, Access Secret only use to calc final sign, no need to put into the call body.
4. using MD5 hex and Lower Case.

Calc Sign Code example

Java

/**
 * demo
 */
@Test
public void generateSignDemo() {
    // header
    Map<String, String> headers = new HashMap<>(8);
    headers.put("accessKey", "fme2na3kdi3ki");
    headers.put("ts", "1655710885431");
    headers.put("bizType", "1");
    headers.put("action", "send");

    // business parameter
    JSONObject postData = new JSONObject();
    postData.put("id", 10001);
    postData.put("name", "xxx");
    String body = postData.toString();
    
    // accessKey secret
    String accessSecret = "abciiiko2k3";

    String sign = calcSign(headers, body, accessSecret);
    log.info("sign: {}", sign); // sign: 87c3560d3331ae23f1021e2025722354
}

/**
 * Sign
 *
 * @param headers      
 * @param body         body  json
 * @param accessSecret secret
 * @return
 */
private String calcSign(Map<String, String> headers, String body, String accessSecret) {
    StringBuilder raw = new StringBuilder();

    // step1: join headers
    raw.append("accessKey=").append(headers.get("accessKey")).append("&action=").append(headers.get("action"))
            .append("&bizType=").append(headers.get("bizType")).append("&ts=").append(headers.get("ts"));
    log.info("step1: {}", raw); // step1: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431

    // step2: join body
    if (StringUtils.isNotEmpty(body)) {
        raw.append("&body=").append(body);
    }
    log.info("step2: {}", raw); // step2: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"name":"xxx","id":10001}

    // step3: add accessSecret
    raw.append("&accessSecret=").append(accessSecret);
    log.info("step3: {}", raw); // step3: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"name":"xxx","id":10001}&accessSecret=abciiiko2k3

    // step4: md5, hex, lower case
    String sign = DigestUtils.md5Hex(raw.toString());
    log.info("step4: sign={}", sign); // step4: sign=87c3560d3331ae23f1021e2025722354

    return sign;
}

C#

public static void Main() {

    // Header
    Dictionary<string, string> headers = new Dictionary<string, string>();
    headers.Add("accessKey", "fme2na3kdi3ki");
    headers.Add("ts", "1655710885431");
    headers.Add("bizType", "1");
    headers.Add("action", "send");

    // business parameters
    string body = "{\"name\":\"xxx\",\"id\":10001}";

    // accessKey secret
    string accessSecret = "abciiiko2k3";
    
    string sign = calcSign(headers, body, accessSecret);
    Console.WriteLine("sign: {0}", sign); // sign: 87c3560d3331ae23f1021e2025722354
}


/**
 * sign
 *
 * @param headers      
 * @param body         
 * @param accessSecret 
 * @return
 */
public static string calcSign(IDictionary<string, string> headers, String body, string accessSecret) {
    StringBuilder str = new StringBuilder();
    
    // step1: header
    str.Append("accessKey=").Append(headers["accessKey"]).Append("&action=").Append(headers["action"])
        .Append("&bizType=").Append(headers["bizType"]).Append("&ts=").Append(headers["ts"]);
    Console.WriteLine("step1: {0}", str); // step1: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431
    
    // step2: body
    if (!string.IsNullOrEmpty(body)) {
        str.Append("&body=").Append(body);
    }
    Console.WriteLine("step2: {0}", str); // step2: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"name":"xxx","id":10001}
    
    // step3: accessSecret
    str.Append("&").Append("accessSecret=").Append(accessSecret);
    Console.WriteLine("step3: {0}", str); // step3: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"name":"xxx","id":10001}&accessSecret=abciiiko2k3
    
    // step4: MD5 hex lowercase
    MD5 md5 = MD5.Create();
    byte[] bytes = md5.ComputeHash(Encoding.UTF8.GetBytes(str.ToString()));
    StringBuilder result = new StringBuilder();
    for (int i = 0; i < bytes.Length; i++)
    {
        result.Append(bytes[i].ToString("x2"));
    }
    string sign = result.ToString();
    Console.WriteLine("step4: sign={0}", sign); // step4: sign=87c3560d3331ae23f1021e2025722354


    return sign;
}

PHP

<?php

$headers = array("accessKey" => "fme2na3kdi3ki", "ts" => "1655710885431", "bizType" => "1", "action" => "send");
$postData = array("id" => 10001, "name" => "牛小信");
$body = json_encode($postData, JSON_UNESCAPED_UNICODE);
echo "body= " . $body . "\n"; // body= {"id":10001,"name":"牛小信"}

$accessSecret = "abciiiko2k3";
$sign = calcSign($headers, $body, $accessSecret);
echo "sign=" . $sign; // sign=7750759da06333f20d0640be09355e34

function calcSign($headers, $body, $accessSecret) {
    // step1: header
    $str = "accessKey=".$headers['accessKey']."&action=".$headers['action']
        ."&bizType=".$headers['bizType']."&ts=".$headers['ts'];
    echo "step1: " . $str . "\n"; // step1: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431
    
    // step2: body
    if (!empty($body)) {
        $str = $str . "&body=" . $body;
    }
    echo "step2: " . $str . "\n"; // step2: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"id":10001,"name":"xxx"}
    
    // step3: 拼接accessSecret
    $str = $str . "&accessSecret=" . $accessSecret;
    echo "step3: " . $str . "\n"; // step3: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"id":10001,"name":"xxx"}&accessSecret=abciiiko2k3
    
    // step4: MD5 hex lowerCase
    $ret = md5($str);
    echo "step4: sign=" . $ret . "\n"; // step4: sign=7750759da06333f20d0640be09355e34

    return $ret;
}

?>

Python

def calc_sign(headers, body, accessSecret):
    # step1: header
    string_raw = 'accessKey=' + str(headers['accessKey']) + '&action=' + str(headers['action']) + '&bizType=' + str(headers['bizType'])  + '&ts=' + str(headers['ts']) 
    print("step1:",string_raw); # step1: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431
    
    # step2: body
    if len(body) > 0:
        string_raw += '&body=' + body
    print("step2:",string_raw); # step2: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"id": 10001, "name": "xxx"}
    
    # step3: 拼接accessSecret
    string_raw += '&accessSecret=' + accessSecret
    print("step3:",string_raw); # step3: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"id": 10001, "name": "xxx"}&accessSecret=abciiiko2k3

    # step4: MD5 hex lowercase
    sign = hashlib.md5(string_raw.encode()).hexdigest()
    print("step4: sign=",sign); # step4: sign= d0c24a9886c629330d7f3f2056c65bc2
    return sign


headers = {'accessKey':'fme2na3kdi3ki','ts':'1655710885431','bizType':'1','action':'send'}

params = {'id':10001,'name':'xxx'}
body = json.dumps(params, ensure_ascii=False, separators=(",", ":"))
print("body=", body) # body= {"id": 10001, "name": "xxx"}

accessSecret = 'abciiiko2k3'

sign = calc_sign(headers, body, accessSecret)
print("sign=", sign) # sign= d0c24a9886c629330d7f3f2056c65bc2

Go

func main() {
    
    headers := map[string]string{
        "accessKey": "fme2na3kdi3ki",
    	"ts": "1655710885431",
   		"bizType": "1",
    	"action": "send",
	}
	
	postData := map[string]interface{}{
        "id": 10001,
    	"name": "xxx",
	}
    bodyByte, err := json.Marshal(postData)
    if err != nil {
      fmt.Printf("wrong err=%v\n", err)
    }
    body := string(bodyByte)
	fmt.Println("body:", body) // body: {"id":10001,"name":"xxx"}

    accessSecret := "abciiiko2k3"

    sign := calcSign(headers, body, accessSecret)
    fmt.Println("sign:", sign) // sign: 7750759da06333f20d0640be09355e34
}



func calcSign(headers map[string]string, body string, accessSecret string) string {
    var build strings.Builder
    
    // step1: header
    build.WriteString("accessKey=");
    build.WriteString(headers["accessKey"]);
    build.WriteString("&action=");
    build.WriteString(headers["action"]);
    build.WriteString("&bizType=");
    build.WriteString(headers["bizType"]);
    build.WriteString("&ts=");
    build.WriteString(headers["ts"]);
	fmt.Println("step1:", build.String()) // step1: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431
	
	// step2: body
	if len(body) > 0 {
        build.WriteString("&body=");
        build.WriteString(body);
    }
	fmt.Println("step2:", build.String()) // step2: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"id":10001,"name":"xxx"}
    
    // step3: accessSecret
	build.WriteString("&accessSecret=")
	build.WriteString(accessSecret)
	raw := build.String();
	fmt.Println("step3:", raw) // step3: accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"id":10001,"name":"xxx"}&accessSecret=abciiiko2k3    
    // step4: MD5 hex lowercase
    md5Result := md5.Sum([]byte(raw))
	sign := fmt.Sprintf("%x", md5Result)
	fmt.Println("step4: sign=", sign) // step4: sign= 7750759da06333f20d0640be09355e34

	return sign
}

Call example

1. Setting parameters value

• Header：
  • accessKey: fme2na3kdi3ki
  • bizType: 1
  • action: send
  • ts: 1655710885431
• body：

{"name":"xxx","id":10001}

2. Join Header、body、accessSecret

accessKey=fme2na3kdi3ki&action=send&bizType=1&ts=1655710885431&body={"name":"xxx","id":10001}&accessSecret=abciiiko2k3

3. Sign

using: hex(md5(headersStr + bodyStr + accessSecretStr))
MD5 hex and lowercase。sign:87c3560d3331ae23f1021e2025722354

4. Do HTTP request

Add sign to Header, execute the request，final Header、body shoule be:

• Header：
  • accessKey: fme2na3kdi3ki
  • bizType: 1
  • action: send
  • ts: 1655710885431
  • sign: 87c3560d3331ae23f1021e2025722354
• body：

{"name":"xxx","id":10001}

Common error

Error Code	Error Info	Memo
1001	Missing parameter	Header must contains all required parameters
1002	Wrong parameter	Check Header \ Body
1003	Invalid sign	Check sign
1004	Wrong timestamp	must between 60 seconds within standard timestamp
1005	No privillage	accessKey wrong, or certain business type is not available