商家后台 / 开放接口说明

开放接口说明

用密钥调用接口，你可以自己开发店铺的运营工具：定时拉取新询价、批量改商品草稿、查看每天的统计。

调用限制

接口只能改草稿和发布。发布要求身份核验已通过，发布后马上公开；平台可以下架违规内容，被平台下架的店铺只能读，不能写。
不能通过接口给买家发消息。接口能看询价、改状态和备注；回复买家要你本人在即时通信里进行。
看不到买家的电话和邮箱。询价里只有买家的显示名和即时通信链接；举报只给条数，不给原文和举报人。
没有回调（webhook）。想知道有没有新询价，用 updated_since 定时拉取，见下面的示例。

怎么开始

登录店主本人的主账号（程序令牌和子账号不能建密钥），打开商家后台的“开放接口”标签，点“新建密钥”。店铺必须是商城店铺。
起个名字（最多 60 字），至少勾一项权限，选有效期（30 / 90 / 180 / 365 天，默认 90 天，到期自动失效）。每家店最多同时有 5 把有效密钥。
完整密钥以 zsk_ 开头，只在建好时显示一次，请立即复制保存。平台只存摘要，丢了只能撤销后重新建。
每次请求都带上请求头：Authorization: Bearer zsk_你的密钥。只认这一种写法，没有别的请求头。不要把密钥写进网页或手机应用的代码里，也不要发给别人；怀疑泄露就马上撤销。

基础地址：/api/user-sites/merchant/open/v1，前面加上平台域名就是完整地址，比如 https://zhugejunshi.com/api/user-sites/merchant/open/v1/shop。请求和返回都是 JSON（上传图片除外），请求体不超过 1 MB。返回的时间是 UTC 的 ISO 8601 格式，例如 2026-11-03T02:00:00+00:00；统计里的 day 是北京时间的日期。

权限

一把密钥只带它需要的权限，别的接口会返回 403。

权限	名称	能做什么
`shop:read`	查看店铺	店铺状态、发布状态、草稿、商品（草稿和线上对照）、平台处理记录。
`products:write`	修改商品	替换某个商品区块的商品；上传图片。
`shop:write`	修改店铺	整份替换草稿、改店名；暂时下线、重新上线。
`review:write`	发布	发布草稿；以前提交、还在审核中的店铺可以撤回。
`inquiries:read`	查看询价	看买家询价，只有买家显示名和即时通信链接。
`inquiries:write`	处理询价	改询价状态和备注。不能给买家发消息。
`stats:read`	查看统计	每天的浏览数和询价数。

接口

路径都接在基础地址后面。每次调用依次检查：密钥（401）、限流（429）、权限（403）、被平台下架时的写操作（403），最后才是你提交的内容（422）和实际处理，所以没带密钥的请求只会得到 401。请求体里不认识的字段会被拒绝（422）。

方法	路径	要的权限	请求	返回
GET	`/shop`	`shop:read`	无	site（店铺摘要，不含草稿）、steps（开店各步骤的进度）、domain（独立域名申请）、counts（线上商品数、草稿商品数、未处理举报数）
GET	`/draft`	`shop:read`	无	整个店铺，含 draft（草稿全文：页面、区块、联系方式）和 revision
PUT	`/draft`	`shop:write`	JSON：revision、draft（整份草稿）；可选 name（店名）	保存后的整个店铺，同 GET /draft，revision 加一
GET	`/products`	`shop:read`	无	revision、review_status、live（线上商品）、draft（草稿商品）、blocks（草稿里的商品区块）、media（图片 id 对应的网址）、problem（现在还不能提交审核的原因，空字符串表示没问题）
PUT	`/products/{page_key}/{block_id}`	`products:write`	JSON：revision、items（这个区块的全部商品，整块替换）	保存后的商品，同 GET /products
POST	`/assets`	`products:write`	multipart/form-data，图片放在 file 字段（JPEG、PNG 或 WEBP，不超过 10 MB）	id、url、width、height、bytes；商品的 image 填这里的 id
POST	`/review/submit`	`review:write`	JSON：revision、overseas_consent（必须是 true，表示同意页面放在新加坡服务器）	整个店铺，直接上线：review_status 变成 approved，public_status 变成 live
POST	`/review/withdraw`	`review:write`	无，不用请求体，也不用 revision	整个店铺，review_status 变回 draft（只用于以前提交、还在审核中的店铺）
POST	`/visibility/offline`	`shop:write`	无，不用请求体，也不用 revision	整个店铺，public_status 变成 offline，买家暂时看不到
POST	`/visibility/online`	`shop:write`	无，不用请求体，也不用 revision	整个店铺，public_status 变回 live；只有暂时下线的店铺可以
GET	`/records`	`shop:read`	查询参数：updated_since（可选）、limit（1 到 100，默认 20）、offset	items（平台处理记录）、total、reports（举报条数：open 未处理、resolved 已处理）
GET	`/inquiries`	`inquiries:read`	查询参数：status（可选）、updated_since（可选）、limit（1 到 100，默认 20）、offset	items（询价）、total、counts（五种状态各有几条）
POST	`/inquiries/{id}`	`inquiries:write`	JSON：revision（这条询价自己的）；可选 status、note	更新后的这条询价
GET	`/stats`	`stats:read`	查询参数：days（7 到 90，默认 30）	days（每天的 day、views、inquiries）、total_views、total_inquiries

