デベロッパー
マーチャントAPI
VeeBoostストアのための読み取り専用REST API:公開済みの単一契約、キーによる認証、予測可能なページネーション — 常に同期し続ける統合のために設計されています。
単一の契約、唯一の真実の情報源として公開
あなたのストアは完全な機械可読契約(OpenAPI 3.1)を公開します:マーチャントAPIのすべてのエンドポイント、パラメータ、レスポンス、エラーコード。このページはそれへのリンクであり、エンドポイント表を決して書き写しません — 契約はずれず、あなたの統合もそうあり続けます。
GET /openapi/v1.jsonクイックスタート
最初のカタログ読み取りまでの3ステップ:
- 管理画面(デベロッパー セクション)で、必要な読み取りスコープを持つAPIキーを作成します。vbk_ で始まり、一度だけ表示されます。
- すべてのリクエストで X-Api-Key ヘッダーにキーを乗せます — テナントはキーから解決され、ホストからは決して解決されません。
- 最初のエンドポイント(例: GET /products)を呼び出し、あとは契約に従います。
認証
すべてのリクエストは X-Api-Key ヘッダーでキーを運びます。v1 はちょうど4つの読み取りスコープを提供します — 商品、注文、顧客、Webhook配信。不足スコープは403で応答し、失効キーは即座に拒否されます。キーはサーバー側に保管してください:ブラウザや公開リポジトリに置くものではありません。
products:readorders:readcustomers:readwebhooks:readページネーション
リスト系エンドポイントはページネーションを行います:page パラメータで辿り、各コレクションに付いてくるエンベロープを読みます — 現在地がわかるため、統合は推測なしで再同期できます。各エンドポイントの正確なパラメータは契約に記載されています。
エラーとレート制限
エラーは解析可能な構造化JSON本体を返します。決してこすり取るための段落ではありません。429レスポンスは安定した契約です:毎回同じ本体の形、X-RateLimit-* ヘッダーと、いつ戻るかを正確に示す Retry-After。押し込んでもデータは解放されません — バックオフしてください。
サンドボックスキー
ローンチ前の間、サンドボックスキーは当チームの検証後に発行され、本番キーとは別の専用レート制限予算で動きます — 実トラフィックやクォータに触れずに、自分のストアでAPIを試せます。
言語別の例
プラットフォームごとに1つのスニペット、読み取りスコープのみ:どれも商品カタログを取得します。<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 の決定になります — 黙って計画されることはありません。