开发接口文档红雀拍单 · API Referencev1

接入指南

从账号到订单的调用顺序
01

建立会话

获取图形验证码,注册或登录。成功后服务端写入 HttpOnly 会话 Cookie。

02

关联店铺

获取授权跳转地址,完成平台授权;也可创建上货店铺导入任务。

03

处理订单

创建同步任务,按待下单、待发货、已发货、交易成功与售后视图查询订单,绑定商品货源链接,并使用收件信息与批量任务接口。

接口基址https://dev.waybill.hongquesoft.com/api/v1

通用约定

  • 除特别说明外,接口使用 JSON,返回 {"ok":true,"data":...};错误返回 {"ok":false,"code":"...","message":"..."}。
  • 认证使用同源浏览器 Cookie hq_waybill_session。前端请求应携带 Cookie;不要读取或存储会话值。
  • 主账号管理自己的店铺;运营账号仅可访问主账号授权给它的店铺和关联订单。未登录返回 HTTP 401;参数不合法通常返回 HTTP 422。
  • 分页默认从 1 开始。支持 page_size=10、20、50、100 的列表会返回 rows、total、page、page_size。
  • 首页展示接口文档;独立 H5 页面位于 /h5/。授权回调返回发起授权的页面,并带上 shop_auth、shop_sync 查询参数。
当前后端按同源 Cookie 会话工作,尚未配置跨域 CORS。前端开发环境请通过同源代理转发 /api/v1;不要在浏览器里直连另一域名并依赖第三方 Cookie。

账号与会话

验证码、注册、登录与退出
GET/api/v1/auth/captcha

获取图形验证码

免登录

请求参数

字段类型说明
——无需额外参数

返回一次性验证码 ID 与图片 data URL;有效期 120 秒。提交注册或登录时同时传入 captcha_id 和用户输入的 captcha。

GET /api/v1/auth/captcha
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idstring一次性验证码 ID
data.imagestringPNG 图片 data URL
data.expires_ininteger有效秒数
POST/api/v1/auth/register

注册账号

免登录

请求头 Content-Type: application/json。成功返回 HTTP 201、用户信息,并建立登录会话。测试环境新注册主账号赠送 100 额度点,余额可通过 GET /api/v1/credits 查询。

字段类型说明
display_name *string称呼,1–40 字符
username *string4–24 位,以字母开头,可含小写字母、数字、下划线
password *string8–64 字符,最多 72 字节
confirm_passwordstring可选;提供时必须与密码相同
captcha_id *string验证码接口返回的 ID
captcha *string图片中的 5 位字符,不区分大小写
POST /api/v1/auth/register
Content-Type: application/json
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger账号 ID
data.usernamestring登录用户名
data.display_namestring称呼
data.rolestringowner 主账号或 operator 运营账号
data.owner_user_idinteger所属主账号 ID
POST/api/v1/auth/login

账号登录

免登录

请求参数

字段类型说明
usernamestring账号,4–24 位
passwordstring账号密码
captcha_idstring验证码 ID
captchastring图片中的验证码

主账号和运营账号共用此接口,均需图形验证码。JSON 字段:username、password、captcha_id、captcha。成功返回用户 id、username、display_name、role、owner_user_id 并写入会话 Cookie。role 为 owner 或 operator;同名运营账号通过各自密码登录。

fetch('/api/v1/auth/login', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  credentials: 'same-origin',
  body: JSON.stringify({
    username: 'example_user',
    password: '<password>',
    captcha_id: '<captcha-id>',
    captcha: 'ABCDE'
  })
});
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger账号 ID
data.usernamestring登录用户名
data.display_namestring称呼
data.rolestringowner 主账号或 operator 运营账号
data.owner_user_idinteger所属主账号 ID
GET/api/v1/auth/me

当前用户

请求参数

字段类型说明
——无需额外参数

读取当前会话。成功返回用户 id、username、display_name、role、owner_user_id;会话失效返回 401。

GET /api/v1/auth/me
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger账号 ID
data.usernamestring登录用户名
data.display_namestring称呼
data.rolestringowner 主账号或 operator 运营账号
data.owner_user_idinteger所属主账号 ID
POST/api/v1/auth/logout

退出登录

请求参数

字段类型说明
参数stringJSON 空对象 {}

以 JSON 请求体 {} 提交。成功后服务端销毁会话并清除 Cookie。

POST /api/v1/auth/logout
Content-Type: application/json
返回字段说明
字段类型说明
okboolean请求成功为 true
datanull退出成功后为 null;会话 Cookie 同时清除

账号额度

主账号余额与变动流水

额度规则

每个主账号拥有独立额度账户,运营账号查询所属主账号的同一余额。测试环境新注册的主账号一次性获得 100 额度点;迁移前已有的主账号初始余额为 0。创建运营账号不会赠送额度。当前没有公开的充值或扣减接口。

GET/api/v1/credits

查询当前额度

请求参数

字段类型说明
——无需额外参数

登录后查询当前主账号的额度余额;运营账号返回所属主账号的余额。

GET /api/v1/credits
返回字段说明
字段类型说明
okboolean请求成功为 true
data.owner_user_idinteger额度所属主账号 ID
data.balanceinteger当前额度余额,单位为额度点
data.updated_atdatetime余额最后变更时间
GET/api/v1/credits/ledger

额度流水

请求参数

字段类型说明
pageinteger页码,默认 1
page_sizeinteger每页 10、20、50 或 100 条,默认 20

按时间倒序分页返回当前主账号的额度变动记录。

