淘宝选品接口实战：从召回、详情、佣金到转链的 Java 接入笔记

APIshop

墨衍会员 · AI 创作全网分发码龄1年

关注

原创最新推荐文章于 2026-10-12 22:13:27 发布 205 阅读 AI 写同款· GEO 优化 ›

1. 先厘清：“淘宝选品接口”不是单个 API

做淘宝客/导购/内容电商选品，本质是一条链路：

候选召回：关键词、类目、榜单、活动物料、高佣/大额券筛选；
详情校验：标题、主图、价格、库存、店铺分、类目、服务标签；
收益评估：佣金率、券后价、补贴、定向计划、历史销量；
转链产出：长链/短链、淘口令、二合一券链接；
效果归因：点击、付款、结算、退款、渠道/会员/Relation ID。

官方常用接口大致分三类：

导购/淘宝客选品：taobao.tbk.dg.material.optional 通用物料搜索，taobao.tbk.dg.material.optional.upgrade 升级版，taobao.tbk.dg.material.recommend 按物料/官方商品库召回，taobao.tbk.item.info.get 商品详情。官方文档把 material.optional 定义为“通用物料搜索API（导购）”，返回结果中含 total_results、result_list.map_data、券信息、佣金字段、类目与店铺字段等。升级版接口在文档中标注为免费、无需用户授权，且收益信息放在 publish_info.income_info、价格促销放在 price_promotion_info。 taobao.tbk.item.info.get 则属于淘宝客公用物料信息查询。
商家自用商品/库存：如果你选品是为了自己店铺运营而不是 CPS 推广，看 taobao.items.onsale.get、taobao.item.seller.get、taobao.items.inventory.get 这类需要店铺授权的接口；开放平台把交易/商品场景接口列在商品同步、订单同步等流程中。
转化组件：taobao.tbk.tpwd.create、taobao.tbk.spread.get、taobao.tbk.dg.punish.order.get 之外的订单明细类接口等。核心原则：能走官方 API 就不要抓页面，不要逆向滑块，不要买黑产 Cookie。

2. 权限与凭证：选品系统的“地基”

接入流程通常是：注册开放平台/联盟账号 → 实名或企业认证 → 创建应用 → 选择类目与 API 权限组 → 提交业务场景 → 获取 app_key/app_secret → 淘宝客侧再维护推广位 adzone_id / pid。开放平台通用流程包括创建应用、获取 API 密钥、按需求申请接口权限并提交资料审核。

实践建议：

app_secret、联盟 pid、渠道 relation_id/special_id 只放服务端；前端、App、小程序永不直连签名。
选品服务与转链服务拆库：选品库允许过期，点击转链必须实时。
对 adzone_id 做多租户隔离；不要跨推广位混用链接。
关注限流与权限变更：官方文档与控制台权限页是唯一事实来源，第三方博客只用于排错参考。

3. Java 公共参数与签名示例

下面示例采用 TOP 常见 sign_method=md5 规则：剔除空值与 sign，按键排序，secret + k1v1k2v2... + secret 后 MD5 大写。若你的应用后台开通的是 HMAC 类签名，按当前文档替换 sign() 实现即可；不要硬编码旧规则。

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Map;
import java.util.TreeMap;

public final class TopClient {
    private static final DateTimeFormatter TS = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

    public static String md5TopSign(Map<String, String> params, String appSecret) {
        TreeMap<String, String> sorted = new TreeMap<>();
        params.forEach((k, v) -> {
            if (v != null && !v.isEmpty() && !"sign".equals(k)) sorted.put(k, v);
        });

        StringBuilder sb = new StringBuilder(appSecret);
        sorted.forEach((k, v) -> sb.append(k).append(v));
        sb.append(appSecret);

        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] dig = md.digest(sb.toString().getBytes(StandardCharsets.UTF_8));
            StringBuilder hex = new StringBuilder();
            for (byte b : dig) hex.append(String.format("%02X", b));
            return hex.toString();
        } catch (Exception e) {
            throw new IllegalStateException("sign error", e);
        }
    }

    public static String hmacSha256Hex(Map<String, String> params, String appSecret) {
        TreeMap<String, String> sorted = new TreeMap<>();
        params.forEach((k, v) -> {
            if (v != null && !v.isEmpty() && !"sign".equals(k)) sorted.put(k, v);
        });
        StringBuilder sb = new StringBuilder();
        sorted.forEach((k, v) -> sb.append(k).append(v));

        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(appSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
            byte[] raw = mac.doFinal(sb.toString().getBytes(StandardCharsets.UTF_8));
            StringBuilder hex = new StringBuilder();
            for (byte b : raw) hex.append(String.format("%02x", b));
            return hex.toString();
        } catch (Exception e) {
            throw new IllegalStateException("hmac sign error", e);
        }
    }

    public static Map<String, String> commonParams(String appKey, String method) {
        Map<String, String> p = new TreeMap<>();
        p.put("app_key", appKey);
        p.put("method", method);
        p.put("format", "json");
        p.put("v", "2.0");
        p.put("timestamp", LocalDateTime.now().format(TS));
        p.put("sign_method", "md5"); // 若后台配置 hmac，可切换 sign/hmacSha256Hex
        return p;
    }

    public static String form(Map<String, String> params) {
        StringBuilder sb = new StringBuilder();
        params.forEach((k, v) -> {
            if (v == null) return;
            if (sb.length() > 0) sb.append('&');
            sb.append(URLEncoder.encode(k, StandardCharsets.UTF_8))
              .append('=')
              .append(URLEncoder.encode(v, StandardCharsets.UTF_8));
        });
        return sb.toString();
    }
}

