メインコンテンツへスキップ

デベロッパー

マーチャントAPI

VeeBoostストアのための読み取り専用REST API:公開済みの単一契約、キーによる認証、予測可能なページネーション — 常に同期し続ける統合のために設計されています。

単一の契約、唯一の真実の情報源として公開

あなたのストアは完全な機械可読契約(OpenAPI 3.1)を公開します:マーチャントAPIのすべてのエンドポイント、パラメータ、レスポンス、エラーコード。このページはそれへのリンクであり、エンドポイント表を決して書き写しません — 契約はずれず、あなたの統合もそうあり続けます。

公開済みの契約GET /openapi/v1.json

クイックスタート

最初のカタログ読み取りまでの3ステップ:

  1. 管理画面(デベロッパー セクション)で、必要な読み取りスコープを持つAPIキーを作成します。vbk_ で始まり、一度だけ表示されます。
  2. すべてのリクエストで X-Api-Key ヘッダーにキーを乗せます — テナントはキーから解決され、ホストからは決して解決されません。
  3. 最初のエンドポイント(例: 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 の決定になります — 黙って計画されることはありません。