GET /api/v1/credits/ledger
返回字段说明
字段类型说明
okboolean请求成功为 true
data.rowsarray当前页记录
data.totalinteger符合条件的记录总数
data.pageinteger当前页码
data.page_sizeinteger每页条数
data.rows[].idinteger流水 ID
data.rows[].deltainteger额度变动,正数为增加
data.rows[].balance_afterinteger变动后余额
data.rows[].reasonstring变动原因;signup_bonus 为注册赠送
data.rows[].created_atdatetime发生时间

运营账号

主账号创建子账号与授权店铺

权限说明

以下三个接口仅主账号可调用。一个店铺可以同时授权给多个运营账号;每个运营账号也可操作多个店铺。授权变更立即影响店铺、订单、同步任务及收件信息查询。运营账号可用普通登录接口登录,但不能创建运营账号、授权或删除店铺、发起店铺授权与导入。

POST/api/v1/operators

创建运营账号

请求头 Content-Type: application/json。成功返回 HTTP 201。shop_ids 可在创建时指定,也可稍后设置;密码不会回传。不同主账号允许使用相同运营用户名和不同密码;如果用户名与密码的组合已经存在,返回 HTTP 409、USERNAME_TAKEN、该用户名已被使用。

字段类型说明
username *string4–24 位,以字母开头;统一转小写
password *string运营账号密码 6–64 字符,最多 72 字节
display_namestring称呼,1–40 字符;省略时使用用户名
shop_idsinteger[]当前主账号店铺的本地 ID 数组;默认空数组
{"username":"abc123","password":"adc456","display_name":"运营一组","shop_ids":[123,456]}

返回 data 包含 id、username、display_name、role、owner_user_id、shop_ids、status、created_at。

返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger运营账号 ID
data.usernamestring登录用户名
data.display_namestring称呼
data.rolestring固定 operator
data.owner_user_idinteger创建者主账号 ID
data.shop_idsinteger[]获授权的本地店铺 ID
data.statusinteger1 为可用
data.created_atdatetime创建时间
GET/api/v1/operators

运营账号列表

请求参数

字段类型说明
pageinteger页码,默认 1
page_sizeinteger每页 10、20、50 或 100 条

查询参数 page 与 page_size,返回 rows、total、page、page_size。每行包含已授权的 shop_ids,便于前端展示和编辑。

GET /api/v1/operators
返回字段说明
字段类型说明
okboolean请求成功为 true
data.rowsarray当前页记录
data.totalinteger符合条件的记录总数
data.pageinteger当前页码
data.page_sizeinteger每页条数
data.rows[].idinteger运营账号 ID
data.rows[].usernamestring登录用户名
data.rows[].display_namestring称呼
data.rows[].statusinteger账号状态
data.rows[].last_login_atdatetime / null最近登录时间
data.rows[].shop_idsinteger[]已授权店铺 ID
data.rows[].rolestring固定 operator
data.rows[].owner_user_idinteger所属主账号 ID
PUT/api/v1/operators/:id/shops

设置可操作店铺

请求参数

字段类型说明
idinteger路径参数,运营账号 ID
shop_idsinteger[]JSON 数组,完整替换授权店铺;[] 撤销全部

JSON 请求体:{"shop_ids":[123,456]}。提交的数组整体替换该运营账号的现有授权;传 [] 则撤销全部。只能设置当前主账号创建的运营账号和自己拥有的店铺。返回 {"id":7,"shop_ids":[123,456]}。

PUT /api/v1/operators/:id/shops
Content-Type: application/json
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger运营账号 ID
data.shop_idsinteger[]更新后的店铺 ID 列表

店铺管理

列表、授权与导入
GET/api/v1/shops

当前账号的店铺列表

请求参数

字段类型说明
——无需额外参数

返回数组。常用字段:id、shop_name、platform、shop_id、source、service_expires_at、service_status、has_authorization、created_at。该接口目前一次返回全部店铺,前端自行搜索或分页。

GET /api/v1/shops
返回字段说明
字段类型说明
okboolean请求成功为 true
data[].idinteger本地店铺 ID
data[].shop_namestring店铺名称
data[].platformstring平台
data[].shop_idstring平台店铺 ID
data[].sourcestring授权来源
data[].service_expires_atstring / null服务到期时间
data[].service_statusstringactive 或 expired
data[].has_authorizationboolean是否已有授权
data[].created_atstring创建时间
GET/api/v1/xhs/oauth/start

获取授权跳转地址

请求参数

字段类型说明
——可选查询参数 return_to=h5,授权完成后返回 /h5/;省略时返回首页

返回 {"ok":true,"data":{"url":"https://..."}}。浏览器跳转到 data.url 完成授权。回调由服务端处理,成功后自动创建近 30 天订单同步任务。

回调路径:/api/v1/xhs/oauth/callback,由平台浏览器流程调用,前端无需直接请求。

GET /api/v1/xhs/oauth/start
返回字段说明
字段类型说明
okboolean请求成功为 true
data.urlstring平台授权跳转地址
DELETE/api/v1/shops/:id

删除店铺

请求参数

字段类型说明
idinteger路径参数,本地店铺 ID

删除当前账号指定店铺及关联授权与订单数据。操作不可撤销,前端应展示店铺名称和影响并要求用户明确确认。

DELETE /api/v1/shops/:id
返回字段说明
字段类型说明
okboolean请求成功为 true
datanull删除成功后为 null
POST/api/v1/shop-import-jobs

创建上货店铺导入任务

请求参数

字段类型说明
usernamestring上货账号
passwordstring上货密码

JSON 请求体为 {"username":"<上货账号>","password":"<上货密码>"}。成功返回 HTTP 201 和任务摘要。账号密码仅用于本次请求,不在前端持久保存。

