跨境云 API 说明
面向总部与授权供应商连接器。正式网站使用 HTTPS；令牌只授予指定供应商的库存读取与观察权限。
接口不会代替供应商登录、采购付款、客户店铺同步或自动下架。未知库存保持未知，核对失败不会写成零。
商品自动上品
POST /api/integrations/catalog/import，使用总部生成的 cloud_catalog_… 令牌，导入商品表格对应的 JSON。该令牌只允许上品。
库存连接
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/integrations/inventory/mappings | 读取该供应商已确认的商品与规格映射。 |
| POST | /api/integrations/inventory/preview | 预检一批真实库存观察，不写入数据库。 |
| POST | /api/integrations/inventory/snapshots | 再次校验并提交；批次号幂等。 |
请求头：Authorization: Bearer cloud_stock_…、Content-Type: application/json。请求主体必须含唯一 jobId 和 items；每项含 sourceSku、quantity、observedAt、evidence。数量使用非负整数；未知用 null；明确无货才用 0。
总部 OMS
管理员页面的接口前缀为 /api/admin/oms/，需要管理员会话、CSRF 和同源校验。它包含待办、商品库存、上架热度、供应商映射、核对预检、采购登记、通知重试和规则设置。
前台同步
GET /api/catalog 返回已发布商品。服务网页在切回窗口时刷新，页面可见时每 30 秒刷新；供应商来源映射、成本与令牌不会出现在公开结果中。
安全边界
- 库存令牌不能访问客户账户、订单、充值、支付或退款。
- 同一批次号提交不同内容会被拒绝，旧观察不能覆盖新观察。
- 正式连接器应保存原始证据，遇到验证码、登录失效或页面变化时停止并转人工核对。