PUT /draft 整份替换草稿，不是只改几个字段：先 GET /draft，改好再整份发回去。审核中的店铺不能改，要先撤回；已发布的店铺一改草稿，状态就变回 draft，线上继续显示上一版，重新发布后更新。
PUT /products/{page_key}/{block_id} 的 page_key、block_id 取自 GET /products 返回的 blocks。items 里每件商品只能有 name、price、image、text 四个字段；image 填 POST /assets 返回的 id（不是网址），不放图片就填 null。
POST /assets：同一张图片重复上传，返回已有的那张；每家店最多 100 张图片。
GET /records 和 GET /inquiries 带 updated_since 时，只返回这个时间之后（含）有变化的，按变化时间从旧到新排，用来增量拉取；不带时按时间从新到旧排。counts 不受 status 和 updated_since 影响，始终是全部询价的各状态条数。
POST /inquiries/{id} 里没写的字段保持不变，note 写空字符串就清空备注（最多 500 字）。

返回的数据

店铺: id、slug、url、mode（shop 是商城店铺）、name、operator_name、review_status（draft 草稿 / pending 审核中 / approved 已通过 / rejected 被退回）、public_status（unpublished 还没公开 / live 公开中 / offline 暂时下线 / suspended 被平台下架）、review_note、suspend_note、has_unpublished_changes（草稿和线上公开的版本有没有不同）、listed（是否已上架合作市场）、revision、submitted_at、published_at、created_at、updated_at。读草稿的接口多一个 draft。
商品行: page_key、block_id、index（在区块里的位置）、name、price、image（图片 id，或 null）、text、change（same 未改动 / changed 已改未提交 / new 新增 / removed 草稿里已删）。live 里只会出现 same 和 removed，draft 里只会出现 same、changed 和 new。
商品区块: page_key、block_id、title、items（区块里的商品条数）。
询价: id、product_name、quantity_text、message、status（new 新询价 / contacted 已联系 / negotiating 洽谈中 / agreed 已谈成 / closed 已关闭）、merchant_note、revision、buyer.name（买家显示名）、conversation_url（即时通信里这个私聊的链接）、replied（你有没有在私聊里回过）、last_reply_at、created_at、updated_at。没有的值是 null。
平台处理记录: id、action（submit、withdraw、offline、online 是你自己做的；approve、reject、suspend、restore 是平台做的）、by（owner 你自己 / platform 平台）、note（平台写的说明；你自己的操作没有，为 null）、created_at。

限流

每把密钥每分钟最多 60 次调用，其中写操作（PUT、POST）最多 20 次，按最近 60 秒滚动计算。
每家店每天最多 10,000 次调用（所有密钥合计），按北京时间的自然日算，每天 00:00（北京时间）重新开始。因为没有权限、店铺被下架或调用太频繁而被拒的（403、429）不算进这 10,000 次。
超过限额返回 429，响应头 Retry-After 是需要等待的秒数。请等够这么久再重试，不要立刻重发。同一时刻涌进来的一小批请求，可能略微超出限额。
带着有效密钥的调用都会记一行（方法、路由、状态码），被拒绝的也记，除 429 以外都计入每分钟的限额；连续的 429 每分钟只记一行；密钥无效的 401 不记。只记这三项，不记请求和返回的内容。你可以在商家后台的“开放接口”标签里看最近的调用记录。调用记录至少保存 90 天，超过 90 天的可能被清理。
每次返回都带 Cache-Control: private, no-store，不要缓存。

