供应商API快速入门：创建、更新、删除产品并履行订单
将目录同步到Accplanet的供应商团队需要一个清晰的闭环：创建或更新产品、保持库存准确、履行订单，并在出现问题时处理退款或工单。本快速入门指南将使用实时供应商API文档带您走完这个闭环。
Accplanet是一个供应商聚合市场。您负责履行库存；平台负责买家发现、结账、物流跟踪和支持工具。请仅将这些端点用于合法的目录和订单操作 — 而非规避政策或不安全的自动化。
简介
- 使用
X-API-Key、Authorization: Bearer、请求体key/apikey或有效的供应商仪表板会话进行身份验证。 - 产品：上传图片 → 创建 → 列表/更新 → 追加自动交付账户 → 仅在规则允许时删除。
- 订单：列表 → 获取 → 更新交付信息/附件 → 更改状态 → 在适当时退款。
- 新上架商品可能需要管理员审批后才能公开显示。
- 编码时请保持官方文档打开，以获取准确的路径和参数表。
身份验证
使用您个人资料中的供应商API密钥。JSON产品/订单调用通常发送：
X-API-Key: YOUR_API_KEY
Content-Type: application/json当您登录供应商仪表板时，浏览器会话身份验证同样有效 — 与文档中的测试API面板配合使用非常方便。
产品生命周期
1 · 第一步
上传图片
POST /products/api/supplier/upload-image/，使用multipart图片文件。保存返回的image_path，用于创建/更新时的images数组。
2 · 创建
创建产品（或按来源URL更新插入）
POST /products/api/supplier/create/需要category_id、title、description、price。可选字段：stock、min_quantity、images、source_product_id、source_product_url、warranty_period_days、status，以及通过accounts或accounts_text配置的自动交付池。
如果source_product_url与您账户下的旧商品匹配，API可能会更新该商品而不是创建重复项（响应中的created/updated标志）。请关注approval_status。
3 · 维护
列表、查询、更新
GET /products/api/supplier/products/— 分页列表，支持搜索、分类、状态、价格筛选。GET /products/api/supplier/products/by-source-id/<source_product_id>/— 按上游ID热同步的快速路径。POST /products/api/supplier/products/<product_id>/update/— 更新标题、价格、库存、图片、来源字段、状态或交付池字段。
通过数字目录ID或列表响应中的product_id来识别产品。买家在分配后会将目录ID视为客户API的service值。
4 · 交付池
追加自动交付账户
POST .../products/<product_id>/accounts/将凭据添加到自动交付池，而无需重写已上架库存。使用结构化accounts对象或accounts_text行（user:pass / user|pass）。谨慎处理返回的accounts_imported — 这些是机密信息。
5 · 删除
在允许时删除
POST .../products/<product_id>/delete/永久删除没有已完成销售的产品。当您只需要停止销售时，优先使用状态更改。
| 端点重点 | 方法路径（主机 accplanet.com） | 典型用途 |
|---|---|---|
| 上传图片 | POST /products/api/supplier/upload-image/ |
获取image_path |
| 创建 | POST /products/api/supplier/create/ |
新上架 / 按来源URL更新插入 |
| 列表 | GET /products/api/supplier/products/ |
同步状态 |
| 按来源ID | GET .../by-source-id/<id>/ |
热同步 |
| 更新 | POST .../products/<id>/update/ |
价格、库存、文案 |
| 追加账户 | POST .../products/<id>/accounts/ |
自动交付池 |
| 删除 | POST .../products/<id>/delete/ |
移除未使用的SKU |
订单生命周期
买家购买后，通过订单API履行订单：
- 列表 —
GET /orders/api/supplier/orders/，可选的status、search、分页参数。 - 获取 —
GET /orders/api/<order_id>/，当您需要单个订单快照时使用。 - 交付 —
POST .../orders/<order_id>/delivered/，附带delivered_info（纯文本或JSON数组字符串）。设置append_delivered_info=true以追加行。或通过.../delivery-attachment/上传文件（multipartfile，≤10MB）。 - 状态 —
POST .../orders/<order_id>/status/，允许的值包括pending_order、running_order、completed_order、refunded_order。receipt_confirmed_order不能通过API设置。 - 退款 —
POST .../orders/<order_id>/refund/，当您的流程需要时进行全额退款。
跟踪列表/获取响应中的delivered_units、remaining_to_deliver和付款字段，使您的仓库逻辑与仪表板保持一致。
自动交付池
在产品上预载账户；Accplanet可以排队交付任务。
手动delivered_info
在人工管理履行时，按订单推送凭据或密钥。
附件
当文本字段不够用时，上传单个履行文件。
工单、付款、余额
- 工单 — 在
/orders/api/supplier/tickets/下进行列表、获取、创建（order_id+ 标题 + 描述）、更新状态/回复。 - 付款 —
GET /orders/api/supplier/payments/获取您供应订单的付款记录。 - 余额 —
GET /users/api/balance/返回已认证账户的客户和供应商钱包余额。
审批状态、库存和订单状态遵循实时平台规则。在发布生产同步时，请对照当前的供应商API文档确认行为。
供应商清单
- [ ] 供应商API密钥存储在服务器端
- [ ]
category_id已从Accplanet分类映射（需要时使用叶子子分类） - [ ] 创建/更新路径已先用非生产标题测试
- [ ] 同步作业中的库存和价格更新是幂等的
- [ ] 交付池或手动
delivered_info路径已在测试订单上验证 - [ ] 订单状态转换与仪表板允许的值一致
- [ ] 工单+退款路径已为您的支持团队记录
下一步：打开供应商API文档，使用测试API进行身份验证，创建一个草稿产品，然后在沙盒式订单上练习列表 → 交付 → 状态。集成购买的买家应使用Accplanet博客上的客户API快速入门指南。
常见问题
为什么我的新产品对买家不可见？
上架商品可能需要管理员审批（approval_status）。仅在您准备好销售时才将商品保持active状态，并在响应或仪表板中确认审批。
product_id和business_id有什么区别？
product_id是供应商路径中使用的系统标识符。business_id是分配时的数字目录ID — 买家通常将其视为客户API的service。
追加账户会改变已上架库存吗？
不会。追加账户仅更新自动交付池。除非您的运营流程将两者关联，否则请通过创建/更新字段单独管理已上架的stock。
我可以通过API设置哪些订单状态？
文档中的值包括pending_order、running_order、completed_order和refunded_order。买家收货确认不能通过API设置。