POST /api/v1/shop-import-jobs
Content-Type: application/json
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger导入任务 ID
data.statusstringrunning、completed 或 failed
data.totalinteger店铺总数
data.processedinteger已处理数
data.importedinteger已导入数
data.failedinteger失败数
data.last_errorstring / null最近错误
data.created_atdatetime创建时间
data.updated_atdatetime更新时间
GET/api/v1/shop-import-jobs/latest

最近一次导入任务

请求参数

字段类型说明
——无需额外参数

返回最近任务或 null。任务摘要包含 id、status、total、processed、imported、failed、last_error 等进度字段。

GET /api/v1/shop-import-jobs/latest
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger导入任务 ID
data.statusstringrunning、completed 或 failed
data.totalinteger店铺总数
data.processedinteger已处理数
data.importedinteger已导入数
data.failedinteger失败数
data.last_errorstring / null最近错误
data.created_atdatetime创建时间
data.updated_atdatetime更新时间
datanull没有历史任务时为 null
POST/api/v1/shop-import-jobs/:id/step

推进导入任务

请求参数

字段类型说明
idinteger路径参数,导入任务 ID

导入任务为 running 时顺序调用,每次处理一家店铺;根据返回的 processed/total 更新进度,直到 status 变为 completed 或 failed。不要并发调用同一个任务。

POST /api/v1/shop-import-jobs/:id/step
Content-Type: application/json
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger导入任务 ID
data.statusstringrunning、completed 或 failed
data.totalinteger店铺总数
data.processedinteger已处理数
data.importedinteger已导入数
data.failedinteger失败数
data.last_errorstring / null最近错误
data.created_atdatetime创建时间
data.updated_atdatetime更新时间

订单同步

后台任务与进度
POST/api/v1/order-sync-jobs

创建同步任务

支持 JSON 或表单提交。一个店铺同时只能有一个排队或运行中的同步任务。

字段类型说明
shop_id *integer店铺列表中的 id
scope *stringlast30 近 30 天、month 近一个月、year 近一年、all 全部
order_statusinteger0–9,默认 0 表示全部状态
order_typeinteger0–5,默认 0 表示全部类型
{"shop_id":123,"scope":"last30","order_status":0,"order_type":0}
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger同步任务 ID
data.shop_record_idinteger本地店铺 ID
data.shop_namestring店铺名称
data.scopestring同步范围
data.order_status_filterinteger订单状态过滤值
data.order_type_filterinteger订单类型过滤值
data.statusstringqueued、running、completed、failed 或 cancelled
data.processed_ordersinteger已处理订单数
data.completed_windowsinteger已完成时间窗口数
data.total_windowsinteger总时间窗口数
data.page_nointeger当前平台页码
data.error_messagestring / null错误信息
data.created_atdatetime创建时间
data.started_atdatetime / null开始时间
data.finished_atdatetime / null结束时间
data.user_idinteger所属主账号 ID
data.start_tsinteger起始 Unix 时间戳
data.end_tsinteger结束 Unix 时间戳
data.cursor_tsinteger当前时间窗口游标
GET/api/v1/order-sync-jobs

同步任务列表

请求参数

字段类型说明
pageinteger页码,默认 1
page_sizeinteger每页 10、20、50 或 100 条

查询参数 page、page_size。返回分页字段及 active_shop_ids,任务行包含 status、processed_orders、completed_windows、total_windows、page_no、error_message 等。

GET /api/v1/order-sync-jobs
返回字段说明
字段类型说明
okboolean请求成功为 true
data.rowsarray当前页记录
data.totalinteger符合条件的记录总数
data.pageinteger当前页码
data.page_sizeinteger每页条数
data.active_shop_idsinteger[]当前有排队或运行任务的店铺 ID
data.rows[].idinteger同步任务 ID
data.rows[].shop_record_idinteger本地店铺 ID
data.rows[].shop_namestring店铺名称
data.rows[].scopestring同步范围
data.rows[].order_status_filterinteger订单状态过滤值
data.rows[].order_type_filterinteger订单类型过滤值
data.rows[].statusstringqueued、running、completed、failed 或 cancelled
data.rows[].processed_ordersinteger已处理订单数
data.rows[].completed_windowsinteger已完成时间窗口数
data.rows[].total_windowsinteger总时间窗口数
data.rows[].page_nointeger当前平台页码
data.rows[].error_messagestring / null错误信息
data.rows[].created_atdatetime创建时间
data.rows[].started_atdatetime / null开始时间
data.rows[].finished_atdatetime / null结束时间
DELETE/api/v1/order-sync-jobs/:id

取消同步任务

请求参数

字段类型说明
idinteger路径参数,同步任务 ID

任务处于 queued 或 running 时可取消,已经同步的订单保留。兼容旧调用 POST /api/v1/order-sync-jobs/:id/cancel。

DELETE /api/v1/order-sync-jobs/:id
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger同步任务 ID
data.statusstring取消后为 cancelled
POST/api/v1/order-sync-jobs/:id/cancel

取消同步任务(兼容路径)

请求参数

字段类型说明
idinteger路径参数,同步任务 ID

旧版前端可继续调用此路径,行为和 DELETE /api/v1/order-sync-jobs/:id 相同。

POST /api/v1/order-sync-jobs/:id/cancel
Content-Type: application/json
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger同步任务 ID
data.statusstring取消后为 cancelled

订单查询

筛选、分页与导出
GET/api/v1/orders

订单列表

