1688 Custom 自定义 API 操作及返回值说明

最新推荐文章于 2026-06-15 19:29:49 发布

原创最新推荐文章于 2026-06-15 19:29:49 发布 · 987 阅读

5 ·

CC 4.0 BY-SA版权

文章标签：

#前端 #javascript #服务器

1688api 专栏收录该内容

33 篇文章

订阅专栏

一、概述

1688 平台提供了强大的 API 接口，以满足不同开发者的需求。其中，custom 自定义 API 允许开发者根据自己的业务需求，灵活地定义和调用特定的接口。本文将详细介绍如何操作 1688 的 custom 自定义 API，并对常见的返回值进行说明。

二、自定义 API 的基本操作

（一）申请自定义 API 权限

注册与认证：首先，你需要在 1688 开放平台注册开发者账号，并完成实名认证。
创建应用：在开放平台创建一个应用，获取 App Key 和 App Secret。
申请权限：在应用的接口管理中，申请 custom 自定义 API 的调用权限。

（二）定义自定义 API

接口名称：自定义 API 的名称，通常以 custom 开头，如 custom.getCustomData。
参数定义：根据业务需求定义接口的输入参数。
返回值定义：定义接口的返回值格式和内容。

（三）调用自定义 API

构建请求：根据定义的接口名称和参数，构建 HTTP 请求。
签名生成：使用 App Secret 对请求参数进行签名，确保请求的安全性。
发送请求：通过 HTTP 客户端发送请求，并处理返回的响应数据。

三、返回值说明

（一）成功返回

当请求成功时，1688 API 通常会返回一个 JSON 格式的响应数据。以下是一个典型的成功返回示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "customData": {
      "id": "12345",
      "name": "Custom Data",
      "value": "This is custom data"
    }
  }
}

code：状态码，200 表示请求成功。
message：返回信息，通常为 success。
data：返回的数据内容，具体结构根据自定义 API 的定义而定。

（二）失败返回

当请求失败时，API 会返回一个包含错误信息的响应。以下是一个典型的失败返回示例：

{
  "code": 400,
  "message": "Invalid parameter",
  "errors": [
    {
      "field": "num_iid",
      "message": "The num_iid parameter is required."
    }
  ]
}

code：状态码，400 表示请求参数错误。
message：返回信息，描述了错误的类型。
errors：详细的错误信息列表，每个错误包含字段名和错误描述。

（三）常见状态码

200：请求成功。
400：请求参数错误。
401：认证失败，通常是 App Key 或 App Secret 错误。
403：权限不足，通常是未申请接口权限或权限被限制。
500：服务器内部错误，通常是 API 服务端出现问题。

四、代码示例

以下是一个使用 Python 调用 1688 custom 自定义 API 的完整示例代码：

import requests
import hashlib
import time
import json

class AlibabaAPI:
    def __init__(self, app_key, app_secret):
        self.app_key = app_key
        self.app_secret = app_secret
        self.api_url = "https://gw.open.1688.com/openapi/param2/1/com.alibaba.open/custom.getCustomData"

    def sign(self, params):
        """生成签名"""
        sorted_params = sorted(params.items(), key=lambda x: x[0])
        sign_str = self.app_secret
        for k, v in sorted_params:
            sign_str += f"{k}{v}"
        sign_str += self.app_secret
        return hashlib.md5(sign_str.encode()).hexdigest().upper()

    def custom_get_custom_data(self, custom_params):
        """调用 custom.getCustomData API"""
        params = {
            "app_key": self.app_key,
            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
            "format": "json",
            "v": "2.0",
            "sign_method": "md5"
        }

        # 添加自定义参数
        params.update(custom_params)

        # 生成签名
        params["sign"] = self.sign(params)

        try:
            response = requests.get(self.api_url, params=params, timeout=10)
            response.raise_for_status()
            result = response.json()

            if "code" in result and result["code"] == 200:
                return {
                    "success": True,
                    "data": result["data"]
                }
            else:
                return {
                    "success": False,
                    "error_code": result.get("code", "Unknown"),
                    "error_msg": result.get("message", "Unknown error")
                }

        except requests.exceptions.RequestException as e:
            return {
                "success": False,
                "error_msg": f"请求异常: {str(e)}"
            }

if __name__ == "__main__":
    APP_KEY = "your_app_key"
    APP_SECRET = "your_app_secret"

    alibaba_api = AlibabaAPI(APP_KEY, APP_SECRET)

    custom_params = {
        "customId": "12345"
    }

    result = alibaba_api.custom_get_custom_data(custom_params)

    if result["success"]:
        print("获取自定义数据成功:")
        print(json.dumps(result["data"], ensure_ascii=False, indent=2))
    else:
        print(f"获取自定义数据失败: {result.get('error_msg', '未知错误')}")
        if "error_code" in result:
            print(f"错误代码: {result['error_code']}")