# SMS HTTP API Documentation

# Update Log

## Update Log

| Version | Description | Author | Date |
|---------|-------------|--------|------|
| v1.3 | 1. Added error code=110<br>2. Added Java, PHP hexadecimal conversion examples | | 2020/10/26<br>2021/06/24 |
| v1.4 | Supported https protocol | | |
| v1.4.1 | Added customer report SMS status interface 5 | | |

# Interface Description

## Interface Description

**Important Notes:**
1. The message content (UTF-8 encoded) needs to be converted to hexadecimal code before sending, for example, "你好" converts to "e4bda0e5a5bd"
2. Phone numbers must include international country codes (e.g., 00628131565741)
3. Password encryption rule: md5(spid+"00000000"+"plaintext password"+timestamp) For example:
   Before MD5: testspid00000000testpwd1601029303
   After MD5: a14e201f22aafbae74c4d72030ad5a8d

# Single SMS Sending

### Request URL
```
https://{domain}/sms/send?spid=xx&pwd=xx&das=xx&timestamp=xx&sm=x
```

### Request Method
GET

### Parameter Description

| Field | Type | Name | Description |
|-------|------|------|-------------|
| spid | string | Interface account | |
| pwd | string | Encrypted password | **Important note 3** |
| das | string | Phone number | Must include international code, e.g., 0062 |
| sm | string | Message content | Must be converted to hexadecimal (character length is based on original text) |
| timestamp | string | Current Unix timestamp (seconds) | Example: 1601028870 |
| senderid | string | Optional | Field enabled for partners |

### Response
```json
{
  "code": 0,
  "msg": "Success",
  "data": {
    "msgid": "100123",
    "parts": 1  //Current SMS calculated number of segments
  }
}
```

### Status Code (code) Description
- 0    -- Submission successful
- 101 -- Required fields cannot be empty (note request method is GET)
- 102 -- Verification failed (Unix timestamp is time zone independent, ensure error range [-10s, 10s])
- 103 -- spid does not exist
- 104 -- Password does not match (parameter must include timestamp)
- 105 -- No available channel (please contact administrator to confirm channel configuration)
- 106 -- Configuration error
- 107 -- Phone number is blacklisted
- 108 -- Content exceeds maximum character count
- 109 -- Parsing failed, please confirm interface parameters
- 110 -- Request IP restricted
- 111 -- Phone number sending restricted (too many attempts)
- 120 -- System error, please try again later (**Important note 1.1**)

# Multiple SMS Sending

### Request URL
```
https://{domain}/sms/rsend
```

### Request Method
POST    Content-Type: application/x-www-form-urlencoded

### Parameter Description

| Field | Type | Name | Description |
|-------|------|------|-------------|
| spid | string | Interface account | |
| pwd | string | Password | **Important note 3** |
| timestamp | string | Current Unix timestamp (seconds) | Example: 1601028870 |
| dasm | string | Message content (no more than 200 phone numbers per request) | Format:<br>phone number,content/phone number,content ... <br><br>**Note the previous instructions** |
| senderid | string | Optional | Field enabled for partners |

### Response
```json
{
  "code": 0,
  "msg": "Success",
  "data": [{
    "das": "00628131565746",
    "msgid": "100123",
    "parts": 1, //Calculated number of segments
    "state": 0
  }]
}
```

### Status Code (code) Description
Same as single SMS sending.

# SMS Delivery Status Query

### Request URL
```
https://{domain}/sms/state?spid=xx&pwd=xx&timestamp=xx&msgid=xx
```

### Request Method
GET

### Parameter Description

| Field | Type | Name | Description |
|-------|------|------|-------------|
| spid | string | Interface account | |
| pwd | string | Password | **Important note 3** |
| timestamp | string | Current Unix timestamp (seconds) | Example: 1601028870 |
| msgid | string | Message ID (no more than 100 per request) | For multiple IDs, connect with commas, e.g.,100123,100124 |

### Response
```json
{
  "code": 0,
  "msg": "Success",
  "data": [{
    "msgid": "100123",
    "state": 0
  }]
}
```

### Delivery Status Description
state  0-No receipt (submitted to channel), 1-Delivery success, 2-Delivery failure

## Asynchronous Delivery Notification

### Interface Description
After the channel returns a receipt, notify the client of SMS delivery content through the configured URL. If needed, inform us of the URL for configuration.

### Request URL
```
http(s)://{your_callback_url}?msgid=36160109669&das=628131565746&state=1
```

### Request Method
GET

### Parameter Description
- msgid   Message ID
- state   0-No receipt (submitted to channel), 1-Delivery success, 2-Delivery failure

## Report SMS Status

### Interface Description
Client business platform SMS status statistics within a specific time period (start_time~end_time) for monitoring and problem detection

### Request URL
```
https://{domain}/sms/monitor
```

### Request Method
POST    Content-Type: application/x-www-form-urlencoded

### Parameter Description

| Field | Type | Name | Description |
|-------|------|------|-------------|
| spid | string | Interface account | |
| start_time | string | Start time Unix timestamp (seconds) | Data statistics start time, example: 1601028870 |
| end_time | string | End time Unix timestamp (seconds) | Data statistics end time, example: 1601028870 |
| total | int | Total submission records | |
| success | int | Number of successful status | |

### Response
```json
{
  "code": 0,
  "msg": "Success"
}
```

# Appendix-Hexadecimal conversion in Java and PHP

### Java String to Hexadecimal

```java
public static String strToHex(String str) {
    String st = "";
    try {
        byte[] by = str.getBytes("utf8");
        for (int i = 0; i < by.length; i++) {
            String strs = Integer.toHexString(by[i]);
            if (strs.length() > 2){
                strs = strs.substring(strs.length() - 2);
            } else if (strs.length() == 1) {
                //Add padding for hexadecimal 00~0F
                strs = String.format("%02x", by[i]);
            }
            st += strs;
        }
    } catch (Exception e) {
        e.printStackTrace();
    }
    return st;
}
```

### PHP String to Hexadecimal

```php
bin2hex($utf8Str);
```