Muvexa API 文档

授权店铺后，可以在在线控制台测试，也可以从后端调用同一个平台接口。Free 每个平台每天包含 20 次调用。

这份文档面向谁

这份文档面向通过 Muvexa API 连接电商系统的技术团队。

需要电商平台 API 能力的 SaaS、ERP、OMS、WMS 和内部技术团队。

为多个已授权店铺管理 API 接入的服务商与集成商。

希望先在浏览器里测试，再通过服务端 API 对接的开发者。

快速开始

授权店铺后，可以在在线控制台测试，也可以从后端调用同一个平台接口。Free 每个平台每天包含 20 次调用。

注册并授权店铺

创建 Muvexa 账号，进入控制台并生成店铺授权链接。授权完成后，Muvexa 会为该店铺签发一对凭证：API Key 与 API Secret。两者都在控制台的授权列表页，默认掩码，点眼睛图标展开或复制。

在 API Console 在线测试

测试阶段，直接在在线 API Console 发起电商平台请求，并查看状态、耗时和响应元数据。

http

POST https://openapi.muvexa.co/amazon/execute
Content-Type: application/json
X-Api-Key: <your-api-key>
X-Timestamp: 1723795200000
X-Nonce: 7b1f2d0c-5b52-4c74-a615-0d7e3cce8e9c
X-Signature: <hmac-sha256-hex>

{
  "method": "GET",
  "path": "/orders/v0/orders",
  "queryParams": {
    "MarketplaceIds": "ATVPDKIKX0DER",
    "CreatedAfter": "2026-08-01T00:00:00Z"
  }
}

连接你的后端系统

在后端使用店铺 API Key 调用对应的平台入口。Free 和 Pro 都支持 API 对接，套餐只影响调用额度。

平台接口地址

每个电商平台使用一个固定的 Muvexa 接口地址，不同平台保持相同的请求协议。

http

Muvexa API
POST https://openapi.muvexa.co/amazon/execute

Connected commerce platforms
Managed by Muvexa API

使用 Muvexa API 入口，并按已连接电商系统的要求填写 method、path、queryParams 与 body。

成功响应按字节原样透传，状态码也沿用电商平台的原值，Muvexa 不加任何自己的外壳。

一个店铺 API Key 唯一绑定平台、卖家与区域。调错平台入口会被拒绝；Amazon 参数由调用方按其文档填写。

请求签名

所有服务端到服务端请求都必须使用控制台展示的 API Secret 进行签名。X-Api-Key 明文传输；API Secret 永远不要放进请求里。

X-Api-Key 用于定位店铺授权关系和 token 映射。

X-Timestamp 使用当前毫秒级 Unix 时间戳。超出允许时间窗口的请求会被拒绝。

X-Nonce 在 nonce 有效期内必须唯一，用于防止重放请求。

X-Signature 是规范字符串的 HMAC-SHA256 十六进制结果，密钥使用 API Secret。

规范字符串

六段按此顺序用单个换行符连接。所有十六进制输出均为小写。

text

HTTP_METHOD          + "\n" +   // POST
REQUEST_PATH         + "\n" +   // /amazon/execute  (路径，不含域名与查询串)
QUERY_STRING         + "\n" +   // 网关侧查询串，通常为空行
SHA256_HEX(raw_body) + "\n" +   // 原始请求体字节的 SHA-256，小写十六进制
X_TIMESTAMP          + "\n" +   // 毫秒级 Unix 时间戳
X_NONCE                          // 本次请求唯一的随机串

X-Signature = HEX(HMAC_SHA256(stringToSign, apiSecret))

请求头

每次请求都要带齐这四个头。API Secret 只在本地参与签名计算，不会离开你的服务器。

http

POST https://openapi.muvexa.co/amazon/execute
Content-Type: application/json
X-Api-Key: <your-api-key>
X-Timestamp: 1723795200000
X-Nonce: 7b1f2d0c-5b52-4c74-a615-0d7e3cce8e9c
X-Signature: <hmac-sha256-hex>

常见错误

几乎所有 INVALID_SIGNATURE 都能归到下面四条之一。

请求体序列化了两次。签名覆盖的是实际发出去的那串字节，所以只序列化一次，然后签它、发它。key 顺序不同或多一个空格就会失败。

把完整 URL 拿去签名。REQUEST_PATH 只是路径，不含协议、域名和查询串。

重试时复用 timestamp 或 nonce。每次请求（含重试）都要重新生成两者，否则会得到 DUPLICATE_NONCE。

服务器时钟不准。X-Timestamp 是毫秒级，且必须落在允许的时间窗口内，保持 NTP 同步。

API 对接格式

Free 和 Pro 都支持 API 对接。请求需要携带 X-Api-Key 和签名头，再把目标电商平台请求发送到对应的平台入口。

