NNumFlow

入门

API Key 认证

NumFlow API 使用账户级 API Key 认证。每个 Key 只可访问所属账户的余额与订单。

发送认证信息

每个请求都要传入 API Key、Unix 时间戳、一次性 Nonce 和 HMAC-SHA256 签名：

METHOD=GET
PATH_NAME=/api/v1/balance
TIMESTAMP=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_HASH=$(printf '' | openssl dgst -sha256 -r | cut -d' ' -f1)
CANONICAL=$(printf '%s\n%s\n%s\n%s\n%s' "$METHOD" "$PATH_NAME" "$TIMESTAMP" "$NONCE" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$NUMFLOW_API_SECRET" -r | cut -d' ' -f1)

curl "https://numflow-sms.com$PATH_NAME" \
  -H "X-API-Key: $NUMFLOW_API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

签名原文为 METHOD\nPATH\nTIMESTAMP\nNONCE\nSHA256(BODY)。Key 以 nf_key_ 开头，Secret 只显示一次，两者都只能保存在服务端。

时间戳允许偏差 5 分钟，Nonce 在窗口内不得重复。请签名对外请求的完整 path，例如 /api/v1/balance。

权限与数据隔离

NumFlow 根据 API Key 自动识别账户。请求体中的用户标识不会用于授权，订单查询、完成和取消操作也只能作用于当前账户拥有的订单。

Key 缺失、无效或已撤销时，API 返回 HTTP 401 和 API_UNAUTHENTICATED。

幂等请求

获取号码时必须发送唯一的 Idempotency-Key。同一账户重复提交同一个键与相同参数时，NumFlow 返回已有订单；参数不同时返回冲突。

Idempotency-Key: order-your-unique-reference-001

密钥管理建议

  • 按应用或环境分别创建 Key，避免多人共用。
  • 怀疑泄露时立即撤销旧 Key 并更新服务端配置。
  • 错误日志中只记录请求引用，不记录完整 API Key。