Korsmet Partner API
欢迎使用 Korsmet 合作伙伴 API。本 API 提供产品目录查询和库存信息访问服务。
基础 URL
https://your-api-server.com/api/v1
功能列表
产品目录
分页浏览、筛选、搜索产品
库存查询
实时查询各仓库可用库存
分类 & 品牌
获取产品分类和品牌列表
认证
所有 API 请求需要通过 X-API-Key Header 携带有效的 API Key 进行认证。每个 Key 每天最多允许 2 个不同 IP 地址访问。
通过 HTTP Header 传递
curl -H "X-API-Key: kp_your_api_key_here" \
https://api.example.com/api/v1/products
IP 限制
每个 API Key 每天最多允许 2 个不同 IP 地址访问。超出限制后需等待次日重置。
获取产品列表
GET
/api/v1/products
分页获取产品列表，支持多种筛选和排序条件。
查询参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
page | number | 1 | 页码 |
limit | number | 20 | 每页条数 (最大 100) |
category | string | - | 按分类筛选，支持逗号分隔多选 |
brand | string | - | 按品牌筛选，支持逗号分隔多选 |
search | string | - | 搜索商品编号、条码或名称 |
barcode | string | - | 精确条码匹配（返回单个产品） |
is_active | 0 / 1 | - | 是否在售 |
country_of_origin | string | - | 产地筛选 (CA, KR, CN, JP 等) |
price_min | number | - | 最低价格 |
price_max | number | - | 最高价格 |
include_stock | boolean | false | 是否包含库存信息 |
sort_by | string | name | 排序字段：price, name, item_no |
sort_order | string | asc | 排序方向：asc, desc |
请求示例
curl -H "X-API-Key: kp_your_key" \
"https://api.example.com/api/v1/products?category=Skincare&brand=Laneige&include_stock=true&limit=10"
响应示例
{
"success": true,
"data": {
"products": [
{
"id": 42,
"item_no": "ITEM001",
"barcode": "8801234567890",
"name": "Laneige Water Sleeping Mask 70ml",
"description": "Overnight moisturizing mask",
"category": "Skincare",
"brand": "Laneige",
"country_of_origin": "KR",
"price": 38.00,
"uom": "EA",
"inner_qty": 6,
"outer_qty": 24,
"is_active": 1,
"total_available": 150,
"in_stock": true,
"warehouses": [
{ "warehouse_code": "TOR", "warehouse_name": "Toronto Warehouse", "available": 100, "in_stock": true },
{ "warehouse_code": "VAN", "warehouse_name": "Vancouver Warehouse", "available": 50, "in_stock": true }
]
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 256,
"total_pages": 26
}
}
}
获取产品详情
GET
/api/v1/products/:identifier
identifier 可以是产品 ID、商品编号 (item_no) 或条码 (barcode)。
查询参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
include_stock | boolean | false | 是否包含各仓库库存详情 |
请求示例
curl -H "X-API-Key: kp_your_key" \
"https://api.example.com/api/v1/products/ITEM001?include_stock=true"
响应示例
{
"success": true,
"data": {
"product": {
"id": 42,
"item_no": "ITEM001",
"barcode": "8801234567890",
"name": "Laneige Water Sleeping Mask 70ml",
"category": "Skincare",
"brand": "Laneige",
"price": 38.00,
"is_active": 1
},
"stock": {
"total_available": 150,
"in_stock": true,
"warehouses": [
{
"warehouse_code": "TOR",
"warehouse_name": "Toronto Warehouse",
"available": 100,
"in_stock": true
},
{
"warehouse_code": "VAN",
"warehouse_name": "Vancouver Warehouse",
"available": 50,
"in_stock": true
}
]
}
}
}
获取分类列表
GET
/api/v1/products/meta/categories
返回所有可用的产品分类及各分类下的产品数量。
响应示例
{
"success": true,
"data": [
{ "category": "Skincare", "product_count": 120 },
{ "category": "Makeup", "product_count": 85 },
{ "category": "Hair Care", "product_count": 45 }
]
}
获取品牌列表
GET
/api/v1/products/meta/brands
返回所有可用的品牌及各品牌下的产品数量。
响应示例
{
"success": true,
"data": [
{ "brand": "Innisfree", "product_count": 38 },
{ "brand": "Laneige", "product_count": 25 },
{ "brand": "Sulwhasoo", "product_count": 18 }
]
}
查询单品库存
GET
/api/v1/inventory/:itemNo
根据商品编号 (item_no) 查询各仓库的可用库存。
请求示例
curl -H "X-API-Key: kp_your_key" \
"https://api.example.com/api/v1/inventory/ITEM001"
响应示例
{
"success": true,
"data": {
"item_no": "ITEM001",
"barcode": "8801234567890",
"name": "Laneige Water Sleeping Mask 70ml",
"is_active": 1,
"stock_summary": {
"total_available": 150,
"in_stock": true
},
"warehouses": [
{
"warehouse_code": "TOR",
"warehouse_name": "Toronto Warehouse",
"available": 100,
"in_stock": true,
"last_updated": "2026-02-11T10:30:00.000Z"
}
]
}
}
获取仓库列表
GET
/api/v1/inventory/warehouses
返回所有活跃的仓库列表。
响应示例
{
"success": true,
"data": [
{ "code": "TOR", "name": "Toronto Warehouse", "is_active": 1 },
{ "code": "VAN", "name": "Vancouver Warehouse", "is_active": 1 }
]
}
API 测试
在下方直接测试 API 接口，查看实时响应结果。
选择接口
GET
产品列表
GET
产品详情
GET
分类列表
GET
品牌列表
GET
单品库存
GET
仓库列表
查询参数
响应
错误码
所有错误响应遵循统一格式：
{
"success": false,
"error": "错误类型",
"message": "错误详情描述"
}
| 状态码 | 说明 | 常见原因 |
|---|---|---|
200 | 成功 | - |
400 | 请求参数错误 | 缺少必填参数、参数格式不正确 |
401 | 未认证 | 缺少 API Key、Key 无效或已过期 |
403 | 权限不足 / IP 限制 | API Key 权限不够、IP 不在白名单、当日 IP 数超过 2 个 |
404 | 资源不存在 | 找不到指定的产品或接口路径 |
429 | 请求过于频繁 | 超出速率限制，请稍后重试 |
500 | 服务器内部错误 | 服务端异常，请联系技术支持 |
速率限制
为保证服务稳定性，API 对请求频率有限制。
默认限制
100 次 / 15 分钟
超出后等待
返回 429 状态码
速率限制信息在响应头中返回：
RateLimit-Limit: 100
RateLimit-Remaining: 95
RateLimit-Reset: 1707600000
如需提高速率限制，请联系 Korsmet 技术团队调整您的 API Key 配置。
© 2026 Korsmet. All rights reserved.