NinjabuyのロゴBusiness
営業に問い合わせる
開発者2026-11プレビュー

NinjaBuy Business API

Taobao、Weidian、1688から商品をインポートし、価格と在庫を同期し、中国の出品者から倉庫での検品を経てお客様の玄関まで、すべての注文を追跡します。HTTPS経由のJSON、1つのアカウント、1つの残高。

ベースURL

このサイトのすべてのルートは1つのベースURLの下にあります。Shopifyアプリもあなたが作るものも同じルートを呼び出すので、アプリにできることはあなたのコードでもできます。

https://www.ninjabuy.com/api/v1

AIアシスタントに聞きたいですか？同じアカウントがMCPのhttps://www.ninjabuy.com/mcpで使えます：AIアシスタント（MCP）。

カタログ
注文
アカウント
最初の呼び出し
curl "https://www.ninjabuy.com/api/v1/balance" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

認証

すべてのリクエストでAPIキーをbearerトークンとして送ってください。キーはnb_で始まります。プレビュー期間中は当社チームが発行します。Businessアカウントの設定が済んだら、ご希望のスコープ付きで、ご指定の経路で各キーを一度だけお送りします。取り消しをご依頼いただくと、次のリクエストから無効になります。

キーはサーバーに保管してください。ブラウザ、アプリ、公開リポジトリにあるキーは誰でも読めて、残高を使われてしまいます。

他のNinjaBuyセラーの代わりに動作するアプリはOAuth 2.1を使います：動的クライアント登録、PKCE（S256）付き認可コードフロー、そしてセラー自身の承認画面。アクセストークンは同じヘッダーに入れ、同じルートで使えます。アクセストークンは1時間有効で、リフレッシュトークンで7日間更新できます。AIアシスタントも同じ方法で接続します（MCP）。

products:readスコープ
インポート、商品、バリエーション、同期ルールの読み取り。
products:writeスコープ
商品のインポート、編集、送信、削除。同期ルールの変更。
inventory:readスコープ
在庫数の読み取り。
orders:readスコープ
注文、フルフィルメント注文、発送の読み取り。
orders:writeスコープ
注文の作成、保留、解除、キャンセル。残高を使います。
balance:readスコープ
残高とその取引の読み取り。
webhooks:writeスコープ
Webhookエンドポイントを管理します。

キーのスコープ外の呼び出しは403 insufficient-scopeを返し、必要なスコープを示します。

ヘッダー
Authorization: Bearer nb_7Qk2...vX9e
Response 401
HTTP/2 401

{
  "type": "https://www.ninjabuy.com/api/v1/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The API key is missing, wrong, expired or revoked.",
  "request_id": "req_7Hq2Lw9c"
}

バージョン管理

パスにはメジャーバージョン/v1が入ります。その中で、日付付きのバージョンがフィールドや動作を変更します。開発に使ったバージョンはNinjaBuy-Versionヘッダーで固定してください。すべての応答は使用したバージョンを同じヘッダーで示します。

2026-11が現行バージョンで、プレビュー版です。安定版になるまで名前やフィールドが変わる可能性があります。すべての変更は変更履歴に記載し、互換性を壊す変更の前には全キー保有者にメールでお知らせします。

1つのバージョン内では追加のみ行います：新しいルート、新しい任意パラメータ、応答の新しいフィールド、新しいイベントタイプ。知らないフィールドは無視するようにクライアントを作ってください。

バージョンを固定
GET /api/v1/orders
NinjaBuy-Version: 2026-11

HTTP/2 200
NinjaBuy-Version: 2026-11

リクエストと応答

  • JSONはContent-Type: application/jsonで送ってください。応答はUTF-8のJSONです。エラーはapplication/problem+jsonです。
  • 金額は10進数の文字列と通貨を持つオブジェクトです：{ "amount": "264.20", "currency": "CNY" }。NinjaBuyの請求はCN¥、あなたの販売価格はストアの通貨です。
  • IDは種類を示すプレフィックス付きの文字列です（prd_、ord_、shp_）。中身に依存しないでください。
  • 日時はUTCのISO 8601です。国は2文字のISOコードです。
  • すべての応答にX-Request-Idヘッダーが付き、すべてのエラーには同じIDがrequest_idとして含まれます。お問い合わせの際はこれを記載してください。
金額、ID、日付
{
  "id": "ord_3n7q",
  "created_at": "2026-11-01T09:14:02Z",
  "total": { "amount": "264.20", "currency": "CNY" },
  "suggested_price": { "amount": "49.99", "currency": "USD" }
}

ページネーション

リストは新しい順にdata、has_more、cursorで返ります。has_moreが true の間は、そのカーソルを送り返して次のページを取得してください。カーソルは取得時と同じフィルターでのみ使えます。

