GETTING STARTED

商家接入文档

通过统一的 HMAC-SHA256 签名协议，安全调用蜀企集团 API 开放平台的自有和聚合数据服务。

接入流程

注册并登录客户中心
创建沙箱或生产应用，保存 AppId 和 AppSecret
在 API 权限页面确认接口已开通
按照本文生成签名并发起请求
通过 Request ID 查询调用明细

环境与地址

环境	基础地址	用途
生产环境	`https://api.shuqitg.com/v1`	正式业务调用
沙箱环境	`https://api.shuqitg.com/sandbox/v1`	开发和联调

应用环境必须与接口地址一致。沙箱 AppId 不能调用生产地址，生产 AppId 也不能调用沙箱地址。

身份认证

每次请求必须包含以下请求头：

请求头	必填	说明
`X-App-Id`	是	客户中心创建应用后获得
`X-Timestamp`	是	当前 Unix 秒级时间戳，允许误差5分钟
`X-Nonce`	是	每次请求唯一随机字符串，5分钟内不可重复
`X-Signature`	是	64位小写十六进制 HMAC-SHA256 签名
`Content-Type`	是	固定为 `application/json`

AppSecret 只在创建应用时展示一次，不应放入前端网页、小程序或公开代码仓库。

签名算法

按以下顺序用换行符 \n 拼接签名原文：

HTTP_METHOD
REQUEST_PATH
SORTED_QUERY_STRING
SHA256_COMPACT_JSON_BODY
TIMESTAMP
NONCE

POST 请求没有查询参数时，第三行保留为空。请求体使用无空格的紧凑 JSON 字符串计算 SHA-256。

签名原文示例

POST
/v1/ip/location

589e...请求体SHA256...
1783900000
550e8400-e29b-41d4-a716-446655440000

最终签名：

hex(HMAC-SHA256(AppSecret, canonicalString))

请求规范

统一使用 HTTPS。
当前业务接口使用 POST 和 JSON 请求体。
单次请求体最大 2MB。
同一 Nonce 不得重复使用。
默认应用总限流20 QPS，接口页展示单接口限制，最终取较小值。
敏感 API 必须配置 IP 白名单。

统一响应

{
  "code": "SUCCESS",
  "message": "查询成功",
  "requestId": "ad7e7b898aa52ab8ceb42c2e74652081",
  "data": {},
  "billing": {
    "charged": false,
    "amount": "0.00"
  }
}

requestId 是平台唯一调用编号，排查问题时请提供该值。

通用错误码

HTTP	错误码	说明
400	INVALID_PARAMETER	请求参数格式错误
401	INVALID_APP_ID	AppId不存在或应用不可用
401	INVALID_SIGNATURE	签名缺失或验证失败
401	TIMESTAMP_EXPIRED	时间戳超过5分钟
403	ENVIRONMENT_MISMATCH	应用与调用环境不一致
403	REAL_NAME_REQUIRED	需要完成实名认证
403	APPROVAL_REQUIRED	敏感API尚未审核开通
403	IP_NOT_ALLOWED	来源IP不在白名单
409	DUPLICATE_REQUEST	Nonce已使用
429	RATE_LIMIT_EXCEEDED	超过QPS限制
502	UPSTREAM_UNAVAILABLE	资源服务暂不可用
504	UPSTREAM_TIMEOUT	资源服务响应超时

POST

IPv4归属地查询

/v1/ip/location · 公开自动开通 · 免费

请求参数

字段	类型	必填	说明
ip	string	是	标准 IPv4 地址，例如 114.114.114.114

请求示例

{ "ip": "114.114.114.114" }

data 字段

返回 IP、简明归属地，以及国家、省市区、运营商、行政区划代码、经纬度等详细字段。

POST

手机号归属地查询

/v1/mobile/location · 公开自动开通 · 免费

请求参数

字段	类型	必填	说明
mobile	string	是	中国大陆11位手机号

请求示例

{ "mobile": "13800138000" }

data 字段

返回号码前7位、省份、城市、运营商、区号、邮编、行政区划代码和简明归属地。

Node.js 完整示例

const crypto = require('crypto');

const appId = 'sq_your_app_id';
const appSecret = 'your_app_secret';
const path = '/v1/ip/location';
const body = JSON.stringify({ ip: '114.114.114.114' });
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID();
const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
const canonical = ['POST', path, '', bodyHash, timestamp, nonce].join('\n');
const signature = crypto.createHmac('sha256', appSecret).update(canonical).digest('hex');

const response = await fetch('https://api.shuqitg.com' + path, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-App-Id': appId,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature
  },
  body
});
console.log(await response.json());

PHP 签名示例

$path = '/v1/mobile/location';
$body = json_encode(['mobile' => '13800138000'], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$bodyHash = hash('sha256', $body);
$canonical = implode("\n", ['POST', $path, '', $bodyHash, $timestamp, $nonce]);
$signature = hash_hmac('sha256', $canonical, $appSecret);