以拍单平台的订单处理视图为主,仍只返回当前账号可见店铺的订单。view=pending_purchase 为待下单:小红书待发货且没有本平台采购订单号;view=after_sale 为已收到并处理小红书售后通知的订单;历史售后订单不会自动回填,需订阅售后消息并完成历史数据补录。其他视图直接按店铺订单状态显示。响应为 rows、total、page、page_size、all_orders、phone_available;行内收件字段默认使用脱敏值。

查询参数格式说明
page / page_sizeinteger页码及每页 10、20、50、100 条;默认 1 / 20
shop_idinteger来源店铺 ID;省略表示全部
viewstringall(默认)、pending_purchase(待下单)、pending_shipment(店铺待发货)、shipped(部分发货/待收货)、completed(交易成功)、after_sale(售后订单)。可与其他筛选条件取交集
order_status0–90 全部,1 待付款,2 已支付处理中,3 清关中,4 待发货,5 部分发货,6 待收货,7 已完成,8 已关闭,9 已取消
order_type0–50 全部,1 现货,2 定金预售,3/4 全款预售,5 换货补发
paid_from / paid_toYYYY-MM-DD成交日期起止,包含当天
order_no / titlestring订单号、宝贝标题模糊搜索
remark / software_remark / messagestring店铺备注、软件备注、买家留言分别模糊搜索
provincestring收货省份模糊搜索
phone4 或 11 位数字手机号尾号 4 位或完整 11 位
flag_colors1,2,...旗帜颜色多选,1–6 逗号分隔;省略表示全部
sortrecent / oldest成交时间倒序或正序,默认 recent
GET /api/v1/orders?view=pending_purchase&page=1&page_size=20&sort=recent
返回字段说明
字段类型说明
okboolean请求成功为 true
data.rowsarray当前页记录
data.totalinteger符合条件的记录总数
data.pageinteger当前页码
data.page_sizeinteger每页条数
data.all_ordersinteger可见店铺的全部订单数
data.phone_availableinteger可按手机号筛选的订单数
data.rows[].idinteger本地订单 ID
data.rows[].shop_record_idinteger本地店铺 ID
data.rows[].shop_namestring店铺名称
data.rows[].seller_idstring平台卖家 ID
data.rows[].external_order_idstring平台订单号
data.rows[].paid_atdatetime / null成交时间
data.rows[].order_statusinteger订单状态
data.rows[].order_typeinteger订单类型
data.rows[].purchase_order_nostring本平台采购订单号;空字符串表示尚未拍单
data.rows[].has_after_saleinteger1 表示已收到该订单的售后通知
data.rows[].item_titlestring宝贝标题
data.rows[].item_image_urlstring首件商品图片 URL
data.rows[].item_linesarray商品明细,逐项含 item_id 与 source_url;绑定按主账号 + 商品 ID 复用
data.rows[].buyer_user_idstring买家平台 ID
data.rows[].actual_received_centsinteger / null实收款,单位分
data.rows[].shipping_fee_centsinteger / null运费,单位分
data.rows[].seller_remarkstring店铺备注
data.rows[].software_remarkstring软件备注
data.rows[].seller_remark_flaginteger旗帜颜色值
data.rows[].customer_remarkstring买家留言
data.rows[].receiver_name_maskedstring脱敏姓名
data.rows[].receiver_phone_maskedstring脱敏手机号
data.rows[].receiver_address_maskedstring脱敏地址
data.rows[].receiver_provincestring收货省份
data.rows[].has_reveal_cacheboolean是否已有可查看的结果
data.rows[].can_reveal_nameboolean姓名可查看提示
data.rows[].can_reveal_phoneboolean手机号可查看提示
data.rows[].can_reveal_addressboolean地址可查看提示

订单行字段

下列字段位于 data.rows[]。可为空的数据请做好占位展示;金额均为整数分,前端展示时除以 100。

字段类型用途
id / external_order_idinteger / string本地订单 ID 用于查看收件信息;平台订单号用于展示和批量任务
shop_record_id / shop_name / seller_idinteger / string / string本地店铺 ID、店铺名称、平台卖家 ID
paid_at / order_status / order_typestring|null / integer / integer成交时间、订单状态、订单类型
purchase_order_no / has_after_salestring / integer本平台采购订单号、是否收到售后通知;同步订单时保留本地采购订单号
item_title / item_image_urlstring / string汇总商品标题、首件商品图片 URL;图片可能为空
item_linesarray商品明细,每项含 title、image_url、spec、sku_id、item_id、quantity、unit_price_cents、source_url
buyer_user_idstring平台买家 ID;可能为空
actual_received_cents / shipping_fee_centsinteger|null实收金额、运费,单位分;可能为空
seller_remark / software_remark / seller_remark_flag / customer_remarkstring / string / integer / string店铺备注、软件备注、旗帜颜色值、买家留言
receiver_name_masked / receiver_phone_masked / receiver_address_masked / receiver_provincestring列表可展示的脱敏收件信息与省份
has_reveal_cache / can_reveal_name / can_reveal_phone / can_reveal_addressboolean服务端返回的查看能力提示;实际查看仍调用对应接口
PUT/api/v1/orders/:id/purchase-order

记录采购订单号

保存本平台采购单号;此接口只记录编号,不执行采购或发货。设置后,待发货订单会退出待下单视图;传空字符串可清空。订单再次同步不会覆盖该字段。

