Taifa 短信发送（SMS v2）接口整理

文档信息

• 供应商：Taifa Mobile Ltd（肯尼亚 SMS 中间商）
• 依据：官方 API Reference（Taifa Mobile Ltd - API Reference.html）
• 厂商页：Taifa Mobile
• 接入结论：v2（官方推荐，响应与 Legacy PHP 完全一致，切换仅改 Base URL）

1. 环境与认证

项	取值
生产 Base URL	https://api.taifamobile.co.ke
测试 Base URL	文档未提供（暂用生产地址 + 不同 API Key 区分，待向供应商确认）
认证	API Key（64 位 hex）放 Header h_api_key，无签名
Content-Type	application/json
加解密	无，明文 JSON over HTTPS
HTTP 状态	恒为 200，业务结果看响应体 status_code

认证 Header：

h_api_key: 27f904b1f2f929ddeb0d4dab0a44af96bd25b73e9e5d605f
Content-Type: application/json

• API Key 从控制台 My Account → API Key 获取，每个请求必带；禁止进前端 / 公开仓库。

v2 vs Legacy

项	Legacy（PHP）	v2（推荐）
Base Path	/api/sms/	/v2/sms/
发送	/api/sms/sendsms.php	/v2/sms/sendsms
余额	/api/sms/units.php	/v2/sms/units
额外	无	health、smpp-credentials
响应结构	数组 + status_code	完全一致

2. 发送短信

POST https://api.taifamobile.co.ke/v2/sms/sendsms
h_api_key: <API_KEY>
Content-Type: application/json

入参

字段	类型	必填	说明
mobile	string	是	目标号码，多个逗号分隔；支持 07xx / 01xx / 254xxxxxxxxx，建议统一 254xxxxxxxxx
sender_name	string	是	已注册 Sender ID（如 TaifaMobile），未注册返回 1001
message	string	是	短信内容，最大 920 字符（6 条 SMS 拼接）
response_type	string	否	json（默认）/ plain，固定用 json
service_id	string/int	否	批量发送固定 0；短码业务时为短码服务标识
link_id	string	否	短码回复场景必填；批量发送留空

号码格式：

格式	示例	备注
本地 07xx	0702739804	Safaricom / Airtel / Telkom
本地 01xx	0102739804	Airtel 短格式
国际	254702739804	E.164，不带 +

请求示例

curl -X POST https://api.taifamobile.co.ke/v2/sms/sendsms \
  -H "h_api_key: <你的API_KEY>" \
  -H "Content-Type: application/json" \
  -d "{\"mobile\":\"254707556633\",\"sender_name\":\"TaifaMobile\",\"message\":\"Hello from Taifa\",\"response_type\":\"json\"}"

成功响应（数组，每号码一条）

[
  {
    "status_code": "1000",
    "status_desc": "Success",
    "message_id": "45766",
    "recipient_id": "52532",
    "mobile_number": "254707556633",
    "network_id": "1",
    "message_cost": "1.00",
    "credit_balance": "498.00"
  }
]

成功判断：HTTP 200 且 status_code == "1000"。多接收人时数组多条，需逐条判断。

3. 辅助接口

3.1 查余额

GET https://api.taifamobile.co.ke/v2/sms/units
h_api_key: <API_KEY>

{
  "credit_balance": "498.00",
  "date": "2026-07-10 12:55:58"
}

3.2 健康检查

GET https://api.taifamobile.co.ke/v2/sms/health

部署环境联通性探测用（443 出站 + DNS 解析 api.taifamobile.co.ke）。

3.3 SMPP（可选）

• 高吞吐（千级 TPS）场景走 SMPP，TCP 2775。
• SMPP 凭据与 REST API Key 相互独立，需 POST /v2/sms/smpp-credentials 单独注册。
• 常规通知/OTP 场景不需要，默认 REST v2。

4. 全量错误码与重试语义

status_code	含义	发送结果	可重试	处理建议
1000	Success	SENT	—	记录 message_id
1001	Invalid sender ID / short code	FAILED	否	校验 sender_name 注册
1002	Network not allowed	FAILED	否	运营商未授权，剔除号码
1003	Invalid mobile number	FAILED	否	校验号码格式
1004	Insufficient credit	FAILED	充值后	告警充值，余额恢复可重投
1005	Database / internal error	FAILED	是	重试 1 次，持续联系支持
1006	Invalid API key / credentials	FAILED	否	检查 h_api_key（人工介入）
1007	Db connection failed	FAILED	是	重试
1008	Db selection failed	FAILED	是	重试
1009	Invalid JSON body	FAILED	否	校验请求体（客户端 Bug）
1010	Request type not supported	FAILED	否	检查版本/请求方式
1011	Account suspended / invalid user state	FAILED	否	联系支持
1012	Mobile number in DND	FAILED	否	免打扰名单，跳过
1013	Invalid API Key	FAILED	否	同 1006
1014	IP not allowed	FAILED	否	补配 IP 白名单

归类速查：

• SENT：1000
• FAILED-参数类（不重试）：1001 1002 1003 1009 1010 1012
• FAILED-账户/配置（不重试，告警）：1004 1006 1011 1013 1014
• FAILED-供应商系统（可重试）：1005 1007 1008

5. 接入注意事项

1. 不要用 HTTP 状态码判断成败：恒 200，必须解析 status_code。
2. 多号码逐条处理：响应是数组，每个号码一条结果，部分失败需按号码明细回传。
3. 余额监控：预付费模式，建议接 /v2/sms/units 定时巡检 + 1004 告警充值。
4. 可重试错误码（1005/1007/1008）配重试次数上限，避免打爆供应商。
5. 敏感信息：API Key 禁止打印日志；短信内容视业务评估脱敏。

接入待确认

编号	问题	默认假设
Q1	是否有独立测试环境 Base URL	暂用生产地址 + 不同 API Key 区分
Q2	IP 白名单是否必须（1014 暗示存在）	默认需要，提前报出口 IP
Q3	Rate Limit / QPS 上限	暂按保守并发控制
Q4	Sender ID 注册流程与审批周期	接入前必须完成注册
Q5	余额预检（发送前查 units）还是 1004 兜底	建议直接发送 + 1004 告警，省一次调用