开发者
商户 API
面向 VeeBoost 商店的只读 REST API:一份已发布的契约、基于密钥的认证和可预期的分页,为始终保持同步的集成而设计。
一份契约,作为唯一事实来源发布
您的商店发布完整的机器可读契约(OpenAPI 3.1):商户 API 的每个端点、参数、响应和错误码。本页面只链接该契约,从不复述端点表 — 契约不会漂移,您的集成也不会。
已发布的契约
GET /openapi/v1.json快速开始
三步完成您的首次目录读取:
- 在管理后台(开发者版块)创建一个带有所需读取权限的 API 密钥。它以 vbk_ 开头,仅显示一次。
- 在每个请求的 X-Api-Key 头中发送它 — 租户由密钥解析,绝不来自主机。
- 调用您的第一个端点,例如 GET /products,之后一切以契约为准。
认证
每个请求都在 X-Api-Key 头中携带您的密钥。v1 仅提供四个读取权限 — 商品、订单、客户和 Webhook 投递。缺少权限返回 403;被吊销的密钥立即拒绝。请将密钥保存在服务器端:它们绝不应出现在浏览器或公开仓库中。
products:readorders:readcustomers:readwebhooks:read分页
列表端点均分页:使用 page 参数遍历,并读取每个集合返回的信封 — 它表明您所在的位置,让集成无需猜测即可重新同步。每个端点的确切参数在契约中记载。
错误与速率限制
错误返回结构化、可解析的 JSON 体,绝不需要靠抓取页面。429 响应是稳定契约:每次相同的体结构,附带 X-RateLimit-* 头和精确告知何时重试的 Retry-After。硬冲不会解锁数据 — 请退避。
沙盒密钥
在上线前阶段,沙盒密钥经我们团队审核后签发,并使用与生产密钥分开的专用限额预算 — 在您的商店上探索 API,不影响真实流量和配额。
按语言示例
每种平台一个代码片段,仅限读取权限:每个都拉取您的商品目录。将 <api-base> 替换为管理后台 → 开发者版块中显示的商店 API 主机。
curl
curl -H "X-Api-Key: vbk_your_key" \
"https://<api-base>/products?page=1"JavaScript
async function listProducts(page = 1) {
const res = await fetch("https://<api-base>/products?page=" + page, {
headers: { "X-Api-Key": "vbk_your_key" },
});
if (res.status === 429) {
// Structured contract: honor Retry-After, never screen-scrape.
const wait = Number(res.headers.get("Retry-After")) * 1000;
await new Promise((done) => setTimeout(done, wait));
return listProducts(page);
}
if (!res.ok) throw new Error("products:read failed with " + res.status);
return res.json();
}Python
import requests
def list_products(page=1):
res = requests.get(
"https://<api-base>/products",
params={"page": page},
headers={"X-Api-Key": "vbk_your_key"},
timeout=10,
)
res.raise_for_status()
return res.json()v1 在设计上只读:products:read、orders:read、customers:read 和 webhooks:read 是仅有的权限。写入权限必须是明确记录的 v1.x 决策 — 不会有任何悄悄新增的计划。