字段类型说明
id *integer路径参数,本地订单 ID
shop_id *integer订单所属店铺 ID,须有操作权限
purchase_order_no *string采购订单号,最多 120 字符;空字符串清空
{"shop_id":123,"purchase_order_no":"PO123456789"}
返回字段说明
字段类型说明
okboolean成功为 true
data.id / data.shop_record_idinteger本地订单与店铺 ID
data.purchase_order_nostring保存后的采购订单号
data.updated_atdatetime更新时间
PUT/api/v1/item-source-links/:itemId

绑定货源链接

以当前主账号和小红书商品 item_id 为键,同一商品在多个订单中共用货源链接。绑定前会核对该商品出现在请求店铺的已同步订单里。传空字符串可解绑;接口不会抓取或验证货源网页内容。

字段类型说明
itemId *string路径参数,订单行 item_lines[].item_id
shop_id *integer有权操作且包含该商品的店铺 ID
source_url *stringHTTPS 货源链接,最多 2048 字节;空字符串解绑
PUT /api/v1/item-source-links/101535728994
{"shop_id":123,"source_url":"https://detail.1688.com/offer/1058657782.html"}
返回字段说明
字段类型说明
okboolean成功为 true
data.item_idstring商品 ID
data.source_urlstring保存后的链接;空字符串表示解绑
data.updated_atdatetime更新时间
GET/api/v1/orders/export

导出筛选结果

请求参数

字段类型说明
筛选参数object与 GET /api/v1/orders 一致,不使用分页参数

使用与订单列表相同的筛选参数,返回 UTF-8 CSV 文件。收件列使用脱敏内容,不包含查看明文的结果。

GET /api/v1/orders/export
返回字段说明
字段类型说明
okboolean请求成功为 true
Content-Typestringtext/csv; charset=UTF-8
文件列CSV订单号、成交时间、来源店铺、订单状态、订单类型、宝贝标题、实收款、快递费、买家 ID、店铺备注、软件备注、买家留言、旗帜颜色、脱敏姓名、脱敏手机号、脱敏地址、收货省份
PUT/api/v1/orders/:id/shop-remark

修改店铺备注

请求参数

字段类型说明
idinteger路径参数,订单列表行的本地订单 ID
shop_idinteger必填,GET /api/v1/shops 返回的本地店铺 ID,须与订单所属店铺一致
remarkstring必填,店铺备注;空字符串表示清空,最多 500 字
flaginteger可选,旗帜颜色 1–6;省略时保留原颜色,无旗帜则使用 1

按订单所属店铺的授权向小红书提交备注和旗帜颜色,成功后更新本地订单。操作人由当前登录账号确定。平台提交失败时本地备注不变。

{"shop_id":123,"remark":"优先处理","flag":2}
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger本地订单 ID
data.shop_record_idinteger本地店铺 ID
data.seller_remarkstring已提交到小红书的店铺备注
data.seller_remark_flaginteger旗帜颜色,1–6
data.updated_atdatetime本地更新时间
PUT/api/v1/orders/:id/software-remark

修改软件备注

请求参数

字段类型说明
idinteger路径参数,订单列表行的本地订单 ID
shop_idinteger必填,GET /api/v1/shops 返回的本地店铺 ID,须与订单所属店铺一致
remarkstring必填,软件备注;空字符串表示清空,最多 1000 字

备注只保存到拍单数据库,订单再次同步时保留。两类备注均需登录,并只能操作主账号或已分配店铺的运营账号可见订单。

{"shop_id":123,"remark":"内部处理记录"}
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger本地订单 ID
data.shop_record_idinteger本地店铺 ID
data.software_remarkstring拍单内保存的软件备注
data.updated_atdatetime更新时间

收件信息

单笔查看与批量任务
收件姓名、手机号和地址属于敏感信息。仅在用户明确操作时调用查看接口;不要写入浏览器持久存储、前端日志或普通订单导出。接口会按账号校验订单归属并实施限流。
POST/api/v1/orders/:id/reveal-recipient

查看单笔收件信息

请求参数

字段类型说明
idinteger路径参数,本地订单 ID

:id 是订单列表行的数据库 id。成功返回 order_id 和 values.name、values.phone、values.address。请求应携带会话 Cookie;建议只在用户点击“查看明文”后发起。

POST /api/v1/orders/:id/reveal-recipient
Content-Type: application/json
返回字段说明
字段类型说明
okboolean请求成功为 true
data.order_idinteger本地订单 ID
data.values.namestring收件人姓名
data.values.phonestring收件人手机号
data.values.addressstring收件地址
POST/api/v1/recipient-decrypt-jobs

创建批量查看任务

请求参数

字段类型说明
order_numbersstringJSON 字段,换行分隔的订单号,最多 200 个

JSON 字段 order_numbers 为换行分隔的订单号字符串,单次最多 200 个。系统按当前账号已有订单核对;同一账号同时只允许一个运行中的任务。

{"order_numbers":"P123456789012345678\nP123456789012345679"}
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger任务 ID
data.statusstringqueued、running、completed 或 cancelled
data.total_ordersinteger订单总数
data.processed_ordersinteger已处理订单数
data.succeeded_ordersinteger成功数
data.failed_ordersinteger失败数
data.created_atdatetime创建时间
data.updated_atdatetime更新时间
data.started_atdatetime / null开始时间
data.finished_atdatetime / null结束时间
data.user_idinteger任务创建者账号 ID
GET/api/v1/recipient-decrypt-jobs

批量任务列表

请求参数

字段类型说明
pageinteger页码,默认 1
page_sizeinteger每页 10、20、50 或 100 条

查询参数 page、page_size。任务行包含 total_orders、processed_orders、succeeded_orders、failed_orders、status 及时间字段。