错误码

出错时返回 {"detail": "中文说明"}，状态码如下。

401	“开放接口密钥无效。”没带密钥、格式不对、密钥不存在、已过期、已撤销，或店主账号、店铺不可用，一律是这一句，不会告诉你是哪一种；请到商家后台检查密钥。
403	“这把密钥没有‘某某’权限。”，缺哪项权限就写哪项；或者“店铺已被平台下架，开放接口现在只能读取，不能修改。”（下架后读接口照常，写接口都不行）。
404	“草稿里没有这个商品区块。”或“没有这条询价。”
409	“数据已被改动，请刷新。”revision 对不上：这份内容在别处被改过，什么也没改。重新读取最新内容再改。
422	请求体缺字段、多了不认识的字段、格式不对，或查询参数超出范围（比如 limit 超过 100、days 不在 7 到 90 之间、status 不是五种之一），返回“内容不完整或格式不正确，请检查必填项、长度及提交确认。”其余的 422 都有具体的中文说明，比如“审核中不能修改，请先撤回。”“updated_since 的时间格式不正确……”“图片不能超过 10 MB。”“提交的内容太大。”
429	“调用太频繁，请 N 秒后再试。”响应头 Retry-After 也是这个秒数。
503	“服务暂时不可用，请稍后再试。”稍等一会儿再重试。

revision：防止互相覆盖

只有四个接口要带 revision：PUT /draft、PUT /products/…、POST /review/submit 用店铺的 revision（从 GET /shop、GET /draft 或 GET /products 读到）；POST /inquiries/{id} 用这条询价自己的 revision。撤回审核、暂时下线、重新上线不用 revision，也不用请求体。

每改一次，对应的 revision 加一。写的时候带上你读到的那个数；如果这期间网页编辑器或别的程序已经改过，revision 对不上，接口返回 409，什么也不会改。这时重新读取，合并后再写。店铺的 revision 在每次改动草稿、提交、撤回、下线、上线后都会变，连续写之前请用上一次返回里的新值。

示例

下面的 zsk_你的密钥 是占位符，换成你自己的完整密钥；$BASE 是第一个示例里设的地址变量。

看店铺状态

BASE=https://zhugejunshi.com/api/user-sites/merchant/open/v1

curl "$BASE/shop" \
  -H "Authorization: Bearer zsk_你的密钥"

拉取某个时间之后有变化的新询价（+ 在网址里要写成 %2B；不写时区按 UTC 算）

curl "$BASE/inquiries?status=new&updated_since=2026-11-01T00:00:00%2B00:00" \
  -H "Authorization: Bearer zsk_你的密钥"

把一条询价标成“已联系”并写备注（revision 用上一步读到的这条询价自己的）

curl -X POST "$BASE/inquiries/询价编号" \
  -H "Authorization: Bearer zsk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"revision": 1, "status": "contacted", "note": "已报价，等对方确认"}'

上传一张商品图片，返回里的 id 填进商品的 image

curl -X POST "$BASE/assets" \
  -H "Authorization: Bearer zsk_你的密钥" \
  -F "file=@商品图.jpg"

替换一个商品区块里的商品（页面和区块的编号取自 GET /products 的 blocks，revision 是店铺的）

curl -X PUT "$BASE/products/页面编号/区块编号" \
  -H "Authorization: Bearer zsk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"revision": 7, "items": [{"name": "示例商品", "price": "39.9 元", "image": "上一步返回的图片 id", "text": "一句话说明"}]}'

改完草稿后发布（revision 是上一步返回的店铺新值）

curl -X POST "$BASE/review/submit" \
  -H "Authorization: Bearer zsk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"revision": 8, "overseas_consent": true}'

暂时下线店铺（不用请求体，也不用 revision）

curl -X POST "$BASE/visibility/offline" \
  -H "Authorization: Bearer zsk_你的密钥"