国美云API请求必须携带X-Gome-AppId和X-Gome-Sign头，签名规则为md5(appSecret+timestamp+nonce+bodyJson)，timestamp为秒级时间戳，body需为原始JSON字符串；Content-Type必须为application/json; charset=utf-8；TLS需启用SNI并指定TLSv1.2；响应中文需检测编码后转UTF-8；时间字段格式严格为yyyy-MM-dd HH:mm:ss且时区设为Asia/Shanghai。
国美云 API 的 PHP 请求必须带 X-Gome-AppId 和 X-Gome-Sign 头
国美云（Gome Cloud）开放平台不支持直接数据库连接或文件读写，所有数据交互都走 HTTP API，且强制校验签名。漏掉任一请求头，返回 401 Unauthorized 或 {"code":4001,"msg":"签名错误"}。
签名规则是：md5(appSecret + timestamp + nonce + bodyJson)（注意 body 是原始 JSON 字符串，非 URL 编码，且 timestamp 是秒级 Unix 时间戳）。PHP 中容易错在：用 microtime(true) 生成毫秒时间、body 被自动转义、JSON 中字段顺序与文档不一致。
-
appSecret和appId必须从国美云控制台「应用管理」获取，不能复用测试环境密钥到生产 - 请求
Content-Type必须为application/json; charset=utf-8，否则签名验证会失败 - 推荐用
file_get_contents('php://input')原样读取 raw body，避免$_POST自动解析破坏 JSON 结构
curl_init() 发起 POST 请求时需禁用 CURLOPT_SSL_VERIFYPEER 吗？
国美云线上接口域名（如 https://openapi.gomecloud.com）使用的是受信 CA 签发的证书，不应关闭证书校验。关闭后可能通过本地测试，但上线后因中间人攻击风险被拦截，或触发国美云服务端 TLS 版本协商失败（他们要求 TLS 1.2+）。
真正常见问题是 PHP cURL 默认不携带 SNI 扩展（尤其旧版 PHP 5.6），导致 Nginx 返回默认证书，握手失败。解决方式是显式设置：
立即学习“PHP免费学习笔记（深入）”；
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-Gome-AppId: your_app_id',
'X-Gome-Sign: ' . $sign,
'Content-Type: application/json; charset=utf-8'
]);
- 务必检查服务器 OpenSSL 版本 ≥ 1.0.1，否则
CURL_SSLVERSION_TLSv1_2不生效 - 不要用
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false)绕过问题，应查系统 CA 证书路径是否正确（curl_setopt($ch, CURLOPT_CAINFO, '/etc/ssl/certs/ca-certificates.crt')） - 调试时加
curl_setopt($ch, CURLOPT_VERBOSE, true)查看 TLS 握手日志
国美云返回的 JSON 数据里有中文字段名，json_decode() 怎么避免乱码？
国美云响应头明确声明 Content-Type: application/json; charset=utf-8，但 PHP json_decode() 默认只处理 UTF-8 字符串。如果响应体实际含 GBK 编码（极少数老接口存在），json_decode() 会返回 null 且 json_last_error() 为 JSON_ERROR_UTF8。
安全做法是先检测编码再转码：
$raw = curl_exec($ch);
$encoding = mb_detect_encoding($raw, ['UTF-8', 'GBK'], true);
if ($encoding !== 'UTF-8') {
$raw = mb_convert_encoding($raw, 'UTF-8', $encoding);
}
$data = json_decode($raw, true);
- 不要依赖
mb_internal_encoding('UTF-8')，它不影响json_decode行为 - 国美云文档未明说字段名编码，但实测订单类接口（如
/order/query）返回字段名是 UTF-8，值可能是 GBK，需单独对 value 转码 - 若
$data === null，立刻打印json_last_error_msg()，比盲目转码更高效
PHP 写入国美云数据时，body 中的时间字段格式必须严格匹配 yyyy-MM-dd HH:mm:ss
国美云多数写接口（如商品上架 /item/publish、库存同步 /stock/update）要求时间字段为字符串格式 yyyy-MM-dd HH:mm:ss，而非时间戳或 ISO8601。传错格式会导致 {"code":4000,"msg":"参数格式错误"}，且错误信息不提示具体哪个字段出错。
- PHP 中用
date('Y-m-d H:i:s', $timestamp)，别用date('c')或 Carbon 的toDateTimeString()（后者可能带毫秒） - 注意时区：国美云服务端按东八区（
Asia/Shanghai）解析，PHP 脚本需设date_default_timezone_set('Asia/Shanghai')，否则time()取出的时间可能偏移 - 空值字段不能传
null或空字符串，必须按文档省略该 key，或传指定默认值（如"publish_time":""可能被拒绝，而"publish_time":null更可能触发校验失败）