GET /api/v1/recipient-decrypt-jobs
返回字段说明
字段类型说明
okboolean请求成功为 true
data.rowsarray当前页记录
data.totalinteger符合条件的记录总数
data.pageinteger当前页码
data.page_sizeinteger每页条数
data.rows[].idinteger任务 ID
data.rows[].statusstringqueued、running、completed 或 cancelled
data.rows[].total_ordersinteger订单总数
data.rows[].processed_ordersinteger已处理订单数
data.rows[].succeeded_ordersinteger成功数
data.rows[].failed_ordersinteger失败数
data.rows[].created_atdatetime创建时间
data.rows[].updated_atdatetime更新时间
data.rows[].started_atdatetime / null开始时间
data.rows[].finished_atdatetime / null结束时间
GET/api/v1/recipient-decrypt-jobs/:id/results

任务结果预览

请求参数

字段类型说明
idinteger路径参数,批量任务 ID
pageinteger页码,固定每页 10 条

查询参数 page,固定每页 10 条。每行返回 order_no、name、phone、address、status、error_message。

GET /api/v1/recipient-decrypt-jobs/:id/results
返回字段说明
字段类型说明
okboolean请求成功为 true
data.rowsarray当前页记录
data.totalinteger符合条件的记录总数
data.pageinteger当前页码
data.page_sizeinteger每页条数
data.rows[].idinteger任务结果行 ID
data.rows[].order_nostring平台订单号
data.rows[].namestring收件人姓名
data.rows[].phonestring收件人手机号
data.rows[].addressstring收件地址
data.rows[].statusstringsuccess 或 failed
data.rows[].error_messagestring失败原因
GET/api/v1/recipient-decrypt-jobs/:id/download

下载任务结果

请求参数

字段类型说明
idinteger路径参数,批量任务 ID

返回 UTF-8 CSV,四列依次为 订单号、姓名、手机号、地址。

GET /api/v1/recipient-decrypt-jobs/:id/download
返回字段说明
字段类型说明
okboolean请求成功为 true
Content-Typestringtext/csv; charset=UTF-8
文件列CSV订单号、名字、手机号、地址
DELETE/api/v1/recipient-decrypt-jobs/:id

取消批量任务

请求参数

字段类型说明
idinteger路径参数,批量任务 ID

可取消排队或运行中的任务;已处理结果保留。

DELETE /api/v1/recipient-decrypt-jobs/:id
返回字段说明
字段类型说明
okboolean请求成功为 true
data.idinteger任务 ID
data.statusstring取消后为 cancelled

采购工作流

商品关联、锁单与前端结果回传
实际拼多多采购、取消与付款由前端采购端完成。后端保存关联、预览、锁、结果和审核状态;成功或失败只代表前端回传的结果,无法替代采购平台核验。金额单位均为分。新接口使用现有同源 Cookie 会话,运营账号只能处理授权店铺的订单。采购结果和付款结果需提交唯一 Idempotency-Key。

订单列表新增字段与筛选

GET /api/v1/orders 增加 view=purchase_records、purchase_order_no、purchase_account_id、order_nos(逗号或换行分隔)、purchased_from、purchased_to;还支持 provinces、item_field=item_id|sku_id + item_keyword、receiver_name(仅匹配脱敏姓名)、has_customer_remark、has_seller_remark、order_history、locked、multi_items、issue=ignored|has_cancel_record。link_status=linked|unlinked|link_only|sku_linked|sku_unlinked 按全部命中订单筛选。return_address_bound、same_address 暂无可靠数据,传入返回 422 FILTER_UNAVAILABLE。发货时限和售后退款状态也暂无字段。订单分页新增 200 条选项。行增加 purchase、purchase_status、link_status、locked_by、skip_reason、auto_stage、pay_status。待下单视图排除已跳过或结果待核对的订单。

GET/api/v1/items

商品关联列表

按当前账号可见店铺的订单商品 ID 汇总,支持分页及关联状态筛选。

请求参数

字段类型说明
shop_id / keywordinteger / string店铺 ID;商品标题或 ID
link_statusstringunlinked、link_only、sku_linked
page / page_sizeinteger页码;每页 10、20、50、100、200
GET /api/v1/items?link_status=unlinked&page=1&page_size=20
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.rows[]array商品行:item_id、title、image_url、shop_names、sale_price_cents、sku_count、linked_sku_count、link_status、suppliers、profit_min_cents、profit_max_cents、pending_orders
data.total / page / page_sizeinteger分页信息
GET/api/v1/items/:itemId/link

读取商品关联

返回本店规格、上家商品及规格映射。仅能读取授权店铺中出现过的商品。

请求参数

字段类型说明
itemIdstring路径参数,小红书商品 ID
GET /api/v1/items/123456/link
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.local_skusarray本店规格:sku_id、name、image_url、sale_price_cents
data.suppliersarray上家商品及规格快照
data.mappingsarray本店 SKU 到上家 SKU 的映射
POST/api/v1/supplier-items/parse

保存或读取上家商品快照

实际链接解析由采购端执行。只传 url 时读取已有快照;无缓存返回 422 SUPPLIER_METADATA_REQUIRED。提交解析结果后保存快照,不在后端访问第三方链接。

请求参数

字段类型说明
urlstring拼多多 HTTPS 商品链接
id / title / shop_namestring采购端解析出的商品 ID、标题、店铺名称;保存时必填 ID 和标题
image_url / shipping_fee_centsstring / integer图片 HTTPS URL、运费(分)
skusarray规格数组,每项 id、name、image_url、price_cents、stock
POST /api/v1/supplier-items/parse
{"url":"https://mobile.yangkeduo.com/goods.html?goods_id=123","id":"123","title":"示例商品","shop_name":"示例店","shipping_fee_cents":0,"skus":[{"id":"sku1","name":"默认规格","price_cents":1299}]}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.id / url / titlestring上家商品标识、链接和标题
data.skusarray上家规格快照
data.fetched_at / from_cachedatetime / boolean快照时间与是否读取缓存
PUT/api/v1/items/:itemId/link

