API 文档

调用约定

• GET 查询接口携带 X-App-Id 和 X-Api-Key；API Key 只允许保存在商户服务端。
• POST 写接口不发送 X-Api-Key，改用 X-Api-Timestamp、X-Api-Nonce 和 X-Api-Signature。
• 写请求时间戳与服务器时间最多相差 300 秒；nonce 每次必须重新生成，重复 nonce 返回 HTTP 409。
• 商户余额统一使用 USD；balanceCents、priceCents 和 chargedAmountCents 均以 0.01 USD 为单位。
• 余额低于 10.00 USD 时，以上全部 7 个接口均返回 HTTP 402，包括余额查询接口。
• USD 商品直接按美元分扣款；其他币种按后台最新汇率换算一次到 USD，并在数据库事务中原子扣款。
• externalOrderNo 在同一 App ID 下必须唯一；相同编号仅允许重试完全相同的商品、规格和数量，否则返回 409。
• 请求和响应均使用 UTF-8 JSON；POST 请求需设置 Content-Type: application/json。
• 创建订单限制为每分钟最多 30 次；商品价格、库存、汇率和扣款金额以后端结果为准。
• 服务端请求失败时返回 error.code 和 error.message，请按 HTTP 状态码处理。

GET 查询认证

X-App-Id: app_0123456789abcdef0123456789abcdef
X-Api-Key: key_your_api_key

POST 写请求签名

使用 API Key 对规范字符串执行 HMAC-SHA256。正文先按对象键递归排序并压缩为 JSON， 再计算 SHA-256；签名格式为 sha256=<64 位小写十六进制>。

FAORBIT-HMAC-V1
<Unix 秒级时间戳>
<nonce>
POST
/v1/merchant/orders
<规范 JSON 正文的 SHA-256>

X-App-Id: app_0123456789abcdef0123456789abcdef
X-Api-Timestamp: 1786172400
X-Api-Nonce: 0123456789abcdef0123456789abcdef
X-Api-Signature: sha256=<HMAC-SHA256 结果>
Content-Type: application/json

Node.js 完整签名示例

import { createHash, createHmac, randomBytes } from "node:crypto";

const appId = process.env.FAORBIT_APP_ID;
const apiKey = process.env.FAORBIT_API_KEY;
const baseUrl = "https://mailaohao.com";
const path = "/v1/merchant/orders";
const body = {
  externalOrderNo: "merchant-order-1001",
  productId: "22222222-2222-4222-8222-222222222222",
  variantId: "33333333-3333-4333-8333-333333333333",
  quantity: 1
};

function stableJson(value) {
  if (value === null || typeof value !== "object") return JSON.stringify(value);
  if (Array.isArray(value)) return "[" + value.map(stableJson).join(",") + "]";
  return "{" + Object.keys(value).sort().map(
    (key) => JSON.stringify(key) + ":" + stableJson(value[key])
  ).join(",") + "}";
}

const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = randomBytes(16).toString("base64url");
const bodyHash = createHash("sha256").update(stableJson(body)).digest("hex");
const canonical = [
  "FAORBIT-HMAC-V1", timestamp, nonce, "POST", path, bodyHash
].join("\n");
const signature = "sha256=" + createHmac("sha256", apiKey)
  .update(canonical)
  .digest("hex");

const response = await fetch(baseUrl + path, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-App-Id": appId,
    "X-Api-Timestamp": timestamp,
    "X-Api-Nonce": nonce,
    "X-Api-Signature": signature
  },
  body: JSON.stringify(body)
});

Key 轮换与撤销

• 管理员在 API 管理页点击“轮换”，新 API Key 只展示一次。
• 可设置 0–10080 分钟旧 Key 宽限期；填 0 表示旧 Key 立即失效。
• 停用凭证会立即撤销该 App ID 下的新旧 Key，全部接口返回 HTTP 401。
• 尚未轮换的旧凭证暂时兼容原 POST 认证；轮换后请在宽限期结束前切换到 HMAC。

签名错误

• MERCHANT_API_SIGNATURE_REQUIRED：写请求缺少签名头。
• MERCHANT_API_SIGNATURE_EXPIRED：时间戳与服务器相差超过 300 秒。
• MERCHANT_API_SIGNATURE_INVALID：请求头格式错误、正文被修改或使用了错误的 Key。
• MERCHANT_API_REPLAY_DETECTED：nonce 已使用，必须生成新 nonce。

余额不足 10 USD

{
  "error": {
    "code": "MERCHANT_BALANCE_BELOW_ACCESS_MINIMUM",
    "message": "商户 USD 余额低于 10.00，暂时无法访问商户 API"
  }
}