{"openapi":"3.1.0","info":{"title":"SkuProfit Pricing API","version":"1.0.0","description":"跨境选品成本与毛利计算 API。所有金额统一以 USD 输出。第三方通过 API Key 调用。"},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"在 Authorization 头携带 `Bearer <API_KEY>`；亦支持 `X-API-Key` 头。"}},"schemas":{"CalcInput":{"type":"object","required":["platform","country","category","sale_price","product_cost","unit_weight_kg"],"properties":{"sku":{"type":"string","example":"ABC-001"},"platform":{"type":"string","enum":["amazon","tiktok","temu","shein","mercadolibre"]},"country":{"type":"string","enum":["US","CA","AU","BR"]},"category":{"type":"string","example":"home"},"input_currency":{"type":"string","default":"USD","example":"CNY"},"sale_currency":{"type":"string","default":"USD","example":"USD"},"sale_price":{"type":"number","example":19.99,"description":"按 sale_currency 解释"},"product_cost":{"type":"number","example":36,"description":"按 input_currency 解释"},"unit_weight_kg":{"type":"number","example":0.45},"unit_volume_cbm":{"type":"number","example":0.003},"shipping_method":{"type":"string","enum":["sea","air"]},"freight_pricing_mode":{"type":"string","enum":["fixed","weight","volume","volume_weight_compare"]},"freight_fixed_price":{"type":"number","example":1.1},"tax_mode":{"type":"string","enum":["none","simple_preset","manual"]},"target_margin_rate":{"type":"number","default":0.3},"advertising_rate":{"type":"number","default":0.1},"return_reserve_rate":{"type":"number","default":0.03}}},"CalcResult":{"type":"object","properties":{"sku":{"type":"string"},"platform":{"type":"string"},"country":{"type":"string"},"output_currency":{"type":"string","example":"USD"},"sale_price_usd":{"type":"number"},"total_cost_usd":{"type":"number"},"gross_profit_usd":{"type":"number"},"gross_margin_rate":{"type":"number","example":0.2186},"break_even_price_usd":{"type":"number","nullable":true},"suggested_price_for_target_margin_usd":{"type":"number","nullable":true},"decision":{"type":"string","enum":["pass","watch","fail","invalid"]},"cost_detail":{"type":"object"},"rate_snapshot":{"type":"object"},"exchange_rate_snapshot":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"paths":{"/calculate":{"post":{"summary":"单 SKU 计算","operationId":"calculate","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalcInput"}}}},"responses":{"200":{"description":"计算成功","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CalcResult"}}}}}},"401":{"description":"缺少/无效 API Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"输入校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"超出速率限制","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/calculate/batch":{"post":{"summary":"批量计算（单条失败不影响其它）","operationId":"calculateBatch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CalcInput"}}}}}}},"responses":{"200":{"description":"批量结果"},"401":{"description":"缺少/无效 API Key"},"429":{"description":"超出速率限制"}}}}}}