保存商品关联

整体替换上家商品和 SKU 映射,最多 20 个上家、200 条映射;校验商品、规格及账号归属。

请求参数

字段类型说明
itemIdstring路径参数,小红书商品 ID
supplier_item_idsstring[]已保存的上家商品 ID
mappingsarray每项 local_sku_id、supplier_item_id、supplier_sku_id、quantity、note
PUT /api/v1/items/123456/link
{"supplier_item_ids":["123"],"mappings":[{"local_sku_id":"skuA","supplier_item_id":"123","supplier_sku_id":"sku1","quantity":1,"note":""}]}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.item_idstring本店商品 ID
data.suppliers / mappingsarray更新后的关联
GET/api/v1/purchase-accounts

采购账号名称列表

只保存和返回账号显示名称,不接收采购平台密码、Cookie 或令牌。

请求参数

字段类型说明
无—无需请求体
GET /api/v1/purchase-accounts
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data[]array账号 id、name
POST/api/v1/purchase-accounts

登记采购账号名称

登记前端采购端使用的账号名称;请求体只允许 name。

请求参数

字段类型说明
namestring账号显示名称,最多 100 字符
POST /api/v1/purchase-accounts
{"name":"采购账号 A"}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.id / nameinteger / string账号 ID 和名称
GET/api/v1/settings/purchase

读取下单设置

设置按主账号保存。

请求参数

字段类型说明
无—无需请求体
GET /api/v1/settings/purchase
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.auto_purchase / lock_ordersboolean自动处理开关、锁单开关
data.warn_repeat_address / warn_address_keywordsboolean提示开关
data.address_keywordsstring[]地址关键字
PUT/api/v1/settings/purchase

修改下单设置

只更新提交的字段;自动采购由前端执行。

请求参数

字段类型说明
auto_purchase / lock_ordersboolean开关
warn_repeat_address / warn_address_keywordsboolean提醒开关
address_keywordsstring[]最多 50 个,每个最多 50 字
PUT /api/v1/settings/purchase
{"auto_purchase":false,"lock_orders":true}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
dataobject完整的更新后设置
GET/api/v1/settings/software-remark

读取软件备注设置

设置按主账号保存。

请求参数

字段类型说明
无—无需请求体
GET /api/v1/settings/software-remark
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.fieldsstring[]备注组成字段
data.flag_colorinteger / null成功后的旗帜颜色;null 为不修改
PUT/api/v1/settings/software-remark

修改软件备注设置

fields 可选 platform、account、order_no、amount、profit、profit_rate、supplier_shop。

请求参数

字段类型说明
fieldsstring[]备注组成字段
flag_colorinteger / null1–6 或 null
PUT /api/v1/settings/software-remark
{"fields":["account","order_no"],"flag_color":1}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.fields / flag_colorarray / integer更新后的设置
POST/api/v1/orders/:id/purchase/prepare

准备采购并锁单

校验待下单状态与规格映射,锁单 15 分钟;采购结果未知时保持锁定直到人工核对。其他操作员持有锁时返回 409 ORDER_LOCKED;映射不完整返回 422 LINK_REQUIRED。

请求参数

字段类型说明
idinteger路径参数,本地订单 ID
POST /api/v1/orders/123/purchase/prepare
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.linesarray采购规格、数量、单价和小计(分)
data.total_cents / profit_centsinteger / null采购总价与预计利润
data.accountsarray采购账号名称列表
data.warningsarray风险提示;当前为空数组
DELETE/api/v1/orders/:id/lock

释放采购锁

仅持锁操作员或锁过期后可释放;采购结果未知时须先人工核对。

请求参数

字段类型说明
idinteger本地订单 ID
DELETE /api/v1/orders/123/lock
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.lockedboolean释放后为 false
POST/api/v1/orders/:id/purchase

回传采购结果

前端完成实际采购后回传结果。必须先准备并锁单;此接口不向拼多多发单。结果未知时不得直接重试,须人工核对。请求头须有 Idempotency-Key。

请求参数

字段类型说明
Idempotency-Keyheader8–120 位唯一请求键,重试使用原键
purchase_account_idinteger已登记账号 ID
statusstringsuccess、failed、unknown
purchase_order_nostring成功时必填
amount_centsinteger / null实际采购金额,单位分
reason / autostring / boolean失败或未知原因;自动采购标识
POST /api/v1/orders/123/purchase
Idempotency-Key: purchase-123-001
{"purchase_account_id":1,"status":"success","purchase_order_no":"PD123","amount_cents":1299,"auto":false}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.statusstring结果状态
data.purchase_order_no / amount_centsstring / integer回传的采购单号和金额
data.account_name / reasonstring账号名称与说明
POST/api/v1/orders/:id/purchase/cancel

回传取消采购结果

前端先在采购端取消,再回传结果;仅成功时清空订单采购单号并保留历史事件。

请求参数

字段类型说明
Idempotency-Keyheader唯一请求键
statusstringsuccess、failed、unknown
reasonstring失败或未知原因
POST /api/v1/orders/123/purchase/cancel
Idempotency-Key: cancel-123-001
{"status":"success","reason":""}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.status / reasonstring取消结果与说明
POST/api/v1/orders/:id/skip

跳过待下单订单

