API 接口文档

本 API 使用 OAuth2.0 协议进行身份认证。客户端在调用业务接口之前，必须先获取 Access Token，并在请求头中携带该 Token。

一、OAuth2.0 认证

本系统支持两种 OAuth2.0 授权方式：

前置条件

联系服务提供方注册您的应用，获取以下凭据：

方式一：Authorization Code Grant（授权码模式）

适用于需要用户授权的 Web 应用。

流程概览

GET /public/authorize.php?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&state={STATE}

GET {REDIRECT_URI}?code={AUTHORIZATION_CODE}&state={STATE}

POST /public/token.php
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={AUTHORIZATION_CODE}
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}
&redirect_uri={REDIRECT_URI}

Authorization: Basic base64(client_id:client_secret)

{
    "access_token": "8843534fa0deed...064c0ca20329d4acc4062",
    "token_type": "Bearer",
    "expires_in": 3600
}

{
    "error": "invalid_grant",
    "error_description": "Authorization code expired"
}

方式二：Client Credentials Grant（客户端凭证模式）

适用于服务器到服务器的后台通信，无需用户交互。

请求 Token

POST /public/token.php
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}

也支持 HTTP Basic Auth：

curl -X POST https://klwy.sdv3.com/public/token.php \
  -u "{CLIENT_ID}:{CLIENT_SECRET}" \
  -d "grant_type=client_credentials"

200 成功响应：

{
    "access_token": "8843534fa0deed...064c0ca20329d4acc4062",
    "token_type": "Bearer",
    "expires_in": 3600
}

二、调用业务接口

所有业务接口均需在请求头中携带 Access Token：

Authorization: Bearer {ACCESS_TOKEN}

ABC 查询接口

基本信息

请求参数

请求示例

curl "https://klwy.sdv3.com/public/abc.php?keyword=Alpha&page=1&page_size=10" \
  -H "Authorization: Bearer 8843534fa0deed...4c0ca20329d4acc4062"

成功响应

{
    "code": 0,
    "message": "ok",
    "data": {
        "list": [
            {
                "organization_name": "科勒集团",
                "organization_code": "KL",
                "warehouse_id": "0001",
                "warehouse_name": "大库",
                "sku_id": "EB1446-NF",
                "inventory_cnt": "1.00000000",
                "create_at": "2026-05-08",
                "update_at": "2026-05-08"
            },
            {
                "organization_name": "科勒集团",
                "organization_code": "KL",
                "warehouse_id": "0001",
                "warehouse_name": "大库",
                "sku_id": "P24490-LV-CP",
                "inventory_cnt": "1.00000000",
                "create_at": "2026-05-08",
                "update_at": "2026-05-08"
            },
            {
                "organization_name": "科勒集团",
                "organization_code": "KL",
                "warehouse_id": "0001",
                "warehouse_name": "大库",
                "sku_id": "K-23796T-1-0",
                "inventory_cnt": "1.00000000",
                "create_at": "2026-05-08",
                "update_at": "2026-05-08"
            }
        ],
        "pagination": {
            "page": 1,
            "page_size": 3,
            "total": 1284,
            "total_pages": 65
        }
    }
}

未授权响应 401

{
    "code": -1,
    "message": "Missing or malformed Authorization header",
    "data": null
}

Token 过期响应 401

{
    "code": -1,
    "message": "Access token expired",
    "data": null
}

三、公共响应格式

所有业务接口统一使用以下 JSON 结构：

{
    "code": 0,
    "message": "ok",
    "data": { ... }
}

四、完整接入示例（PHP）

<?php

$baseUrl      = 'https://klwy.sdv3.com/public';
$clientId     = 'your_client_id';
$clientSecret = 'your_client_secret';

// 1. 获取 Access Token（Client Credentials 模式）
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL        => $baseUrl . '/token.php',
    CURLOPT_POST       => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type'    => 'client_credentials',
        'client_id'     => $clientId,
        'client_secret' => $clientSecret,
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/x-www-form-urlencoded'],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!isset($response['access_token'])) {
    die('获取 Token 失败: ' . json_encode($response));
}

$accessToken = $response['access_token'];

// 2. 调用 ABC 查询接口
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => $baseUrl . '/abc.php?keyword=Alpha&page=1&page_size=10',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $accessToken,
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['code'] === 0) {
    print_r($response['data']);
} else {
    echo '请求失败: ' . $response['message'];
}

五、完整接入示例（cURL 命令行）

# 1. 获取 Token
TOKEN=$(curl -s -X POST "https://klwy.sdv3.com/public/token.php" \
  -d "grant_type=client_credentials" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# 2. 调用 ABC 接口
curl -s "https://klwy.sdv3.com/public/abc.php?keyword=Alpha" \
  -H "Authorization: Bearer $TOKEN"

六、错误码参考

OAuth2.0 错误（Token 端点）

业务接口错误

七、最佳实践

— End of Document —