{"openapi":"3.1.0","info":{"title":"商家开放接口","version":"v1","description":"商家用密钥调用接口，自己开发店铺运营工具：看询价、改商品草稿、发布、看统计。仅限商城店铺（mode = shop）。\n密钥在商家后台 /my-shop 的“开放接口”标签里建和撤销（用店主本人主账号登录；程序令牌和子账号不能建）。完整密钥以 zsk_ 开头，只在建好时显示一次；每家店最多同时有 5 把有效密钥，有效期 30 / 90 / 180 / 365 天（默认 90 天）。\n每次请求带请求头 Authorization: Bearer zsk_你的密钥，只认这一种写法。\n限流：每把密钥每分钟最多 60 次，其中写操作（PUT、POST）最多 20 次，按最近 60 秒滚动计算；每家店每天最多 10,000 次（所有密钥合计），按北京时间自然日、00:00 重新开始，因权限不足、被下架或限流被拒的（403、429）不计入。超限返回 429，响应头 Retry-After 为需要等待的秒数。\n检查顺序：密钥（401）、限流（429）、权限（403）、被下架时的写操作（403）、请求内容（422）、实际处理。请求体不超过 1 MB，请求体里不认识的字段会被拒绝（422）。没有回调（webhook），新询价请用 updated_since 定时拉取。\n不能通过接口给买家发消息，也看不到买家的电话和邮箱。所有返回带 Cache-Control: private, no-store，不要缓存。返回的时间是 UTC 的 ISO 8601；统计里的 day 是北京时间日期。\nrevision 用来防止互相覆盖：PUT /draft、PUT /products/…、POST /review/submit 用店铺的 revision；POST /inquiries/{inquiry_id} 用这条询价自己的 revision。对不上返回 409，什么也不会改。"},"servers":[{"url":"https://www.zhugejunshi.com/api/user-sites/merchant/open/v1","description":"正式环境"}],"tags":[{"name":"店铺","description":"查看店铺状态与草稿，整份替换草稿，暂时下线或重新上线。"},{"name":"商品","description":"查看线上与草稿商品，按区块替换商品，上传商品图片。"},{"name":"发布","description":"发布草稿、撤回以前提交的审核，并查看平台处理记录。"},{"name":"客户咨询","description":"拉取买家询价，修改询价状态和备注。"},{"name":"统计","description":"每天的浏览数和询价数。"}],"security":[{"bearerAuth":[]}],"paths":{"/shop":{"get":{"operationId":"getShop","tags":["店铺"],"summary":"查看店铺状态与开店进度","x-scope":"shop:read","description":"返回店铺摘要（不含草稿）、开店各步骤进度、独立域名申请和各类条数。","responses":{"200":{"description":"店铺总览。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopOverview"},"example":{"site":{"id":"00000000-0000-0000-0000-000000000001","slug":"demo-shop","url":"https://demo-shop.example.com/","mode":"shop","name":"示例商店","operator_name":"示例经营者","review_status":"approved","public_status":"live","review_note":null,"suspend_note":null,"has_unpublished_changes":false,"listed":true,"revision":7,"submitted_at":"2026-11-03T02:00:00+00:00","published_at":"2026-11-03T02:00:00+00:00","created_at":"2026-11-01T02:00:00+00:00","updated_at":"2026-11-03T02:00:00+00:00","node_sync":{}},"steps":[{"key":"goods","state":"done","note":""}],"domain":null,"counts":{"products_live":3,"products_draft":4,"reports_open":0}}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/draft":{"get":{"operationId":"getDraft","tags":["店铺"],"summary":"读取整个店铺含草稿","x-scope":"shop:read","description":"返回整个店铺，含草稿全文（页面、区块、联系方式）和 revision。要改草稿，先读这里，改好再整份发回 PUT /draft。","responses":{"200":{"description":"含草稿的店铺。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shop"},"example":{"id":"00000000-0000-0000-0000-000000000001","slug":"demo-shop","url":"https://demo-shop.example.com/","mode":"shop","name":"示例商店","operator_name":"示例经营者","review_status":"approved","public_status":"live","review_note":null,"suspend_note":null,"has_unpublished_changes":false,"listed":true,"revision":7,"submitted_at":"2026-11-03T02:00:00+00:00","published_at":"2026-11-03T02:00:00+00:00","created_at":"2026-11-01T02:00:00+00:00","updated_at":"2026-11-03T02:00:00+00:00","draft":{"pages":[]},"node_sync":{}}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}},"put":{"operationId":"putDraft","tags":["店铺"],"summary":"整份替换店铺草稿","x-scope":"shop:write","description":"整份替换草稿，不是只改几个字段；可同时改店名。保存后 revision 加一。审核中的店铺不能改，要先撤回；已发布的店铺一改草稿，状态变回 draft，线上继续显示上一版，重新发布后更新。写操作；店铺被平台下架后不可用（403）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftBody"},"example":{"revision":7,"draft":{"pages":[]},"name":"示例商店"}}}},"responses":{"200":{"description":"保存后的整个店铺，同 GET /draft。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shop"},"example":{"id":"00000000-0000-0000-0000-000000000001","slug":"demo-shop","url":"https://demo-shop.example.com/","mode":"shop","name":"示例商店","operator_name":"示例经营者","review_status":"approved","public_status":"live","review_note":null,"suspend_note":null,"has_unpublished_changes":false,"listed":true,"revision":8,"submitted_at":"2026-11-03T02:00:00+00:00","published_at":"2026-11-03T02:00:00+00:00","created_at":"2026-11-01T02:00:00+00:00","updated_at":"2026-11-03T02:00:00+00:00","draft":{"pages":[]},"node_sync":{}}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Stale"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/visibility/offline":{"post":{"operationId":"takeOffline","tags":["店铺"],"summary":"暂时下线店铺","x-scope":"shop:write","description":"让店铺暂时下线，买家看不到。不用请求体，也不用 revision。写操作；店铺被平台下架后不可用（403）。","responses":{"200":{"description":"整个店铺，public_status 变成 offline。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shop"},"example":{"id":"00000000-0000-0000-0000-000000000001","slug":"demo-shop","url":"https://demo-shop.example.com/","mode":"shop","name":"示例商店","operator_name":"示例经营者","review_status":"approved","public_status":"offline","review_note":null,"suspend_note":null,"has_unpublished_changes":false,"listed":true,"revision":7,"submitted_at":"2026-11-03T02:00:00+00:00","published_at":"2026-11-03T02:00:00+00:00","created_at":"2026-11-01T02:00:00+00:00","updated_at":"2026-11-03T02:00:00+00:00","draft":{"pages":[]},"node_sync":{}}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/visibility/online":{"post":{"operationId":"bringOnline","tags":["店铺"],"summary":"重新上线店铺","x-scope":"shop:write","description":"让暂时下线的店铺重新公开，public_status 变回 live；只有暂时下线的店铺可以。不用请求体，也不用 revision。写操作；店铺被平台下架后不可用（403）。","responses":{"200":{"description":"整个店铺。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shop"},"example":{"id":"00000000-0000-0000-0000-000000000001","slug":"demo-shop","url":"https://demo-shop.example.com/","mode":"shop","name":"示例商店","operator_name":"示例经营者","review_status":"approved","public_status":"live","review_note":null,"suspend_note":null,"has_unpublished_changes":false,"listed":true,"revision":7,"submitted_at":"2026-11-03T02:00:00+00:00","published_at":"2026-11-03T02:00:00+00:00","created_at":"2026-11-01T02:00:00+00:00","updated_at":"2026-11-03T02:00:00+00:00","draft":{"pages":[]},"node_sync":{}}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/products":{"get":{"operationId":"getProducts","tags":["商品"],"summary":"查看线上与草稿商品","x-scope":"shop:read","description":"返回线上商品和草稿商品的对照。商品没有编号，用商品名把草稿和线上对应起来；live 里只会出现 same 和 removed，draft 里只会出现 same、changed 和 new。blocks 里的 page_key、block_id 用于 PUT /products/{page_key}/{block_id}。","responses":{"200":{"description":"商品对照。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsView"},"example":{"revision":7,"review_status":"approved","live":[{"page_key":"home","block_id":"products-1","index":0,"name":"示例商品","price":"39.9 元","image":null,"text":"一句话说明","change":"same"}],"draft":[{"page_key":"home","block_id":"products-1","index":0,"name":"示例商品","price":"39.9 元","image":null,"text":"一句话说明","change":"same"}],"blocks":[{"page_key":"home","block_id":"products-1","title":"热销商品","items":1}],"media":{},"problem":""}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/products/{page_key}/{block_id}":{"put":{"operationId":"replaceProducts","tags":["商品"],"summary":"整块替换一个商品区块","x-scope":"products:write","description":"替换草稿里某个商品区块的全部商品（整块替换）。page_key、block_id 取自 GET /products 返回的 blocks。items 里每件商品只能有 name、price、image、text 四个字段；image 填 POST /assets 返回的 id（不是网址），不放图片填 null。写操作；店铺被平台下架后不可用（403）。","parameters":[{"name":"page_key","in":"path","required":true,"description":"页面编号，取自 GET /products 的 blocks。","schema":{"type":"string","maxLength":30},"example":"home"},{"name":"block_id","in":"path","required":true,"description":"商品区块编号，取自 GET /products 的 blocks。","schema":{"type":"string","maxLength":40},"example":"products-1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsBody"},"example":{"revision":7,"items":[{"name":"示例商品","price":"39.9 元","image":null,"text":"一句话说明"}]}}}},"responses":{"200":{"description":"保存后的商品，同 GET /products。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsView"},"example":{"revision":8,"review_status":"draft","live":[],"draft":[{"page_key":"home","block_id":"products-1","index":0,"name":"示例商品","price":"39.9 元","image":null,"text":"一句话说明","change":"new"}],"blocks":[{"page_key":"home","block_id":"products-1","title":"热销商品","items":1}],"media":{},"problem":""}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Stale"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/assets":{"post":{"operationId":"uploadAsset","tags":["商品"],"summary":"上传商品图片","x-scope":"products:write","description":"用 multipart/form-data 上传，图片放在 file 字段（JPEG、PNG 或 WEBP，不超过 10 MB，只收一个文件）。同一张图片重复上传返回已有的那张；每家店最多 100 张图片。返回的 id 填进商品的 image。写操作；店铺被平台下架后不可用（403）。","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"图片文件。"}}}}}},"responses":{"200":{"description":"图片信息。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"},"example":{"id":"00000000-0000-0000-0000-0000000000b1","url":"https://example.com/signed-image-url","width":800,"height":600,"bytes":40960}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/review/submit":{"post":{"operationId":"submitReview","tags":["发布"],"summary":"发布草稿","x-scope":"review:write","description":"发布草稿。身份核验已通过的店主发布后马上公开（review_status 变成 approved，public_status 变成 live），平台可事后下架。overseas_consent 必须是 true，表示同意页面放在新加坡服务器。身份未核验返回 409；审核中、内容没有改动、草稿不合格等返回 422 并带具体说明。写操作；店铺被平台下架后不可用（403）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitBody"},"example":{"revision":8,"overseas_consent":true}}}},"responses":{"200":{"description":"整个店铺。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shop"},"example":{"id":"00000000-0000-0000-0000-000000000001","slug":"demo-shop","url":"https://demo-shop.example.com/","mode":"shop","name":"示例商店","operator_name":"示例经营者","review_status":"approved","public_status":"live","review_note":null,"suspend_note":null,"has_unpublished_changes":false,"listed":true,"revision":9,"submitted_at":"2026-11-03T02:00:00+00:00","published_at":"2026-11-03T02:00:00+00:00","created_at":"2026-11-01T02:00:00+00:00","updated_at":"2026-11-03T02:00:00+00:00","draft":{"pages":[]},"node_sync":{}}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Stale"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/review/withdraw":{"post":{"operationId":"withdrawReview","tags":["发布"],"summary":"撤回审核中的提交","x-scope":"review:write","description":"只用于以前提交、还在审核中的店铺，撤回后 review_status 变回 draft；不在审核中返回 422。不用请求体，也不用 revision。写操作；店铺被平台下架后不可用（403）。","responses":{"200":{"description":"整个店铺。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shop"},"example":{"id":"00000000-0000-0000-0000-000000000001","slug":"demo-shop","url":"https://demo-shop.example.com/","mode":"shop","name":"示例商店","operator_name":"示例经营者","review_status":"draft","public_status":"live","review_note":null,"suspend_note":null,"has_unpublished_changes":false,"listed":true,"revision":7,"submitted_at":"2026-11-03T02:00:00+00:00","published_at":"2026-11-03T02:00:00+00:00","created_at":"2026-11-01T02:00:00+00:00","updated_at":"2026-11-03T02:00:00+00:00","draft":{"pages":[]},"node_sync":{}}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/records":{"get":{"operationId":"listRecords","tags":["发布"],"summary":"查看平台处理记录","x-scope":"shop:read","description":"店铺的提交、撤回、下线、上线、通过、退回、下架、恢复等记录，以及举报条数（只给条数，不给原文和举报人）。不带 updated_since 时按时间从新到旧；带时只返回这个时间之后（含）的，从旧到新，翻页时可能重复看到一条，不会漏。","parameters":[{"name":"updated_since","in":"query","required":false,"description":"只返回这个时间之后（含）有变化的，按变化时间从旧到新排，用于增量拉取；不填时按时间从新到旧排。ISO 8601 格式，不写时区按 UTC 算；在网址里 + 要写成 %2B。","schema":{"type":"string","maxLength":40,"default":""},"example":"2026-11-01T00:00:00+00:00"},{"name":"limit","in":"query","required":false,"description":"每页条数。","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"description":"跳过前多少条。","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"记录列表。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordsPage"},"example":{"items":[{"id":"00000000-0000-0000-0000-0000000000c1","action":"submit","by":"owner","note":null,"created_at":"2026-11-03T02:00:00+00:00"}],"total":1,"reports":{"open":0,"resolved":0}}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/inquiries":{"get":{"operationId":"listInquiries","tags":["客户咨询"],"summary":"拉取买家询价列表","x-scope":"inquiries:read","description":"买家询价只有买家显示名和即时通信链接，没有电话和邮箱。带 updated_since 时按变化时间从旧到新，用于增量拉取。counts 不受 status 和 updated_since 影响，始终是全部询价的各状态条数（后端未提供时不返回）。","parameters":[{"name":"status","in":"query","required":false,"description":"只看某个状态；不填看全部。","schema":{"type":"string","enum":["","new","contacted","negotiating","agreed","closed"],"default":""}},{"name":"updated_since","in":"query","required":false,"description":"只返回这个时间之后（含）有变化的，按变化时间从旧到新排，用于增量拉取；不填时按时间从新到旧排。ISO 8601 格式，不写时区按 UTC 算；在网址里 + 要写成 %2B。","schema":{"type":"string","maxLength":40,"default":""},"example":"2026-11-01T00:00:00+00:00"},{"name":"limit","in":"query","required":false,"description":"每页条数。","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"description":"跳过前多少条。","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"询价列表。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiriesPage"},"example":{"items":[{"id":"00000000-0000-0000-0000-0000000000a1","product_name":"示例商品","quantity_text":"100 件","message":"想了解批量价格","status":"new","merchant_note":null,"revision":1,"buyer":{"name":"示例买家"},"conversation_url":"/im?conversation=example","replied":false,"last_reply_at":null,"created_at":"2026-11-03T02:00:00+00:00","updated_at":"2026-11-03T02:00:00+00:00"}],"total":1,"counts":{"new":1,"contacted":0,"negotiating":0,"agreed":0,"closed":0}}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/inquiries/{inquiry_id}":{"post":{"operationId":"updateInquiry","tags":["客户咨询"],"summary":"修改询价状态和备注","x-scope":"inquiries:write","description":"没写的字段保持不变；note 写空字符串就清空备注（最多 500 字）。revision 是这条询价自己的，不是店铺的。不能给买家发消息。写操作；店铺被平台下架后不可用（403）。","parameters":[{"name":"inquiry_id","in":"path","required":true,"description":"询价编号，取自 GET /inquiries 的 id。","schema":{"type":"string","maxLength":36},"example":"00000000-0000-0000-0000-0000000000a1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiryBody"},"example":{"revision":1,"status":"contacted","note":"已报价，等对方确认"}}}},"responses":{"200":{"description":"更新后的这条询价。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inquiry"},"example":{"id":"00000000-0000-0000-0000-0000000000a1","product_name":"示例商品","quantity_text":"100 件","message":"想了解批量价格","status":"contacted","merchant_note":"已报价，等对方确认","revision":2,"buyer":{"name":"示例买家"},"conversation_url":"/im?conversation=example","replied":false,"last_reply_at":null,"created_at":"2026-11-03T02:00:00+00:00","updated_at":"2026-11-03T02:00:00+00:00"}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Stale"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/stats":{"get":{"operationId":"getStats","tags":["统计"],"summary":"查看每天浏览与询价数","x-scope":"stats:read","description":"最近若干天每天的浏览数和询价数，day 是北京时间日期。","parameters":[{"name":"days","in":"query","required":false,"description":"统计最近多少天。","schema":{"type":"integer","minimum":7,"maximum":90,"default":30}}],"responses":{"200":{"description":"每日统计。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"},"example":{"days":[{"day":"2026-11-06","views":120,"inquiries":3}],"total_views":120,"total_inquiries":3}}}},"401":{"$ref":"#/components/responses/InvalidKey"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooOften"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"请求头 Authorization: Bearer zsk_…，密钥在商家后台 /my-shop 的“开放接口”标签里建，完整密钥只显示一次。"}},"schemas":{"Shop":{"type":"object","description":"店铺。","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"店铺公开网址。"},"mode":{"type":"string","description":"shop 是商城店铺。"},"name":{"type":"string"},"operator_name":{"type":["string","null"]},"review_status":{"type":"string","enum":["draft","pending","approved","rejected"],"description":"draft 草稿 / pending 审核中 / approved 已通过 / rejected 被退回。"},"public_status":{"type":"string","enum":["unpublished","live","offline","suspended"],"description":"unpublished 还没公开 / live 公开中 / offline 暂时下线 / suspended 被平台下架。"},"review_note":{"type":["string","null"]},"suspend_note":{"type":["string","null"]},"has_unpublished_changes":{"type":"boolean","description":"草稿和线上公开的版本有没有不同。"},"listed":{"type":"boolean","description":"是否已上架合作市场。"},"revision":{"type":"integer","description":"店铺的版本号，每次改动加一。"},"submitted_at":{"type":["string","null"],"format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"draft":{"type":"object","description":"草稿全文：页面、区块、联系方式。GET /shop 里的 site 不含这个字段。"},"node_sync":{"type":"object","description":"新加坡副本的同步状态，内部字段，可忽略。"}}},"ShopOverview":{"type":"object","properties":{"site":{"anyOf":[{"$ref":"#/components/schemas/Shop"},{"type":"null"}],"description":"店铺摘要，不含草稿；还没有店铺时为 null。"},"steps":{"type":"array","description":"开店各步骤的进度。","items":{"type":"object","properties":{"key":{"type":"string"},"state":{"type":"string","description":"done / todo / waiting / blocked / unknown。"},"note":{"type":"string"}}}},"domain":{"type":["object","null"],"description":"独立域名申请，没有时为 null。"},"counts":{"type":"object","properties":{"products_live":{"type":"integer"},"products_draft":{"type":"integer"},"reports_open":{"type":"integer","description":"未处理举报数。"}}}}},"DraftBody":{"type":"object","required":["revision","draft"],"properties":{"revision":{"type":"integer","description":"读到的店铺 revision。"},"draft":{"type":"object","description":"整份草稿，先 GET /draft 再改。"},"name":{"type":["string","null"],"description":"店名，可选。"}}},"ProductsBody":{"type":"object","required":["revision","items"],"properties":{"revision":{"type":"integer","description":"读到的店铺 revision。"},"items":{"type":"array","description":"这个区块的全部商品，整块替换。","items":{"$ref":"#/components/schemas/ProductInput"}}}},"ProductInput":{"type":"object","description":"只能有这四个字段。","properties":{"name":{"type":"string"},"price":{"type":"string","description":"价格文字，例如“39.9 元”。"},"image":{"type":["string","null"],"description":"POST /assets 返回的图片 id，不放图片填 null。"},"text":{"type":"string"}}},"ProductLine":{"type":"object","properties":{"page_key":{"type":"string"},"block_id":{"type":"string"},"index":{"type":"integer","description":"在区块里的位置。"},"name":{"type":"string"},"price":{"type":"string"},"image":{"type":["string","null"],"description":"图片 id。"},"text":{"type":"string"},"change":{"type":"string","enum":["same","changed","new","removed"],"description":"same 未改动 / changed 已改未提交 / new 新增 / removed 草稿里已删。"}}},"ProductBlock":{"type":"object","properties":{"page_key":{"type":"string"},"block_id":{"type":"string"},"title":{"type":"string"},"items":{"type":"integer","description":"区块里的商品条数。"}}},"ProductsView":{"type":"object","properties":{"revision":{"type":"integer"},"review_status":{"type":"string"},"live":{"type":"array","description":"线上商品。","items":{"$ref":"#/components/schemas/ProductLine"}},"draft":{"type":"array","description":"草稿商品。","items":{"$ref":"#/components/schemas/ProductLine"}},"blocks":{"type":"array","description":"草稿里的商品区块。","items":{"$ref":"#/components/schemas/ProductBlock"}},"media":{"type":"object","description":"图片 id 对应的带签名网址（约一小时有效）。","additionalProperties":{"type":"string"}},"problem":{"type":"string","description":"现在还不能提交审核的原因，空字符串表示没问题。"}}},"Asset":{"type":"object","properties":{"id":{"type":"string","description":"填进商品的 image。"},"url":{"type":"string","description":"带签名的图片网址，约一小时有效。"},"width":{"type":"integer"},"height":{"type":"integer"},"bytes":{"type":"integer"}}},"SubmitBody":{"type":"object","required":["revision"],"properties":{"revision":{"type":"integer","description":"店铺的 revision。"},"overseas_consent":{"type":"boolean","default":false,"description":"必须是 true（真正的布尔值），表示同意页面放在新加坡服务器；否则返回 422。"}}},"PlatformRecord":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string","description":"submit、withdraw、offline、online 是店主自己做的；approve、reject、suspend、restore 是平台做的。"},"by":{"type":"string","enum":["owner","platform"]},"note":{"type":["string","null"],"description":"平台写的说明；店主自己的操作为 null。"},"created_at":{"type":"string","format":"date-time"}}},"RecordsPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PlatformRecord"}},"total":{"type":"integer"},"reports":{"type":"object","properties":{"open":{"type":"integer","description":"未处理。"},"resolved":{"type":"integer","description":"已处理。"}}}}},"Inquiry":{"type":"object","description":"没有的值是 null。","properties":{"id":{"type":"string"},"product_name":{"type":["string","null"]},"quantity_text":{"type":["string","null"]},"message":{"type":["string","null"]},"status":{"type":"string","enum":["new","contacted","negotiating","agreed","closed"],"description":"new 新询价 / contacted 已联系 / negotiating 洽谈中 / agreed 已谈成 / closed 已关闭。"},"merchant_note":{"type":["string","null"]},"revision":{"type":"integer","description":"这条询价自己的版本号。"},"buyer":{"type":"object","properties":{"name":{"type":["string","null"],"description":"买家显示名。"}}},"conversation_url":{"type":["string","null"],"description":"即时通信里这个私聊的链接。"},"replied":{"type":["boolean","null"],"description":"你有没有在私聊里回过。"},"last_reply_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"InquiriesPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Inquiry"}},"total":{"type":"integer"},"counts":{"type":"object","description":"全部询价的五种状态各有几条。","properties":{"new":{"type":"integer"},"contacted":{"type":"integer"},"negotiating":{"type":"integer"},"agreed":{"type":"integer"},"closed":{"type":"integer"}}}}},"InquiryBody":{"type":"object","required":["revision"],"properties":{"revision":{"type":"integer","description":"这条询价自己的 revision。"},"status":{"type":["string","null"],"enum":["new","contacted","negotiating","agreed","closed",null],"description":"不填保持不变。"},"note":{"type":["string","null"],"maxLength":500,"description":"备注；空字符串清空，不填保持不变。"}}},"Stats":{"type":"object","properties":{"days":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","format":"date","description":"北京时间日期。"},"views":{"type":"integer"},"inquiries":{"type":"integer"}}}},"total_views":{"type":"integer"},"total_inquiries":{"type":"integer"}}},"Error":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string","description":"中文说明。"}}}},"responses":{"InvalidKey":{"description":"密钥无效：没带、格式不对、不存在、已过期、已撤销，或店主账号、店铺不可用，一律是同一句，不说明是哪一种。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"开放接口密钥无效。"}}}},"Forbidden":{"description":"这把密钥没有所需权限，或店铺已被平台下架（下架后只能读，写接口都不行）。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"这把密钥没有“修改店铺”权限。"}}}},"NotFound":{"description":"草稿里没有这个商品区块，或没有这条询价。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"草稿里没有这个商品区块。"}}}},"Stale":{"description":"revision 对不上，这份内容在别处被改过，什么也没改。重新读取再改；提交发布时身份未核验也返回 409。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"数据已被改动，请刷新。"}}}},"Invalid":{"description":"请求体缺字段、多了不认识的字段、格式不对，或查询参数超出范围，返回统一提示；其余 422 带具体中文说明。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"内容不完整或格式不正确，请检查必填项、长度及提交确认。"}}}},"TooOften":{"description":"调用太频繁。响应头 Retry-After 是需要等待的秒数。","headers":{"Retry-After":{"description":"需要等待的秒数。","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"调用太频繁，请 12 秒后再试。"}}}},"Unavailable":{"description":"服务暂时不可用，稍后再试。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"服务暂时不可用，请稍后再试。"}}}}}}}