背景：

在通过 HTTP 请求调用短信发送接口（single_send、batch_send、tpl_single_send、tpl_batch_send）时，所有请求参数需要进行 URL 编码（urlencode）。未正确编码可能会导致请求失败或内容错误

常见问题与解决方法：

1、报错提示请求参数缺失或未知异常

问题描述1：

调用batch_send接口时，即使已经传入了 apikey，仍出现错误：参数 apikey 必须传入

错误复现1：

问题描述2：

调用single_send接口时，已传入参数却出现错误：未知异常

错误复现2：

原因分析：

调用云片发送接口需要使用application/x-www-form-urlencoded格式传参，示例中虽然header中传入了Content-Type: application/x-www-form-urlencoded，但实际请求body还是使用的json格式，导致的报错

解决方法：

在发送请求时，务必对所有参数值（包括 apikey）进行urlencode，并确保请求体的格式符合 key=value 的键值对标准。建议使用合适的编码工具或库：

Java: URLEncoder.encode(value, "UTF-8")

Python: urllib.parse.quote(value)

JavaScript: encodeURIComponent(value)

2、短信内容缺失或显示错误

问题描述1：

调用 single_send 接口时，发送的短信内容部分丢失。例如：

• 输入：a1%123
• 输出：a13（%12 被误解为特殊字符导致问题）

错误复现1：

问题描述2：

调用 tpl_single_send 接口时，已对参数做了urlencode，可实际下发的短信内容仍然缺失或内容有误

错误复现2：

原因分析：

特殊字符（如 %、& 等）未进行 URL 编码，服务器误解析这些符号为特殊指令

错误复现1中，a1%123 和 a2%456 中的%12 和 %45 被错误解析，导致后续内容被截断或替换

--（a1%123的 %12 在 ASCII 表中对应换节符，通常被处理为无效，所以变成了 a13。a2%456的 %45 被解析为 ASCII 表中的 E，所以变成了 a2E6）

错误复现2中，由于仅对整个参数进行一次编码，未对内嵌的“%”进行?；ば员嗦?，从而被错误解析

解决方法：

对短信内容进行urlencode，确保所有字符被安全传递。在调用指定模板发送接口（tpl_single_send、tpl_batch_send）时，需要对变量名和变量值分别进行 urlencode 再传递。

建议：

• 始终对参数进行 URL 编码：避免 %、&、= 等特殊字符导致问题；
• 验证请求格式：确保请求体为 key=value 格式，参数之间用 & 分隔；
• 使用编码工具：使用编程语言内置的 urlencode 方法，减少手动错误。

参考：

单条发送接口

批量发送接口

指定模板单发

指定模板群发

java

python

C#

C/C++

shell/bash

php

asp

nodejs

go

ruby

cURL