4. 选品召回：升级版物料搜索

升级版返回更贴近选品：收益、近 2 小时/当日推广销量、最终促销价、未来活动价、满减路径都在结构化字段里。官方示例中 publish_info.income_info.commission_rate 为比例乘 100 后的整数，如 55 表示 5.5%；two_hour_promotion_sales、daily_promotion_sales 可用于热度粗排；price_promotion_info.final_promotion_price 更接近用户到手价判断。

import java.io.IOException;
import java.util.Map;
import java.util.TreeMap;
import okhttp3.*;

public class TbkSelection {
    private static final String GATEWAY = "https://eco.taobao.com/router/rest";
    private final OkHttpClient http = new OkHttpClient();
    private final String appKey;
    private final String appSecret;
    private final String adzoneId;

    public TbkSelection(String appKey, String appSecret, String adzoneId) {
        this.appKey = appKey;
        this.appSecret = appSecret;
        this.adzoneId = adzoneId;
    }

    public String searchOptionalUpgrade(String keyword, long pageNo, long pageSize) throws IOException {
        Map<String, String> p = new TreeMap<>(TopClient.commonParams(appKey, "taobao.tbk.dg.material.optional.upgrade"));
        p.put("adzone_id", adzoneId);
        p.put("q", keyword);
        p.put("page_no", String.valueOf(pageNo));
        p.put("page_size", String.valueOf(pageSize));
        // 选品常用过滤：按需开启，不要一次堆满
        // p.put("has_coupon", "true");
        // p.put("sort", "tk_rate_des");     // 以文档枚举为准
        // p.put("start_price", "20");
        // p.put("end_price", "200");
        // p.put("start_tk_rate", "100");    // 如文档要求乘100，则1%传100
        // p.put("is_tmall", "true");
        // p.put("itemloc", "杭州");
        p.put("sign", TopClient.md5TopSign(p, appSecret));

        Request req = new Request.Builder()
                .url(GATEWAY)
                .post(RequestBody.create(TopClient.form(p), MediaType.get("application/x-www-form-urlencoded; charset=utf-8")))
                .build();

        try (Response resp = http.newCall(req).execute()) {
            String body = resp.body() == null ? "" : resp.body().string();
            if (!resp.isSuccessful()) throw new IOException("HTTP " + resp.code() + ": " + body);
            return body;
        }
    }
}

注意：不同接口对佣金/比例的缩放可能不同。旧版字段常见 commission_rate=1550表示15.5%，新版/升级版的 income_rate 示例直接给 5.50。入库前统一归一化为 Decimal commissionRate，不要在前端混用“1550 / 15.5 / 0.155”。

5. 详情校验与商品补充信息

taobao.tbk.item.info.get 适合做候选商品批量详情补齐；但不要把详情接口当成高并发实时库存源。 CPS 场景更重要的是“能否推广、券是否有效、当前到手价多少”。

public String itemInfoGet(String numIids, String fields) throws IOException {
    Map<String, String> p = new TreeMap<>(TopClient.commonParams(appKey, "taobao.tbk.item.info.get"));
    p.put("num_iids", numIids);     // 多个 id 用逗号，具体上限看文档
    p.put("fields", fields);        // 按文档指定返回字段，别 fields=*
    p.put("sign", TopClient.md5TopSign(p, appSecret));

    Request req = new Request.Builder()
            .url(GATEWAY)
            .post(RequestBody.create(TopClient.form(p), MediaType.get("application/x-www-form-urlencoded; charset=utf-8")))
            .build();
    try (Response resp = http.newCall(req).execute()) {
        String body = resp.body() == null ? "" : resp.body().string();
        if (!resp.isSuccessful()) throw new IOException("HTTP " + resp.code() + ": " + body);
        return body;
    }
}

6. 选品打分：别只按佣金率排序

建议把候选商品归一化成 SelectionCandidate 后打分：

public class SelectionCandidate {
    public String itemId;
    public String title;
    public String categoryName;
    public String shopTitle;
    public BigDecimal finalPrice;       // 到手价/预估促销价
    public BigDecimal commissionRate;   // 0.155 = 15.5%
    public BigDecimal commissionAmount; // 预估佣金，若接口返回
    public Long dailySales;
    public Long twoHourSales;
    public BigDecimal shopDsr;          // 注意部分接口用*5或差值表示，先归一
    public Boolean hasCoupon;
    public String couponInfo;
    public String clickUrl;
    public String couponShareUrl;
}

public class ScoreService {
    public double score(SelectionCandidate c) {
        // 示例权重：按业务调参；所有分子分母先做异常值截断
        double income = clamp(c.commissionAmount == null ? 0 : c.commissionAmount.doubleValue(), 0, 100);
        double hot = log1p(c.dailySales == null ? 0 : c.dailySales);
        double price = c.finalPrice == null ? 0 : clamp(100 - c.finalPrice.doubleValue(), 0, 100);
        double dsr = clamp(c.shopDsr == null ? 0 : c.shopDsr.doubleValue(), 0, 5) * 20;
        double couponBoost = Boolean.TRUE.equals(c.hasCoupon) ? 8 : 0;
        return 0.45 * income + 0.25 * hot + 0.15 * price + 0.10 * dsr + couponBoost;
    }

    private static double clamp(double v, double min, double max) { return Math.max(min, Math.min(max, v)); }
    private static double log1p(double v) { return Math.log1p(Math.max(0, v)) * 10; }
}

工程上要加三类护栏：