背景:

在通过 HTTP 请求调用短信发送接口(single_sendbatch_sendtpl_single_sendtpl_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_sendtpl_batch_send)时,需要对变量名和变量值分别进行 urlencode 再传递。

建议:

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

参考:

单条发送接口

批量发送接口

指定模板单发

指定模板群发

java

python

C#

C/C++

shell/bash

php

asp

nodejs

go

ruby

cURL