您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 綜合知識

PHP 微信小店 API 調用實戰：cURL 封裝、JSON 參數構建、Access Token 管理、常見錯誤碼與除錯技巧

編輯：PHP 綜合知識

微信小店 API 採用「POST + JSON」統一格式，參數結構嚴格，常見失敗原因：JSON 格式錯誤、Access Token 過期、參數欄位名稱大小寫錯誤、商品 ID 類型不符。本文提供最小可用封裝、實戰調用範例、除錯清單。

核心請求封裝

 $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_SSL_VERIFYPEER => true,
        CURLOPT_SSL_VERIFYHOST => 2,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    ]);
    if ($data) {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
    }
    $res = curl_exec($ch);
    if (curl_errno($ch)) {
        throw new RuntimeException('cURL error: ' . curl_error($ch));
    }
    curl_close($ch);
    $arr = json_decode($res, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new RuntimeException('Invalid JSON response: ' . $res);
    }
    return $arr;
}

/** 獲取 Access Token (簡易版，生產請加快取) */
function getWxToken(string $appId, string $appSecret): string {
    $url = "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid={$appId}&secret={$appSecret}";
    $res = wxRequest($url);
    if (isset($res['errcode'])) throw new RuntimeException("Token error: {$res['errmsg']}");
    return $res['access_token'];
}

實戰調用範例

$appId = 'YOUR_APPID';
$appSecret = 'YOUR_SECRET';
$token = getWxToken($appId, $appSecret);

// 1. 獲取所有上架商品 (狀態 1)
$res = wxRequest("https://api.weixin.qq.com/merchant/getbystatus?access_token={$token}", [
    'status' => 1,
    'page' => 1,
    'page_size' => 50,
]);
print_r($res);

// 2. 獲取所有分組
$res = wxRequest("https://api.weixin.qq.com/merchant/group/getall?access_token={$token}", []);
print_r($res);

// 3. 根據分組 ID 獲取商品
$groupId = 207061749;
$res = wxRequest("https://api.weixin.qq.com/merchant/group/getbyid?access_token={$token}", [
    'group_id' => $groupId,
]);
print_r($res);

// 4. 獲取單個商品詳情
$productId = 'pf82VwN45zr8eOlur5mAiSTjg8WU';
$res = wxRequest("https://api.weixin.qq.com/merchant/get?access_token={$token}", [
    'product_id' => $productId,
]);
print_r($res);

JSON 參數構建避坑指南

錯誤	正確	說明
`'{"status": 1}'` (字串)	`['status' => 1]` (陣列)	PHP 陣列經 `json_encode` 自動生成合法 JSON，避免手寫字串出錯
`'{"product_id": "pid"}'`	`['product_id' => 'pid']`	欄位名稱區分大小寫，必須與文檔一致
數字型 ID 傳成字串	文檔要求數字時用 `123`，字串時用 `'123'`	`group_id` 通常為數字，`product_id` 為字串
中文未編碼	`json_encode($data, JSON_UNESCAPED_UNICODE)`	避免 Unicode 轉義導致簽名驗證失敗 (部分介面需簽名)

常見錯誤碼快速查表

$errorMap = [
    42001 => 'access_token 過期/無效 → 重新獲取',
    40001 => 'AppSecret 錯誤',
    45009 => '調用頻率超限 → 指數退避重試',
    45028 => '商品不存在',
    45029 => '分組不存在',
    45030 => '庫存不足',
    45047 => '郵費模板不存在',
    45058 => '商品狀態不允許操作',
    45059 => 'SKU 不存在',
    -1    => '系統繁忙 → 重試',
];

function wxCheck(array $res): void {
    if (($res['errcode'] ?? 0) !== 0) {
        $code = $res['errcode'];
        $msg = $res['errmsg'] ?? 'Unknown';
        throw new RuntimeException("Wechat API error [$code]: $msg - " . ($errorMap[$code] ?? ''));
    }
}

除錯技巧

原始請求/回應記錄：在 wxRequest 中記錄 $url、$data、$res、耗時，存入日誌或資料表。
Postman/Insomnia 測試：先在客戶端跑通，再移植到代碼，排除參數錯誤。
對比官方文檔版本：微信介面常更新，確認文檔日期與 merchant 版本。
沙箱環境：微信提供測試號，避免污染正式數據。
IP 白名單：公眾號後台需配置服務器 IP 白名單，否則 40164 (IP 不在白名單)。

生產級封裝建議

類別化：WechatShopClient 封裝 Token 快取、重試、限流、日誌。
介面化：定義 WechatShopInterface，便於測試 Mock、多版本切換。
異常分層：WechatApiException(含 errcode)、WechatNetworkException、WechatAuthException。
非同步化：寫操作推入佇列，消費者串行處理，避免並發衝突。

微信小店 API 核心在於「正確的 JSON 結構、有效的 Access Token、頻率控制」。掌握 cURL 封裝、JSON 編碼選項、錯誤碼映射三大基礎，配合結構化日誌與非同步架構，即可構建穩健的微信電商整合層。