摘要：拉美跨境业务扩张阶段，美客多（MercadoLibre）多店铺、多站点批量上新是 ERP 系统的核心能力。传统后台手动发布、CSV 模板导入，存在效率低、变体处理麻烦、多站点适配困难、错误难以批量排查等痛点。本文从工程落地角度，完整讲解基于 API 实现商品采集‑数据预处理‑草稿存储‑批量刊登‑结果回写整套闭环方案，梳理架构设计、关键接口、伪代码、业务坑点。
一、业务背景
做美客多跨境 ERP、铺货工具，经常遇到这些现实业务痛点：
- 墨西哥 MLM、巴西 MLB、阿根廷 MLA 等站点语言、货币、类目体系完全独立，一套素材不能直接多站点复用；
- 变体 SKU 繁多，人工整理规格、价格、图片极易出现 SKU 丢失、规格错乱；
- 直接采集原始数据无法直接提交刊登，需要图片转存、语种翻译、币种换算、类目映射、补齐平台必填属性；
- CSV 批量上传报错不直观，大批量商品发布失败，很难定位具体字段问题；
- 需要完整闭环：采集→处理→草稿人工复核→发布→任务状态回写，方便运营排查失败原因。
借助美客多商品详情采集接口结合刊登接口，可以搭建自动化批量上货链路，减少大量重复人工操作。
二、整体系统架构与完整业务链路
- 商品数据源录入
批量导入 / 单个录入源商品item_id、目标发布站点、目标店铺 ID；支持从货源平台、美客多其他店铺抓取素材。 - 调用采集接口获取原始数据
调用mercadolibre.item_get，拉取标题、图片集合、描述、类目路径、品牌、属性参数、variants 变体数组、价格、库存参考、卖家信息。 - 数据预处理（整套链路最核心环节）
- 图片处理：源站图片存在防盗链，下载转存自有对象存储，替换图片 URL；过滤无效图片；
- 文本处理：标题、描述、属性做翻译适配站点语种（西语 / 葡语），过滤违禁词；
- 币种换算：把源价格换算成目标站点本地货币；
- 变体解析：完整解析
variants数组，拆分每一个子 SKU 规格、价格、图片； - 类目映射：源类目不能直接复用，做类目匹配，补齐平台强制必填属性；
- 库存处理：接口返回
available_quantity仅为参考值，业务层设置实际刊登库存。
草稿库持久化
处理完成的数据存入草稿池，运营可以二次编辑修改标题、价格、类目、属性，校验无误后再发起发布，避免直接提交刊登造成大量失败。
异步批量刊登任务
通过店铺 OAuth 授权 token 调用刊登接口，不使用同步阻塞发布；提交之后获取publish_task_id任务编号。大批量商品使用 Redis 任务队列限流，控制请求 QPS。
轮询刊登任务状态，结果回写
循环查询 task_id 获取发布结果，将成功、失败、错误详情全部回写到业务数据库；区分字段缺失、类目错误、图片异常、平台风控等不同错误类型。
异常告警
刊登失败、接口限流、字段缺失输出日志，推送消息给到开发或者运营人员。
三、核心接口能力说明
- 商品采集接口：
mercadolibre.item_get
入参：item_id、site站点编码，鉴权 key、secret；
输出：标题、图集、HTML 描述、类目、品牌、variants变体数组、属性、价格、库存参考值。 - 商品刊登接口
依赖店铺 OAuth2.0 授权 access_token；接收经过预处理后的刊登结构体；支持单品发布、异步批量发布；返回任务 ID 用于轮询结果。
