hongben-server/modules/fmode-tikhub-server/docs/fmode-amazon-sp-api

@fmode/amazon-sp-api

Amazon Selling Partner API (SP-API) 集成模块，支持多店铺动态配置（基于 Parse Server）。

功能特性

• 多店铺支持：基于 Shop 表（Parse Server）动态获取 SP-API 配置。
• 动态路由：请求头携带 shopId 和 marketplaceId，自动路由到正确的 API 端点和店铺配置。
• Token 管理：自动处理 LWA Token 的获取、缓存（数据库持久化）和刷新。
• 完整接口覆盖：包括 Orders, Listings, Reports, Notifications, Catalog, Sales, Inventory, Pricing, ExternalFulfillment, CustomerFeedback。
• 企业级特性：请求重试（429 处理）、日志记录、类型安全。

安装

npm install @fmode/amazon-sp-api

初始化

在应用启动时，初始化 Parse 配置：

import express from 'express';
import { createSpApiRouter, initParse } from '@fmode/amazon-sp-api';

const app = express();

// 1. 初始化 Parse (连接到配置中心)
initParse({
  appId: 'msq-voc', // 或从环境变量读取
  serverURL: 'https://server-msq.fmode.cn/parse',
  // masterKey: 'YOUR_MASTER_KEY' // 如果需要 Server-to-Server 权限
});

// 2. 挂载 SP-API 路由
// 注意：不再需要传入静态 client，模块会自动处理动态配置
app.use('/api/amazon', createSpApiRouter());

app.listen(3000, () => {
  console.log('Server started on port 3000');
});

请求示例

前端或调用方需要在 Header 中携带 shopId 和 marketplaceId。

获取订单列表

GET /api/amazon/orders?CreatedAfter=2023-10-01T00:00:00Z
Headers:
  shopId: <PARSE_SHOP_OBJECT_ID>
  marketplaceId: ATVPDKIKX0DER

响应格式

{
  "success": true,
  "data": {
    "payload": {
      "Orders": [...]
    }
  },
  "timestamp": "2023-10-27T10:00:00.000Z"
}

数据库配置 (Parse Shop 表)

在 Parse Dashboard 中，Shop 表需要包含以下字段：

| Field | Type | Description | |Data Type| Field Name | Description | |---|---|---| | Object | config | 包含 SP-API 凭证: { "clientId": "...", "clientSecret": "...", "refreshToken": "..." } | | String | sp_api_access_token | (自动维护) 当前有效的 Access Token | | Date | sp_api_token_expires_at | (自动维护) Token 过期时间 |

错误处理

• 400 Bad Request: 缺少 shopId 头，或 shopId 无效，或 Shop 配置不完整。
• 429 Too Many Requests: 模块会自动重试（指数退避），如果重试多次仍失败，返回错误。
• 500 Internal Server Error: 服务器内部错误或 SP-API 异常。