limitinteger
1〜100。省略時は25。
cursorstring
前のページのカーソル。最初のページでは省略します。
curl "https://www.ninjabuy.com/api/v1/orders?limit=25&cursor=c_2v9kq" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "data": [
    { "id": "ord_3n7q", "status": "checked" },
    { "id": "ord_3n6z", "status": "shipped" }
  ],
  "has_more": true,
  "cursor": "c_1q4ea"
}

レート制限

制限はアカウント単位で、すべてのキー、OAuthトークン、MCP接続で共有されます。すべての応答はIETFのRateLimit-PolicyとRateLimitヘッダーで現在の状況を示します。拒否は429 rate-limitedで、Retry-Afterに秒数が入ります。

時間枠対象となるもの
"create-links";q=30;w=60マーケットプレイスから出品を読み取る呼び出し：インポートの作成や更新、商品の送信。1分あたり30回で、リンクAPIおよびMCPと共有です。
"default";q=120;w=60その他すべての呼び出し。1分あたり120回。
レスポンス 429
HTTP/2 429
Content-Type: application/problem+json
Retry-After: 12
RateLimit-Policy: "create-links";q=30;w=60
RateLimit: "create-links";r=0;t=12

{
  "type": "https://www.ninjabuy.com/api/v1/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Try again in 12 seconds.",
  "request_id": "req_7Hq2Lw9c"
}

冪等性

任意のPOSTにIdempotency-Key（印字可能なASCII文字1〜255文字。UUIDが最適）を付けると、タイムアウト後の再試行で2つ目の注文が作られることはありません。24時間は、同じルート・同じボディの同じキーに対して、最初の応答を1バイトも違わずにIdempotent-Replayed: true付きで返し、再実行も制限へのカウントもしません。

  • 同じキーでボディやルートが異なる場合：422 idempotency-key-reused。
  • 最初のリクエストがまだ実行中：409 idempotency-key-in-progress、Retry-After付き。
  • レート制限による拒否は応答ではありません。キーは使われないままなので、Retry-Afterの後に再試行すればリクエストが実行されます。

注文にはあなた自身のexternal_idも付きます。同じIDの2つ目の注文は、どのキーで送っても409 duplicate-orderで拒否されます。

再試行されたリクエスト
POST /api/v1/orders
Idempotency-Key: 4f0c2b4e-9d1a-4e0f-b0a8-5d1d3c7e2f61

HTTP/2 201
Idempotent-Replayed: true
X-Request-Id: req_7Hq2Lw9c

エラー

エラーはproblem JSON（RFC 9457）です：typeは分岐に使える固定URL、titleはその名前、detailはこのケースを表示可能な言葉で説明し、request_idで当社のログから探せます。検証に失敗したボディにはerrorsが加わり、それぞれにフィールドを指すJSON pointerが付きます。

ステータスタイプ時期
400bad-jsonボディがJSONではありません。
400bad-bodyフィールドが欠けているか誤っています。errors[]が該当箇所を示します。
400bad-idempotency-keyIdempotency-Keyが空、長すぎる、または印字可能なASCIIではありません。
401unauthorizedキーまたはトークンが欠けている、誤っている、期限切れ、または取り消されています。
403insufficient-scopeキーにルートが必要とするスコープがありません。
404not-foundこのアカウントにそのオブジェクトはありません。他のアカウントのIDも同じ応答になります。
405method-not-allowedルートは存在しますが、このメソッドでは使えません。Allow に使えるメソッドが記載されています。
409duplicate-orderこの external_id の注文が存在します。order がその注文を示します。
409idempotency-key-in-progressこのキーの最初のリクエストがまだ実行中です。
409invalid-stateそのオブジェクトは今その操作ができません。例えば、発送済みの注文のキャンセル。
415unsupported-media-typeボディが application/json ではありません。
422idempotency-key-reusedキーが別のリクエストに使われました。
422unprocessable有効なJSONですが処理できません：読み取れないリンク、売り切れのバリエーションなど。detail に内容が入ります。
429rate-limited時間枠内の呼び出しが多すぎます。Retry-After 秒待ってください。
500internal-error当社側の問題です。同じIdempotency-Keyで再試行してください。
503service-unavailable現在キーの確認またはストアへの接続ができません。Retry-After の後に再試行してください。
Response 400
HTTP/2 400

{
  "type": "https://www.ninjabuy.com/api/v1/problems/bad-body",
  "title": "Invalid request body",
  "status": 400,
  "detail": "1 field is invalid.",
  "request_id": "req_7Hq2Lw9c",
  "errors": [
    {
      "pointer": "/ship_to/country",
      "detail": "Must be a two-letter country code."
    }
  ]
}