リンク
リクエストフィールド、リンクごとの結果、再リクエストについて。
リンクの作成
POST https://www.ninjabuy.com/api/v1/linksにはBearerトークンとContent-Type: application/jsonが必要です。
| フィールド | ルール |
|---|---|
links | 必須。1〜2,000個の文字列の配列です。各入力の前後の空白は除去され、長さは1〜4,096文字である必要があります。 |
campaign | 任意。小文字、数字、ハイフンで構成する3〜64文字で、先頭は文字または数字です：^[a-z0-9][a-z0-9-]{2,63}$。訪問時にutm_campaignとして引き継がれます。 |
label | リンク一覧に表示する任意の名前。前後の空白を除去した後で1〜40文字の表示可能な文字とし、制御文字は使用できません。空白の除去が発生すると警告が返ります。 |
async | 任意の真偽値。trueの場合は常にバックグラウンドジョブを開始します。 |
Taobao、Tmall、Weidian、1688の商品リンク、対応する購入代行サービスのリンクと短縮リンク、WeidianとTaobaoのショップ（対応する購入代行サービスのショップページを含む）、対応する公開NinjaBuyページを変換できます。NinjaBuyのURL、または/search?q=hoodieのようなパスだけの入力も受け付けます。既存のNinjaBuy紹介リンクを貼り付けると、そのリンク先に対して自分の紹介実績が記録されるリンクを作成します。
即時処理と一括処理
入力が100件以下でasync: trueを指定しない場合、results、warnings、request_idを含む200が返ります。100件を超える場合、またはasync: trueの場合は、ジョブ、Location、Retry-Afterを含む202が返ります。クイックスタートとジョブをご覧ください。
結果は重複した入力も含め、入力順を保持します。各行にはinputとstatusがあり、必要に応じてtarget、url、code、noteが含まれます。
| ステータス | 意味 |
|---|---|
ok | 変換済みです。urlは紹介実績が記録されるNinjaBuyリンクです。 |
unsupported | 入力は認識できましたが、非対応のマーケットプレイスや非公開NinjaBuyページなどのためリンクを作成できません。 |
unreadable | 使用可能なリンク先を読み取れませんでした。 |
sheet | Google SheetのURLです。このエンドポイントはシートの内容を変換しません。 |
シートの場合はシートAPIで内容をXLSXに変換するか、NinjaBuyに貼り付けてください。既存のNinjaBuy /spreadsheets/d/<sheet id>ページ自体には、紹介実績が記録されるリンクを作成できます。
再リクエストと紹介実績
同じアカウント、正規化されたリンク先、キャンペーン、ラベルでは、REST、MCP、一括処理のいずれで作成しても同じリンクが返ります。キャンペーンまたはラベルが異なる場合は別のリンクになります。Idempotency-Keyを指定せずに一括処理を再送すると新しいジョブが作成されます。リンクの再利用によってジョブ送信が重複排除されることはありません。
RESTで新規作成したリンクはcreatedVia: "api"を記録します。リンクを再利用した場合は元の作成元（api、mcp、share、redirect）を保持します。このフィールドはMCPのlist_linksとlinkの結果で取得でき、RESTの作成レスポンスには含まれません。実績の記録とレポートについては紹介をご覧ください。
Idempotency-Key
POST /api/v1/links、POST /api/v1/uploads、POST /api/v1/sheetsに任意のIdempotency-Keyを付けると、別のジョブを作成したりリンク作成枠を追加で消費したりせずにリクエストを再試行できます。実行したいリクエストごとに、1〜255文字の表示可能なASCII文字からなる一意のキーを使用してください。
Idempotency-Key: partner-batch-2026-10-23-00124時間は、同じアカウント、キー、検証済みリクエストで、元のステータス、バイト単位で同一の本文、元のrequest_idを含むヘッダーがIdempotent-Replayed: trueとともに再返却されます。JSONオブジェクトのキーの順序は問いません。24時間後にはキーを再利用できます。
- 同じキーで別の本文またはPOSTルートを送ると
422（idempotency-key-reused）を返します。新しいキーを使用してください。 - 最初のリクエストの実行中は、再試行に
Retry-After付きの409（idempotency-key-in-progress）を返します。待ってから再試行してください。 - 無効なキーは
400（bad-idempotency-key）を返します。無効な本文でキーが予約されることはありません。 - 実行開始後は、エラーを含め最初の応答を保存します。
429は保存しません。Retry-Afterの後に同じキーで再試行してください。
クラッシュしたリクエストは、キーの期限切れまで実行中の状態が続く場合があります。このリクエストの再返却は、上記の一致するリンクの再利用とは別の機能です。