概览

SkuProfit 提供 API 供第三方系统随时调用,输入 SKU 基础数据,返回结构化的成本、毛利、毛利率、 保本价、目标售价与费用拆分。所有金额统一以 USD 输出;非 USD 输入通过实时汇率折算。

请求与响应均为 JSON。响应统一为 { success, data } 或 { success:false, error:{ code, message } }。

鉴权

所有 /api/v1 接口需要 API Key。在请求头携带:

Authorization: Bearer sk_live_xxxxxxxx # 或 X-API-Key: sk_live_xxxxxxxx

速率限制

按 API Key 独立限流,默认 120 次/分钟(可按接入方调整)。每个响应包含限流头:

X-RateLimit-Limit: 120 X-RateLimit-Remaining: 118 X-RateLimit-Reset: 1783112400   # 窗口重置的 Unix 秒

超限返回 429,并带 Retry-After(秒)。建议客户端读取上述头做退避重试。

接口:单 SKU 计算

请求字段

完整字段(头程、包材、清关、仓储、各项费用覆盖等)见 OpenAPI。传入 *_fee 覆盖字段时优先于系统费率。

请求示例

curl -X POST https://<YOUR_HOST>/api/v1/calculate \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "ABC-001",
    "platform": "amazon",
    "country": "US",
    "category": "home",
    "input_currency": "CNY",
    "sale_currency": "USD",
    "sale_price": 19.99,
    "product_cost": 36,
    "unit_weight_kg": 0.45,
    "unit_volume_cbm": 0.003,
    "shipping_method": "sea",
    "freight_pricing_mode": "fixed",
    "freight_fixed_price": 1.1
  }'

响应示例

{
  "success": true,
  "data": {
    "sku": "ABC-001",
    "platform": "amazon",
    "country": "US",
    "output_currency": "USD",
    "sale_price_usd": 19.99,
    "total_cost_usd": 16.77,
    "gross_profit_usd": 3.22,
    "gross_margin_rate": 0.1611,
    "break_even_price_usd": 15.32,
    "suggested_price_for_target_margin_usd": 27.10,
    "decision": "watch",
    "cost_detail": { "...": "各费用项 USD" },
    "rate_snapshot": { "...": "本次费率" },
    "exchange_rate_snapshot": { "...": "本次汇率" },
    "warnings": []
  }
}

响应关键字段

接口:批量计算

请求体 { "items": [ CalcInput, ... ] }。单条失败不影响其它:失败项返回 success:false 与错误码。

curl -X POST https://<YOUR_HOST>/api/v1/calculate/batch \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "items": [ { "platform": "amazon", "country": "US", ... }, { ... } ] }'

异步批量 + Webhook 回调

大批量或需要"算完推回总后台"的场景,用异步任务。提交后立即返回 job_id,计算在后台进行。

curl -X POST https://<YOUR_HOST>/api/v1/batch-jobs \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [ { "platform":"amazon","country":"US","category":"home",
                 "sale_price":19.99,"product_cost":36,"unit_weight_kg":0.45 } ],
    "callback_url": "https://your-backend/skuprofit/webhook"
  }'
# -> 202 { "job_id":"...", "status":"pending", "poll_url":"/api/v1/batch-jobs/..." }

轮询任务状态与结果:

{ "status":"completed", "total":1, "success_count":1, "failed_count":0,
  "callback_status":"delivered",
  "result": { "event":"batch.completed", "items":[ { "index":0, "success":true,
              "gross_margin_rate":0.22, "decision":"watch", ... } ] } }

回调(Webhook)与验签

若提交时带了 callback_url,任务完成后我们会 POST 结果到该地址,请求头包含:

X-SkuProfit-Event: batch.completed
X-SkuProfit-Timestamp: 1751622000
X-SkuProfit-Signature: sha256=<hmac>

验签(防伪造):用组织的 Webhook 签名密钥(在「API 与用量」页获取)计算

expected = "sha256=" + HMAC_SHA256(secret, timestamp + "." + rawBody)
// 与 X-SkuProfit-Signature 常量时间比较;并校验 timestamp 新鲜度(如 5 分钟内)

决策值

• pass — 毛利率 ≥ 目标毛利率,可进入下一步
• watch — 低于目标但 ≥ 最低毛利率(默认 15%),需优化
• fail — 低于最低毛利率,不建议上架
• invalid — 数据不足,无法判断

错误码

接入示例(Node.js)

const res = await fetch("https://<YOUR_HOST>/api/v1/calculate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SKUPROFIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    platform: "amazon", country: "US", category: "home",
    input_currency: "CNY", sale_currency: "USD",
    sale_price: 19.99, product_cost: 36, unit_weight_kg: 0.45,
    freight_pricing_mode: "fixed", freight_fixed_price: 1.1,
  }),
});
const { success, data, error } = await res.json();

安全与合规

• 传输走 HTTPS;API Key 置于服务端环境变量,切勿暴露在浏览器或仓库。
• 每次调用均记录审计日志(密钥、接口、IP、状态、耗时),用于风控与用量核对。
• 内部页面接口(/api/calculate 等)仅限本站同源调用;第三方一律使用 /api/v1。
• 需要轮换或吊销密钥,联系我方即时处理。