method：原电商平台接口的 HTTP 方法，例如 GET、POST、PUT 或 DELETE。

path：原平台 API 路径，例如 /orders/v0/orders。

queryParams：发送到目标接口 URL ? 后面的查询参数，只放平台文档定义的 URL 参数。参数值按「已编码」处理，含空格、=、&、% 或 + 的值需自行百分号编码。

body：POST/PUT 等接口的 JSON 请求体，按平台文档原样填写；数组和嵌套对象放这里。没有请求体时可省略。queryParams 与 body 不能互换。

请求体

在这里描述你想调用的电商接口。queryParams 会进入 URL，body 会作为 JSON 请求体发送；两者都按已连接平台的文档填写，Muvexa 不会注入或改写业务字段。

json

{
  "method": "GET",
  "path": "/orders/v0/orders",
  "queryParams": {
    "MarketplaceIds": "ATVPDKIKX0DER",
    "CreatedAfter": "2026-08-01T00:00:00Z"
  }
}

POST 请求示例

创建报表这类接口要求把 reportType 和 marketplaceIds 放在 body 中，不能把它们改放到 queryParams。

json

{
  "method": "POST",
  "path": "/reports/2021-06-30/reports",
  "body": {
    "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
    "marketplaceIds": ["ATVPDKIKX0DER"]
  }
}

成功响应：原样透传

拿到的是已连接平台自己的响应体与原始状态码，Muvexa 保持响应契约透明。

json

{
  "payload": {
    "Orders": [
      {
        "OrderId": "902-0000000-0000000",
        "OrderStatus": "Shipped",
        "PurchaseDate": "2026-08-14T09:12:33Z",
        "OrderTotal": { "CurrencyCode": "USD", "Amount": "42.50" }
      }
    ],
    "NextToken": "MRjLDgAAAAA..."
  }
}

网关错误

只有 Muvexa 自身发出的拒绝才用这个外壳：参数不正确、凭证或签名无效、额度用尽。电商平台的错误一律原样透传，响应体就是平台自己的错误结构。

json

{
  "code": 429,
  "msg": "当日调用额度已用尽",
  "data": null
}

代码示例

同一个已签名请求的 Python、Java、TypeScript、Go 与 cURL 版本。每份示例都自包含，只用各语言标准库。

import hashlib, hmac, json, os, time, uuid
from urllib.parse import urlsplit
import requests

ENDPOINT = "https://openapi.muvexa.co/amazon/execute"
API_KEY = os.environ["MUVEXA_API_KEY"]
API_SECRET = os.environ["MUVEXA_API_SECRET"]

# 只序列化一次：下面签的和发的是同一串字节
payload = {
    "method": "GET",
    "path": "/orders/v0/orders",
    "queryParams": {"MarketplaceIds": "ATVPDKIKX0DER", "CreatedAfter": "2026-08-01T00:00:00Z"},
}
body = json.dumps(payload, separators=(",", ":")).encode("utf-8")

timestamp = str(int(time.time() * 1000))
nonce = str(uuid.uuid4())
string_to_sign = "\n".join([
    "POST",
    urlsplit(ENDPOINT).path,
    "",                                    # 查询串为空
    hashlib.sha256(body).hexdigest(),
    timestamp,
    nonce,
])
signature = hmac.new(
    API_SECRET.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256
).hexdigest()

res = requests.post(
    ENDPOINT,
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": API_KEY,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
        "X-Signature": signature,
    },
    data=body,          # 传 data=body，不要用 json=payload（会重新序列化）
    timeout=60,
)
print(res.status_code, res.text)

目前还没有 Muvexa SDK，这些示例都是直接走 HTTP 调用。API Key 与 API Secret 请从环境变量或密钥管理服务读取，不要提交进代码仓库。

签名错误码

401 响应体的 code 字段直接指明原因。其他状态码是电商平台的原始响应透传，不做改写。

错误码	含义
INVALID_API_KEY	API Key 不存在、已作废，或未配置 API Secret。
MISSING_SIGNATURE	X-Timestamp、X-Nonce、X-Signature 三者之一缺失或为空。
INVALID_TIMESTAMP	X-Timestamp 不是数字，或超出允许的时间窗口。先检查服务器时钟。
DUPLICATE_NONCE	该 X-Nonce 已在 nonce 有效期内被同一个 API Key 使用过。每次请求生成新的。
INVALID_SIGNATURE	签名不匹配。对照上面的规范字符串逐行核对。

隐私与数据

本平台不获取、不存储、不暴露任何买家个人身份信息（PII）。

调用历史仅记录元数据（方法、路径、状态码、耗时），绝不记录请求体或响应体。

涉及买家数据的受限接口不属于当前公开代理文档范围。

店铺 refresh token 加密存储；后台仅保存授权关系与调用统计，不含任何 PII。