宝付短信渠道接口

本文档描述平台短信发送所使用的宝付（Mandao）短信网关接口规范，供后端通知服务（Celery Worker）集成使用。

环境地址

注意： 生产环境需在宝付侧开通服务器出口 IP 白名单，部署前需提前申请。

请求规范

• 请求方式： POST
• Content-Type： multipart/form-data

请求参数

sendType 枚举

businessType 枚举

响应参数

判断标准： success == true 且 result > 0 为短信发送成功。

成功响应示例：

{
  "success": true,
  "result": 1,
  "errorCode": null,
  "errorMsg": null
}

失败响应示例：

{
  "success": false,
  "result": 0,
  "errorCode": "SMS_001",
  "errorMsg": "手机号格式不正确"
}

请求示例

Python（Celery Worker 集成）

import httpx
import uuid
from app.config import settings  # 从 KMS/配置中心读取

async def send_sms(mobile: str, content: str, business_type: int = 4) -> bool:
    """
    发送短信
    :param mobile: 手机号，多个用逗号分隔
    :param content: 短信内容
    :param business_type: 业务类型，默认 4（普通业务通知）
    :return: 是否发送成功
    """
    payload = {
        "userName": settings.BAOFOO_SMS_USERNAME,
        "userPass": settings.BAOFOO_SMS_PASSWORD,
        "mobile": mobile,
        "content": content,
        "domain": settings.APP_NAME,
        "sendType": "3",
        "businessType": str(business_type),
        "requestId": str(uuid.uuid4()),
    }

    async with httpx.AsyncClient(timeout=10.0) as client:
        response = await client.post(settings.BAOFOO_SMS_URL, data=payload)
        result = response.json()

    success = result.get("success") is True and (result.get("result") or 0) > 0
    if not success:
        logger.error(
            "宝付短信发送失败",
            mobile=mobile,
            error_code=result.get("errorCode"),
            error_msg=result.get("errorMsg"),
        )
    return success

配置项（存入 KMS / 环境变量）

平台短信场景映射

注意事项

1. 生产环境 IP 白名单： 部署前需将服务器出口 IP 提交给宝付侧开通，否则生产环境请求会被拦截。
2. requestId 幂等： 建议每次请求生成唯一 UUID 作为 requestId，便于宝付侧排查问题。
3. 凭证安全： userName 和 userPass 禁止明文写入代码或 Git，统一存入 KMS，参见 00d-preparation-checklist.md。
4. 发送频率： 同一手机号短信发送需在业务层做频率限制（如 60 秒 1 次），避免触发运营商拦截。
5. 境外手机号： 发送境外号码时需填写 areaCode（如中国大陆 +86、香港 +852）。