美客多批量上货解决方案：美客多 API 实现商品采集‑预处理‑刊登全链路

摘要：拉美跨境业务扩张阶段，美客多（MercadoLibre）多店铺、多站点批量上新是 ERP 系统的核心能力。传统后台手动发布、CSV 模板导入，存在效率低、变体处理麻烦、多站点适配困难、错误难以批量排查等痛点。本文从工程落地角度，完整讲解基于 API 实现商品采集‑数据预处理‑草稿存储‑批量刊登‑结果回写整套闭环方案，梳理架构设计、关键接口、伪代码、业务坑点。

一、业务背景

做美客多跨境 ERP、铺货工具，经常遇到这些现实业务痛点：

1. 墨西哥 MLM、巴西 MLB、阿根廷 MLA 等站点语言、货币、类目体系完全独立，一套素材不能直接多站点复用；
2. 变体 SKU 繁多，人工整理规格、价格、图片极易出现 SKU 丢失、规格错乱；
3. 直接采集原始数据无法直接提交刊登，需要图片转存、语种翻译、币种换算、类目映射、补齐平台必填属性；
4. CSV 批量上传报错不直观，大批量商品发布失败，很难定位具体字段问题；
5. 需要完整闭环：采集→处理→草稿人工复核→发布→任务状态回写，方便运营排查失败原因。

借助美客多商品详情采集接口结合刊登接口，可以搭建自动化批量上货链路，减少大量重复人工操作。

二、整体系统架构与完整业务链路

商品item_id录入 → API采集商品原始素材 → 数据清洗预处理 → 草稿库存储（运营可编辑）→ 异步批量刊登任务 → 查询刊登任务结果 → 结果落库+异常告警

1. 商品数据源录入 批量导入 / 单个录入源商品item_id、目标发布站点、目标店铺 ID；支持从货源平台、美客多其他店铺抓取素材。
2. 调用采集接口获取原始数据 调用mercadolibre.item_get，拉取标题、图片集合、描述、类目路径、品牌、属性参数、variants 变体数组、价格、库存参考、卖家信息。
3. 数据预处理（整套链路最核心环节）

• 图片处理：源站图片存在防盗链，下载转存自有对象存储，替换图片 URL；过滤无效图片；
• 文本处理：标题、描述、属性做翻译适配站点语种（西语 / 葡语），过滤违禁词；
• 币种换算：把源价格换算成目标站点本地货币；
• 变体解析：完整解析variants数组，拆分每一个子 SKU 规格、价格、图片；
• 类目映射：源类目不能直接复用，做类目匹配，补齐平台强制必填属性；
• 库存处理：接口返回available_quantity仅为参考值，业务层设置实际刊登库存。

1. 草稿库持久化 处理完成的数据存入草稿池，运营可以二次编辑修改标题、价格、类目、属性，校验无误后再发起发布，避免直接提交刊登造成大量失败。
2. 异步批量刊登任务 通过店铺 OAuth 授权 token 调用刊登接口，不使用同步阻塞发布；提交之后获取publish_task_id任务编号。大批量商品使用 Redis 任务队列限流，控制请求 QPS。
3. 轮询刊登任务状态，结果回写 循环查询 task_id 获取发布结果，将成功、失败、错误详情全部回写到业务数据库；区分字段缺失、类目错误、图片异常、平台风控等不同错误类型。
4. 异常告警 刊登失败、接口限流、字段缺失输出日志，推送消息给到开发或者运营人员。

重要提示：采集返回原始数据不能直接提交刊登，美客多平台对类目、属性、图片、语种校验严格，原样提交大概率发布失败。

三、核心接口能力说明

1. 商品采集接口：mercadolibre.item_get 入参：item_id、site站点编码； 输出：标题、图集、HTML 描述、类目、品牌、variants变体数组、属性、价格、库存参考值。
2. 商品刊登接口 依赖店铺 OAuth2.0 授权 access_token；接收经过预处理后的刊登结构体；支持单品发布、异步批量发布；返回任务 ID 用于轮询结果。

开发重点：变体数组variants，外层展示价格不能用于刊登，每一个子变体拥有独立规格、价格、图片，必须逐个解析。

四、Python 伪代码示例：采集与预处理模块

import requests
import time

