《1688供应商入驻API落地方案：supplier.* 接口的准入条件与数据同步》（附Python源码）
先拍结论：
1688 里“供应商入驻”通常不是你用买家 ERP 去调supplier.create这么简单。1688 开放平台侧：你是 ISV/ERP，做“供应商/商家能力集成”要走 ISP/ISV 入驻、应用权限、商家授权；1688 商家侧：供应商自己入驻 1688 是后台资质审核（营业执照、类目资质、诚信通、保证金），不是单纯 API；数据同步侧：ERP 和供应商之间真正跑起来的是「商品/库存/订单/物流/售后」四类同步，而不是“调一个 supplier 接口就入驻成功”。所以本文把“入驻准入”和“供应商数据同步”拆开讲，不然架构一定会混。
一、先纠正概念：没有“一个 supplier.join 接口”包打天下
1688 生态里相关主体：
角色 | 入口 | 是不是 API 为主 |
|---|---|---|
1688 商家/供应商入驻 1688 | 1688 商家后台 / 诚企入驻 | 后台表单 + 资质审核为主 |
ISV/ERP 接入开放平台 | open.1688.com | AppKey/AppSecret + 权限包 |
ISP 服务提供商入驻 | 开放平台合作伙伴 | 实名 + 营业执照 + 能力证明 |
分销商绑定供应商 | 分销管理 / 供销平台 | 商家授权 + offer 绑定 |
ERP 同步供应商商品库存 | 开放 API | product/* trade/* logistics/* |
所以“supplier.* 接口”在 1688 开放平台并没有像trade.order.get那样成为买家 ERP 的主接口族。更常见的是：
买家/分销商侧：
alibaba.product.*/alibaba.trade.*/alibaba.logistics.*商家/供应商侧：
alibaba.item.seller.*/alibaba.offer.*/ 商家后台 OpenAPI跨境分销：
alibaba.cpsMedia.*/global.product.operation
二、供应商准入条件（ERP 侧要校验什么）
ERP 在“添加一家 1688 供应商”时，不是存个店铺名就完事，要建供应商准入档案：
1. 平台侧硬条件
企业实名 / 个体工商户（个人号拿不到核心交易能力）
1688 商家店铺状态正常（非关店/处罚中）
供货类目和你的销售渠道匹配（美妆/3C/食品要额外资质）
是否开通：一件代发 / 分销严选 / 跨境寻源通 / 密文面单
是否签《信息共享协议》（影响 retailPrice / 佣金字段）
2. ERP 内部准入模型
from dataclasses import dataclass, field
from enum import Enum
class SupplierStatus(str, Enum):
PENDING = "pending" # 待审核
QUALIFIED = "qualified" # 可采购
RESTRICTED = "restricted" # 仅可铺货不可自动下单
BLOCKED = "blocked" # 违规/售罄/关店
@dataclass
class SupplierQualification:
supplier_id: str
shop_name: str
legal_entity: str = "" # 营业执照主体
categories: list[str] = field(default_factory=list)
supports_drop_ship: bool = False
supports_cross_border: bool = False
supports_encrypted_address: bool = False
signed_info_sharing: bool = False
credit_level: str = "" # 诚信通/实力商家等
return_window_days: int = 0
status: SupplierStatus = SupplierStatus.PENDING
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
class SupplierAdmissionService:
REQUIRED_FOR_AUTO_PURCHASE = {
"supports_drop_ship",
"supports_encrypted_address",
"signed_info_sharing",
}
def evaluate(self, q: SupplierQualification) -> SupplierStatus:
if not q.legal_entity:
return SupplierStatus.PENDING
if q.status == SupplierStatus.BLOCKED:
return SupplierStatus.BLOCKED
missing = self.REQUIRED_FOR_AUTO_PURCHASE - {
k for k, v in q.__dict__.items() if v is True
}
if missing:
return SupplierStatus.RESTRICTED
return SupplierStatus.QUALIFIED规则：能铺货 ≠ 能自动下单；能自动下单 ≠ 能收密文地址；能收密文 ≠ 能跨境代发。
三、供应商数据同步的四张表（不是一张 supplier 表）
生产里要把“供应商”和“供应商发出的数据”分开：
supplier_profile 供应商档案（主体/资质/状态） supplier_offer 供应商商品/offer 映射 supplier_stock 按 sku 的库存快照 supplier_order 采购单/退款/物流事件
1. 商品同步：增量，不全量扫
def sync_supplier_products(client, supplier_id, last_modified_min): page = 1 while True: resp = client.list_supplier_offers( supplier_id=supplier_id, modified_start=last_modified_min, page=page, page_size=50, ) for offer in resp.offers: upsert_offer(supplier_id, offer) if not resp.has_more: break page += 1
要点：
用
modified时间窗单页别贪大（20/50 一条）
下架商品要更新状态，不能只插不删
2. 库存同步：快照 + 变更，不信任“当前库存”
1688 库存是 B2B 快照：
amountOnSale阶梯库存
虚拟库存
下单即占 / 支付后占
@dataclass class StockSnapshot: offer_id: str sku_id: str amount_on_sale: int | None is_fuzzy: bool captured_at: float def is_trustable(s: StockSnapshot) -> bool: if s.amount_on_sale is None: return False if s.amount_on_sale in (-1, 999999): return False return True
规则：
模糊库存 → 标
unknown自动下单前必须再跑
createOrder.preview不拿“昨天库存”当“现在能买”
3. 订单/物流同步：消息 + 拉取双源
Webhook/消息：触发查单
alibaba.trade.get.buyerView：真相源logistics.trace.get：物流子状态供应商发错仓 / 无单号：进补偿队列
4. 资质/类目同步：低频但必须
供应商类目资质到期 → 禁止采购对应类目
食品/美妆/3C 资质失效 → 自动下架下游 listing
诚信通掉级 → 触发人工复核
四、供应商绑定流程（分销商侧）
def bind_supplier(erp_supplier_id, platform_supplier_id, scope: dict):
"""
scope:
- categories: ["home", "digital"]
- allow_auto_purchase: False
- allow_encrypted_address: False
- flow: "boutiquefenxiao" / "fenxiaonew" / ""
"""
profile = load_supplier_profile(platform_supplier_id)
if profile.status != "qualified":
raise PermissionError("供应商未通过准入，禁止绑定自动采购")
mapping = {
"erp_supplier_id": erp_supplier_id,
"platform_supplier_id": platform_supplier_id,
"scope": scope,
"bound_at": now(),
}
save_supplier_binding(mapping)
# 触发首次商品/库存增量同步
enqueue("sync.supplier.products", mapping)
enqueue("sync.supplier.stock", mapping)五、隐藏约束（供应商同步最坑的 7 条）
供应商入驻不是 API 一步到位，后台资质 + 开放平台权限是两件事
分销授权没开 → 商品能看，不能下代发单
零售价/代发价不返回 → 通常是因为严选/信息共享协议没签
库存是批发口径，和零售“有几件”不是一回事
供应商改模板/改货号 → 下游 SKU 映射会断
Webhook 会丢 → 必须轮询 modified 时间窗兜底
供应商关店/处罚 → 要有“停采 + 切备供 + 下游下架”三连动
六、供应商状态机（ERP 内部）
class SupplierLifecycle(str, Enum):
PROSPECT = "prospect" # 候选
ADMITTED = "admitted" # 资质过
BOUND = "bound" # 已绑定商品
ACTIVE = "active" # 正在采购
DEGRADED = "degraded" # 库存/资质异常
SUSPENDED = "suspended" # 人工暂停
REMOVED = "removed" # 清退
SUPPLIER_TRANSITIONS = {
SupplierLifecycle.PROSPECT: {"ADMITTED"},
SupplierLifecycle.ADMITTED: {"BOUND", "SUSPENDED"},
SupplierLifecycle.BOUND: {"ACTIVE", "SUSPENDED"},
SupplierLifecycle.ACTIVE: {"DEGRADED", "SUSPENDED", "REMOVED"},
SupplierLifecycle.DEGRADED: {"ACTIVE", "SUSPENDED", "REMOVED"},
SupplierLifecycle.SUSPENDED: {"BOUND", "ADMITTED", "REMOVED"},
SupplierLifecycle.REMOVED: set(),
}七、和前几篇收口
《1688 商品 API》：
offer/get/product是“供应商商品长什么样”《1688 订单 API》：采购单/退款是“和这家供应商发生交易后世界怎么变”
《1688 物流 API》：这家供应商的物流轨迹/运费模板怎么读
《1688 跨境分销》：这家供应商是不是严选/跨境/可密文
本文：供应商“能不能进我系统、进来了同步什么、异常怎么踢掉”
一句话：供应商入驻 = 资质准入；供应商同步 = 商品/库存/订单/物流/资质五流合一；供应商清退 = 下游 listing 自动降级 + 采购单切备供。
