kylin987/jd-sp-api-sdk

京东 SP-API PHP SDK (RESTful 标准化接口)

v1.5.1 2026-03-17 03:05 UTC

Requires

• php: >=7.4
• ext-curl: *
• ext-json: *
• ext-openssl: *
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^9.0

MIT

• kylin987

README

京东新一代 SP-API（RESTful 标准化接口）PHP SDK

安装

composer require kylin987/jd-sp-api-sdk

快速开始

1. 初始化配置和 API 客户端

<?php
require_once __DIR__ . '/vendor/autoload.php';

use JdSpApi\Configuration;
use JdSpApi\Api\SkusApi;
use JdSpApi\Request\Product\ListSkusRequest;

// 初始化配置
$config = new Configuration();
$config->setHost('https://api-cn.jd.com/rest');  // 正式环境
// $config->setHost('https://api-cn-pre.jd.com/rest');  // 预发环境
$config->setAppKey('your_appKey');
$config->setAppSecret('your_appSecret');
$config->setAccessToken('your_accesToken');
$config->setSignMethod(\JdSpApi\Signer::SIGN_METHOD_HMAC_SHA256); // 可选：md5, hmacsha256, hmacmd5

// 创建 API 实例
$apiInstance = new SkusApi($config);

2. 调用 SKU 列表接口

// 创建请求对象
$request = new ListSkusRequest();
$request->setWareId(123456);
$request->setPageNo(1);
$request->setPageSize(20);
$request->setSkuStatus(1); // 1-上架，2-下架，3-全部

try {
    $result = $apiInstance->listSkus($request);
    
    if ($result['success']) {
        print_r($result['data']);
    } else {
        foreach ($result['errorList'] as $error) {
            echo "Error {$error['code']}: {$error['message']}\n";
        }
    }
} catch (\Exception $e) {
    echo 'Exception when calling SkusApi->listSkus: ', $e->getMessage(), PHP_EOL;
}

3. 调用订单接口

use JdSpApi\Api\OrdersApi;
use JdSpApi\Request\Order\GetOrderRequest;

// 创建订单 API 实例
$ordersApi = new OrdersApi($config);

// 获取订单详情
$orderRequest = new GetOrderRequest();
$orderRequest->setOrderId('300695175502');
$orderRequest->setScopeSet(['consigneeInfo', 'buyerRemark']);

try {
    $result = $ordersApi->getOrder($orderRequest);
    print_r($result);
} catch (\Exception $e) {
    echo 'Exception: ', $e->getMessage(), PHP_EOL;
}

4. 调用商品接口

use JdSpApi\Api\WaresApi;
use JdSpApi\Request\Ware\GetWareRequest;

$waresApi = new WaresApi($config);

$wareRequest = new GetWareRequest();
$wareRequest->setWareId(123456);
$wareRequest->setField(['wareId', 'title', 'price']);

try {
    $result = $waresApi->getWare($wareRequest);
    print_r($result);
} catch (\Exception $e) {
    echo 'Exception: ', $e->getMessage(), PHP_EOL;
}

配置选项

$config = new Configuration();

// 必选配置
$config->setHost('https://api-cn.jd.com/rest');  // API 地址
$config->setAppKey('your_appKey');               // 应用 AppKey
$config->setAppSecret('your_appSecret');         // 应用 AppSecret
$config->setAccessToken('your_accesToken');      // 用户 AccessToken

// 可选配置
$config->setSignMethod(\JdSpApi\Signer::SIGN_METHOD_HMAC_SHA256); // 签名方式
$config->setTimeout(30);  // 超时时间（秒）
$config->setDebug(true);  // 调试模式

签名方式

签名方式	常量	说明
MD5	Signer::SIGN_METHOD_MD5	默认兼容方式
HmacSHA256	Signer::SIGN_METHOD_HMAC_SHA256	推荐，更安全
HmacMD5	Signer::SIGN_METHOD_HMAC_MD5	备选方案

环境配置

// 正式环境
$config->setHost(Configuration::HOST_PROD);

// 预发环境
$config->setHost(Configuration::HOST_PRE);

错误处理

try {
    $result = $apiInstance->listSkus($request);
    
    if (!$result['success']) {
        foreach ($result['errorList'] as $error) {
            echo "Error {$error['code']}: {$error['message']}\n";
        }
    }
} catch (\Exception $e) {
    echo "Request failed: " . $e->getMessage();
}

响应格式

成功响应

{
  "success": true,
  "data": {
    // 业务数据
  }
}

错误响应

{
  "success": false,
  "errorList": [
    {
      "code": "99900130002",
      "message": "无效签名，请确认传参是否正确",
      "details": "..."
    }
  ],
  "data": {}
}

已实现的 API

订单 API (OrdersApi)

• ✅ getOrder() - 获取订单详情
• ✅ updateOrderRemark() - 更新订单备注

商品 SKU API (SkusApi)

• ✅ listSkus() - SKU 列表查询

商品 API (WaresApi)

• ✅ getWare() - 获取商品详情

请求类参考

ListSkusRequest

$request = new ListSkusRequest();
$request->setWareId(123456);           // 商品 ID
$request->setSkuIds([123, 456]);       // SKU ID 列表筛选
$request->setSkuStatus(1);             // SKU 状态：1-上架，2-下架，3-全部
$request->setPageNo(1);                // 页码
$request->setPageSize(20);             // 每页条数（最大 100）
$request->setRequestIdentity('vender'); // 业务身份：vender/supplier/userPin

GetOrderRequest

$request = new GetOrderRequest();
$request->setOrderId('300695175502');  // 订单 ID
$request->setScopeSet(['consigneeInfo', 'buyerRemark']); // 返回字段范围

UpdateOrderRemarkRequest

$request = new UpdateOrderRemarkRequest();
$request->setOrderId('300695175502');  // 订单 ID
$request->setRemark('客户要求下午配送'); // 备注内容

GetWareRequest

$request = new GetWareRequest();
$request->setWareId(123456);           // 商品 ID
$request->setField(['wareId', 'title', 'price']); // 返回字段（最多 100 个）

License

MIT License