API_KEY = "your_key"
API_SECRET = "your_secret"
ITEM_GET_URL = "https://api-gw.onebound.cn/mercadolibre.item_get"

def fetch_source_item(item_id, site="MLM"):
    params = {
        "key": API_KEY,
        "secret": API_SECRET,
        "item_id": item_id,
        "site": site
    }
    resp = requests.get(ITEM_GET_URL, params=params, timeout=15)
    return resp.json()

def build_publish_draft(item_id, site="MLM"):
    """采集原始数据，预处理生成刊登草稿"""
    res = fetch_source_item(item_id, site)
    if res.get("code") != 200:
        print(f"采集失败 item_id={item_id}, msg={res.get('msg')}")
        return None
    raw_data = res["data"]

    draft = {
        "source_item_id": item_id,
        "target_site": site,
        "title": raw_data.get("title",""),
        "brand": raw_data.get("brand",""),
        "images":[],
        "description": raw_data.get("description",""),
        "variants":[]
    }
    # 图片转存处理，业务中此处实现下载图片上传OSS
    for img in raw_data.get("images",[]):
        # new_img_url = download_and_upload_oss(img)
        draft["images"].append(img)

    # 解析变体SKU
    for var in raw_data.get("variants",[]):
        sku_info = {
            "spec_text": var.get("spec_text",""),
            "price": var.get("price",""),
            "pic_url": var.get("pic_url",""),
            "stock": 100 # 业务自定义库存，不要直接使用available_quantity
        }
        draft["variants"].append(sku_info)

    # db.insert_draft(draft) #存入草稿表，运营可编辑
    return draft

if __name__ == "__main__":
    build_publish_draft("MLM1357924680", site="MLM")
    time.sleep(1.2)

五、工程实战高频踩坑总结

1. available_quantity 仅为参考值，禁止直接拿来刊登 公开接口返回库存是区间映射，不是真实可售库存；刊登库存由业务层自主配置，直接使用接口返回库存会出现超卖。
2. 变体 SKU 处理是主要故障点 外层 price 只是页面展示价格；每个子变体独立价格、图片、规格，刊登必须遍历 variants 数组；忽略变体处理会出现上架 SKU 丢失、规格错乱。
3. 图片防盗链问题 源站图片 URL 带防盗链，直接提交刊登会审核失败；业务必须下载图片转存自有对象存储，使用新 URL 提交发布。
4. 类目映射极易刊登失败 源商品类目 ID 不能直接复用；需要做类目匹配映射，补齐平台类目下全部必填属性，否则直接返回发布报错。
5. 多站点语种、货币差异 墨西哥西语、巴西葡萄牙语，不同站点货币完全不同；采集素材如果是中文，需要翻译处理；价格需要换算成本地币种。
6. 接口限流 429 风险 采集接口、刊登接口都有严格 QPS 限制；大批量商品必须使用 Redis 异步任务队列，设置请求间隔、指数退避重试，禁止循环高并发调用。
7. 刊登采用异步任务模式，不要同步等待 大批量发布提交后拿到 task_id，轮询查询任务结果；把成功失败、错误详情落库，方便定位问题。
8. 空值兼容处理 部分商品品牌、属性为空，代码必须安全取值，防止采集、定时任务空指针崩溃。
9. 平台合规风险 直接搬运他人商品素材会带来侵权、盗图风险；技术层面仅做数据获取，业务上需要做好素材合规校验。

六、业务落地应用场景

1. 店铺商品搬家：抓取美客多 A 店铺商品素材，经过预处理刊登到同平台其他店铺；
2. 跨平台铺货系统：美客多商品素材转换，刊登到 Temu、Ozon、Coupang 等跨境平台；
3. 批量上新工具：对接货源数据，批量生成草稿，运营人工复核后一键批量发布；
4. 素材归档系统：采集商品标题、图片、参数，用于竞品调研、类目数据分析。

七、小结

美客多 API 批量上货，难点不在于简单调用接口拿数据，而在于完整的预处理链路：变体解析、图片转存、类目映射、语种货币归一化、异步任务管理、草稿人工复核机制。 原始接口返回只能作为素材来源，不能直接提交刊登。生产环境做好队列限流、异常日志、刊登结果回写，就可以稳定支撑拉美跨境 ERP 批量上新业务。