ya-market-api 完整使用文档Yandex Market 雅得市场API Python包一、包基础概述1. 包定义与作用ya-market-api是封装Yandex.Market俄罗斯雅得电商平台官方REST API的Python第三方SDK专门面向跨境卖家、数据分析人员、爬虫开发者简化与Yandex商城后台交互无需手动封装HTTP请求、签名、分页、鉴权逻辑。核心对接Yandex Market商家后台所有业务接口商品管理、订单、库存、价格、报表、物流、店铺数据、广告投放、评价管理。2. 核心功能总览鉴权封装自动处理OAuth2.0商家token、商户ID校验、请求签名商品模块商品创建/更新/上下架、类目查询、属性批量修改、图片上传库存价格实时库存同步、批量调价、折扣设置、促销价管理订单模块订单拉取、发货、取消订单、修改配送信息、签收确认报表数据销量报表、流量统计、转化数据、竞品数据导出物流模块配送方案配置、包裹创建、物流轨迹查询广告模块商品推广预算调整、投放数据、关键词管理评价模块获取用户评价、回复差评、申诉恶意评价工具能力自动分页、批量请求、异常重试、响应JSON格式化、日志打印3. 支持Python版本最低Python 3.7推荐3.9 / 3.10 / 3.11依赖库requests、pydantic、python-dotenv、urllib3二、完整安装教程方式1pip标准安装pipinstallya-market-api方式2升级最新版pipinstall--upgradeya-market-api方式3源码安装官方githubgitclone https://github.com/ya-market/python-api.gitcdpython-api pipinstall.4. 依赖修复常见缺失pipinstallrequests pydantic python-dotenv三、基础语法、初始化与核心参数3.1 客户端初始化核心语法基础初始化模板fromya_market_apiimportYaMarketClient# 实例化客户端clientYaMarketClient(# 必填核心鉴权参数token商家OAuth访问令牌,business_id12345,# 商户主IDcampaign_id67890,# 店铺渠道ID多店铺必填# 可选配置参数timeout30,# 请求超时时间秒retry_count3,# 接口失败自动重试次数debugFalse,# True打印完整请求日志versionv2# API版本默认v2)3.2 全局核心参数说明参数名类型是否必填说明tokenstr是Yandex商家后台生成OAuth2.0 access_tokenbusiness_idint是商户主体ID商家后台个人中心获取campaign_idint分场景必填单个店铺渠道ID多店铺操作必须传timeoutint可选HTTP请求超时默认20sretry_countint可选5xx/网络错误自动重试默认2次debugbool可选开启打印请求头、响应体调试日志versionstr可选API版本v1/v2主流v2proxydict可选代理配置{http:xxx,https:xxx}3.3 接口通用请求语法所有业务模块统一调用格式# 模块.方法(接口业务参数)respclient.products.list(page1,limit50)# 返回结构固定Pydantic模型对象resp.result# 业务数据主体resp.meta# 分页信息total、page、pagesresp.errors# 错误信息列表resp.is_success()# 判断请求是否成功返回布尔值3.4 分页通用参数所有列表接口通用参数作用page页码默认1limit单页条数最大50filter过滤字典如筛选上架/下架商品sort排序字段price、created_at、views四、8个完整可运行实战应用案例案例1批量拉取店铺所有商品商品基础数据导出场景导出全店商品ID、标题、价格、库存用于本地表格对账fromya_market_apiimportYaMarketClientimportpandasaspd clientYaMarketClient(token你的token,business_id12345,campaign_id67890,debugFalse)all_products[]page1whileTrue:# 调用商品列表接口resclient.products.list(pagepage,limit50)ifnotres.is_success():print(接口错误,res.errors)breakitemsres.result.get(offers,[])ifnotitems:breakall_products.extend(items)# 判断是否还有下一页ifpageres.meta[pages]:breakpage1# 写入Exceldfpd.DataFrame(all_products)df.to_excel(yandex商品清单.xlsx,indexFalse)print(f导出商品总数{len(all_products)})案例2批量同步商品库存自动化库存更新场景本地进销存系统同步库存到Yandex店铺批量修改100件商品库存fromya_market_apiimportYaMarketClient clientYaMarketClient(tokenxxx,business_id12345,campaign_id67890)# 待更新库存列表stock_list[{offer_id:offer_001,stock:20},{offer_id:offer_002,stock:5},{offer_id:offer_003,stock:0}]# 批量库存更新接口respclient.stocks.update(offersstock_list)ifresp.is_success():print(库存同步成功)else:print(同步失败详情,resp.errors)案例3拉取当日新订单并自动标记发货场景定时脚本抓取当天未发货订单推送物流单号完成发货操作fromya_market_apiimportYaMarketClientfromdatetimeimportdate clientYaMarketClient(tokenxxx,business_id12345,campaign_id67890)# 筛选今日新建、未发货订单todaydate.today().isoformat()order_resclient.orders.list(filter{createdAtFrom:today,status:UNSHIPPED},limit50)ifnotorder_res.is_success():print(订单拉取失败)else:ordersorder_res.result[orders]fororderinorders:order_idorder[id]# 模拟物流单号track_numfTR{order_id}9999# 订单发货接口ship_respclient.orders.ship(order_idorder_id,shipments[{trackCode:track_num,deliveryServiceId:101}])ifship_resp.is_success():print(f订单{order_id}发货完成物流单号{track_num})案例4批量商品调价设置限时折扣场景大促活动批量修改售价添加7天限时折扣价fromya_market_apiimportYaMarketClient clientYaMarketClient(tokenxxx,business_id12345,campaign_id67890)price_data[{offer_id:offer_001,price:1290.00,# 原价oldPrice:1590.00,# 划线价discountStartDate:2026-06-20,discountEndDate:2026-06-27},{offer_id:offer_002,price:899.00,oldPrice:1099.00}]respclient.prices.update(offersprice_data)print(调价结果,resp.resultifresp.is_success()elseresp.errors)案例5获取店铺流量转化数据报表数据分析场景拉取近7天商品曝光、点击、订单转化数据做运营分析fromya_market_apiimportYaMarketClientfromdatetimeimportdatetime,timedelta clientYaMarketClient(tokenxxx,business_id12345)# 时间范围近7天enddatetime.now().date()startend-timedelta(days7)report_respclient.reports.stats(date_fromstart.isoformat(),date_toend.isoformat(),metrics[clicks,views,orders,revenue])ifreport_resp.is_success():datareport_resp.result[rows]forrowindata:print(商品ID{}曝光{}点击{}成交{}单营收{}.format(row[offerId],row[views],row[clicks],row[orders],row[revenue]))案例6自动读取用户评价并回复好评/申诉差评场景每日定时抓取新评价自动回复好评识别差评标记人工处理fromya_market_apiimportYaMarketClient clientYaMarketClient(tokenxxx,business_id12345,campaign_id67890)# 获取所有商品评价review_resclient.reviews.list(limit50)ifreview_res.is_success():reviewsreview_res.result[reviews]forrevinreviews:review_idrev[id]ratingrev[rating]# 好评自动回复ifrating4andnotrev.get(answer):client.reviews.answer(review_idreview_id,text感谢您的好评我们会持续优化商品与服务~)print(f评价{review_id}自动回复完成)elifrating2:print(f差评预警评价ID{review_id}内容{rev[text]})案例7广告投放预算自动化调整成本控制场景单日广告消耗超阈值自动下调每日投放预算fromya_market_apiimportYaMarketClient clientYaMarketClient(tokenxxx,business_id12345,campaign_id67890)# 获取广告账户当日消耗adv_statclient.ads.stats(date_from2026-06-20)total_spendadv_stat.result[totalSpent]max_limit5000# 单日预算上限5000卢布iftotal_spendmax_limit:# 下调广告日预算至3000client.ads.set_budget(budget3000)print(f当日消耗{total_spend}超过阈值预算下调完成)else:print(f广告消耗正常当前消耗{total_spend})案例8新建商品上架完整商品创建流程场景程序自动创建新品、上传图片、设置属性、直接上架销售fromya_market_apiimportYaMarketClient clientYaMarketClient(tokenxxx,business_id12345,campaign_id67890)new_offer{offerId:new_0001,productId:9876,# 类目产品IDname:无线蓝牙降噪耳机,price:2490.00,stock:30,visibility:VISIBLE,# VISIBLE上架 / HIDDEN下架pictures:[https://xxx/img1.jpg,https://xxx/img2.jpg],params:[{name:颜色,value:黑色},{name:续航,value:30小时}]}respclient.products.create(offernew_offer)ifresp.is_success():print(新品创建成功商品ID,resp.result[offerId])else:print(创建失败,resp.errors)五、常见错误代码、报错原因与解决方案1. 鉴权类错误高频401 Unauthorized原因token过期、token权限不足、business_id填写错误解决商家后台重新生成OAuth token核对商户ID开通对应接口权限商品/订单权限403 Forbidden原因token仅只读权限执行写操作改价/发货/新建商品渠道campaign_id不属于当前商户解决创建具备编辑权限的token核对店铺渠道ID2. 参数格式错误400 Bad Request / VALIDATION_ERROR原因价格传整数、库存负数、日期格式错误、offer_id重复、缺少必填字段解决价格必须字符串1290.00库存≥0日期严格YYYY-MM-DD校验入参字段完整性NOT_FOUND 404原因订单ID/商品offer_id不存在、API版本错误解决核对ID初始化指定versionv23. 限流与服务端错误429 Too Many Requests原因接口请求频率超出Yandex限制每秒≤10次解决添加time.sleep(0.2)批量合并请求开启包内置retry重试500 / 502 / 503 服务异常原因Yandex Market服务器临时故障解决依赖retry_count自动重试间隔10秒后重新请求4. 业务逻辑错误STOCK_NEGATIVE库存更新传入负数修正库存数值≥0ORDER_ALREADY_SHIPPED重复给同一订单执行发货先查询订单状态再操作PRICE_INVALID折扣价高于原价调整oldPrice大于售价5. 网络环境报错requests.exceptions.ConnectionError无法连接API服务器检查网络、添加代理proxy参数关闭防火墙ModuleNotFoundError: No module named ‘ya_market_api’未正确执行pip安装确认pip对应当前python环境六、使用重要注意事项1. 权限与token安全token属于敏感凭证禁止硬编码写在代码中建议使用.env文件python-dotenv读取区分只读token、读写token日常数据查询用只读token降低风险token有效期一般90天需定时重新生成替换2. 请求频率管控Yandex官方限流单商户每秒最多10次请求批量循环必须增加延时商品、库存批量接口单次最多50条超大数量拆分多批次提交3. 数据与金额规范所有价格、金额必须使用字符串传递禁止int/float浮点精度丢失会触发报错库存最小为0不支持负数下架商品库存建议统一填0图片链接必须外网可访问https地址本地路径无法上传4. 批量操作容错批量更新接口部分商品失败时接口会返回单条错误明细不要直接丢弃全部数据需单独处理失败商品重试5. 定时脚本部署建议每日报表、库存同步脚本避开Yandex高峰期莫斯科时间18:00-22:00生产环境开启debugFalse关闭日志避免泄露token增加异常捕获try-except防止单条数据崩溃整个循环6. 多店铺区分同一商户多个店铺每次接口调用必须传入对应campaign_id否则会操作默认店铺造成数据错乱7. 数据存储规范接口返回商品、订单ID为字符串导出Excel/数据库统一保存字符串格式避免数字ID丢失前缀08. 合规限制禁止高频爬虫式抓取竞品数据超出限流会直接封禁token数据仅用于自有店铺运营禁止倒卖平台商品数据。《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。