保存跳过原因,待下单列表排除已跳过订单。

请求参数

字段类型说明
reasonstringsold_out、package_mismatch、price_too_high、other
notestring补充说明,最多 500 字
POST /api/v1/orders/123/skip
{"reason":"sold_out","note":""}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.skip_reason / skip_notestring保存后的原因与说明
PUT/api/v1/orders/:id/remarks

修改订单备注

店铺备注及旗帜调用开放平台;软件备注保存本地数据库。请求必须带 shop_id。

请求参数

字段类型说明
shop_idinteger订单所属店铺 ID
shop_remark / flag_colorstring / integer平台备注和 1–6 旗帜
software_remarkstring本地软件备注
PUT /api/v1/orders/123/remarks
{"shop_id":12,"software_remark":"已核对"}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.seller_remark / seller_remark_flagstring / integer已保存的平台备注及旗帜
data.software_remarkstring已保存的软件备注
GET/api/v1/auto-purchase/status

自动采购状态

查询是否开启和上次前端触发时间。

请求参数

字段类型说明
无—无需请求体
GET /api/v1/auto-purchase/status
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.enabledboolean自动采购设置
data.last_run_atdatetime / null上次触发时间
POST/api/v1/auto-purchase/run

领取自动采购候选订单

返回最多 100 个待下单订单 ID 给前端处理。后端不执行采购,purchased、failed、unknown 在此响应中均为 0。

请求参数

字段类型说明
无—无需请求体
POST /api/v1/auto-purchase/run
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.candidate_order_idsinteger[]候选订单 ID
data.last_run_atdatetime触发时间
GET/api/v1/auto-purchases

自动采购记录

按 review、approved、exception 阶段分页。仅展示当前账号可操作店铺。

请求参数

字段类型说明
stagestringreview、approved、exception
page / page_sizeinteger页码和每页条数
GET /api/v1/auto-purchases?stage=review&page=1
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.rowsarray订单、销售金额、采购结果及付款状态
data.total / page / page_sizeinteger分页信息
POST/api/v1/auto-purchases/review

审核自动采购

approve 转为待付款。reject 需先由前端在采购端取消并调用取消回传接口,否则逐单返回 EXTERNAL_CANCEL_REQUIRED。

请求参数

字段类型说明
order_idsinteger[]最多 100 个本地订单 ID
decisionstringapprove 或 reject
POST /api/v1/auto-purchases/review
{"order_ids":[123],"decision":"approve"}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data[]array每单 order_id、ok、message、code
POST/api/v1/auto-purchases/:id/pay

回传付款结果

前端完成实际付款后回传;未知结果待人工核对,不自动重复支付。必须带 Idempotency-Key。

请求参数

字段类型说明
statusstringsuccess、failed、unknown
reasonstring失败或未知原因
POST /api/v1/auto-purchases/123/pay
Idempotency-Key: payment-123-001
{"status":"success"}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.status / reasonstring付款结果与说明
POST/api/v1/auto-purchases/:id/resolve

人工核对未知采购

确认采购端是否已生成订单;确认成功时需采购订单号。

请求参数

字段类型说明
placedboolean是否已下单
purchase_order_nostringplaced=true 时必填
POST /api/v1/auto-purchases/123/resolve
{"placed":true,"purchase_order_no":"PD123"}
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.statusstring核对后的状态
POST/api/v1/auto-purchases/:id/retry

重试失败订单

仅自动采购失败且人工确认未下单时可重新进入待处理。

请求参数

字段类型说明
无—无需请求体
POST /api/v1/auto-purchases/123/retry
返回字段说明
字段类型说明
okboolean成功为 true;失败为 false
dataobject / array成功响应数据
data.statusstringready

错误与约定

前端统一处理建议

HTTP 状态

状态含义建议
400 / 415JSON 格式或 Content-Type 错误修正请求体与请求头
401未登录或凭据错误重新建立会话
403无权操作或店铺服务不可用提示用户检查店铺状态
404资源不存在或不属于当前账号刷新列表后重试
409重复任务或当前状态冲突展示后端 message,避免重复提交
422字段校验失败将 message 显示在对应表单附近
429请求频繁或收件信息受平台额度限制查看 code:RATE_LIMITED 可稍后重试;RECIPIENT_LIMITED 需联系管理员核对平台额度
502 / 503依赖服务暂不可用保留用户输入,提供重试操作

平台回调

以下接口由小红书平台调用;常规业务前端无需主动调用。

POST/push

订单通知推送

请求参数

字段类型说明
app-keystring平台应用标识请求头
timestampstring平台签名时间戳请求头
signstring平台签名请求头
消息体JSON array订单状态通知列表或平台包装对象

接收平台订单状态消息并加入后台处理队列。接口独立于 /api/v1 前缀;平台按约定传入签名请求头和消息列表。

POST /push
Content-Type: application/json
返回字段说明
字段类型说明
successboolean是否接收成功
error_codeinteger0 为成功;400、401、500 为失败码
error_msgstring失败原因,成功时为空字符串
GET/api/v1/xhs/oauth/callback

店铺授权回调

请求参数

字段类型说明
codestring平台授权码
statestring授权流程中的一次性状态值

平台授权后携带 code 与 state 跳转到此地址。服务端完成令牌交换后重定向到授权发起页(首页或 /h5/);前端无需直接请求。

GET /api/v1/xhs/oauth/callback
返回字段说明
字段类型说明
HTTP 302string浏览器跳转到授权发起页,查询参数 shop_auth 和 shop_sync 表示结果
空参数响应string无回调参数时返回 JSON ok 与 message,用于连通性检查