はじめての注文 — 15分で、日本の仕入れ先の在庫から発注するまで

このチュートリアルでは、orosy バイヤーAPI を使って 商品を探し、カートに入れ、テスト注文を作り、確保確定まで進める 一連の流れを体験します。

所要時間: 約 15 分（コピペしていくだけなら 5 分以内）
必要なもの: API キーだけ。バイヤーポータルでサインアップ → 審査承認（通常すぐ）→ ポータルからキーを発行できます
費用: かかりません。demo キーの注文はテスト専用で、実際の課金・在庫の変動は一切起きません
クレジットカードの登録も不要です。 OAuth の設定や SDK のインストールも不要。curl が動けば始められます

事業責任者の方へ: コードなしで全体像を知りたい方には、サービス紹介資料をご用意しています。wholesale_shop_api@orosy.com までご連絡ください。

Step 0. 疎通確認（30秒）

まず API に届くことを確認します。このエンドポイントだけは認証不要です。

curl https://wholesale-api.orosy.com/v1/health

{"status":"ok","stage":"prod","time":"2026-08-10T15:00:30.962Z"}

status: ok が返れば準備完了です。

Step 1. 商品を探す（3分）

複数の仕入れ先、約 20 万点の商品を 1 つのクエリで横断検索します。キーワードのほか、価格帯（min_price / max_price）・在庫（min_stock）・カテゴリでも絞り込めます。

curl -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
  "https://wholesale-api.orosy.com/v1/products?q=マグカップ&per_page=2"

{
  "total": 128,
  "items": [
    {
      "product_id": "de300001-0000-4000-8000-000000000001",
      "title": "デモ用マグカップ 350ml（サンプル商品）",
      "brand": "",
      "delivery_group": "demo-warehouse",
      "min_buyer_price": 800,
      "min_retail_price": 1200,
      "variation_count": 1,
      "images": ["https://wholesale-media.orosy.com/img/…"]
    },
    …
  ]
}

「マグカップ」だけで 128 件。buyer_price（卸価格）と retail_price（参考上代）が両方返るので、粗利を見ながら選べます。

次に商品詳細を取り、注文に使う variation_id（色・サイズ単位の ID）を控えます:

curl -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
  "https://wholesale-api.orosy.com/v1/products/de300001-0000-4000-8000-000000000001"

{
  "title": "デモ用マグカップ 350ml（サンプル商品）",
  "variations": [
    {
      "variation_id": "de300002-0000-4000-8000-000000000002",
      "jan": "4900000000001",
      "variant_label": "ホワイト 350ml（サンプル）",
      "buyer_price": 800,
      "retail_price": 1200,
      "order_unit": "1",
      "stock_level": "in_stock",
      "stock_observed_at": "2026-06-23 21:03:59+00"
    }
  ]
}

JAN・発注単位（order_unit）・在庫状態と観測時刻まで返ります。

Step 2. カートに入れる（2分）

仕入れ先が違う商品でも、カートは 1 つです。

curl -X PUT -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"variation_id": "de300002-0000-4000-8000-000000000002", "qty": 2}' \
  "https://wholesale-api.orosy.com/v1/cart/items"

GET /v1/cart で中身と見積を確認します:

curl -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
  "https://wholesale-api.orosy.com/v1/cart"

{
  "items": [ { "variation_id": "de3000…", "qty": 2, "buyer_price": 800, … } ],
  "groups": [
    {
      "group_code": "demo-warehouse",
      "subtotal": 1600,
      "supplier_fee": 800,
      "free_threshold": 10000,
      "messages": ["Add ¥8,400 more to this group for free supplier shipping (currently ¥800)."]
    }
  ],
  "estimate": {
    "subtotal_standard": 2400,
    "tax_standard": 240,
    "shipping_fee": 800,
    "total": 2640,
    "currency": "JPY"
  }
}

注文前に、送料・送料無料ライン・税（8%/10% 行単位）込みの合計がわかります。「あと ¥8,400 でこの仕入れ先の送料が無料」というメッセージまで返るので、そのまま画面に出せます。

Step 3. 注文を作る（3分）

配送先を指定して注文を確定します。demo キーの注文はテスト注文なので、安心して実行できます。

curl -X POST -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ship_to": {
      "postal_code": "530-0001",
      "state": "大阪府",
      "city": "大阪市北区",
      "line1": "梅田1-2-2",
      "recipient": "orosy テスト太郎",
      "phone": "06-0000-0000"
    },
    "note": "はじめてのテスト注文"
  }' \
  "https://wholesale-api.orosy.com/v1/orders"

HTTP 201
{
  "order_id": "de300003-0000-4000-8000-000000000003",
  "status": "pending_confirmation",
  "breakdown": { "total": 2640, "tax_standard": 240, "shipping_fee": 800, … },
  "payment": { "status": "requires_capture" },
  "items": [ { "item_no": 1, "qty": 2, "confirmed_qty": null, … } ]
}

知っておくと良いこと:

価格変動ガード: カートに入れた後で卸価格が変わっていた場合、API は 409 PRICE_CHANGED を返して勝手に確定しません。新価格で良ければ "accept_price_change": true を付けて再実行します（知らないうちに高い価格で買われない設計です）
二重注文の防止: リトライで同じ注文が 2 回作られるのを防ぐため、Idempotency-Key ヘッダの付与を推奨します。同じキーでの再送は最初の注文をそのまま返します（ヘッダなしでも、直近の同一カートの二重送信はサーバ側で自動排除されます）
注文直後の状態は pending_confirmation（在庫の確保待ち）。confirmed_qty はまだ null です

Step 4. 注文のその後を体験する（3分）

実際の運用では、注文後に orosy が仕入れ先へ買い付けを行い、注文は「確保確定 → 出荷 → 納品」と進みます。demo キーでは、この遷移をシミュレータで自分で再現できます。

# 全アイテムの確保が確定した状態にする
curl -X POST -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"action": "confirm_full"}' \
  "https://wholesale-api.orosy.com/v1/orders/de300003-…/simulate"

# 状態を確認する
curl -H "Authorization: Bearer orosy_demo_xxxxxxxx" \
  "https://wholesale-api.orosy.com/v1/orders/de300003-…"

{
  "status": "confirmed",
  "confirmed_total": 2640,
  "payment": { "status": "succeeded" },
  "items": [ { "item_no": 1, "qty": 2, "confirmed_qty": 2 } ],
  "confirmed_at": "2026-07-03 05:12:56+00"
}

pending_confirmation → confirmed、confirmed_qty: null → 2、支払いも succeeded に進みました。

confirm_partial（一部だけ確保）や cancel も試せます。一部品切れのときに請求がどうなるか（届いた分だけ請求・全量品切れなら請求ゼロ）を、本番前にコードで確認できるのがこのシミュレータの目的です。

できました 🎉

いま体験したこと:

約 20 万点の横断検索（卸価格と参考上代つき）
仕入れ先をまたいだ 1 カートと、送料・税込みの事前見積
価格変動ガード付きの注文
確保確定までのライフサイクル

次のステップ

一部品切れのときの請求を確かめる: confirm_partial で「届いた分だけ請求」を再現 → ガイド「一部品切れと請求」へ
AI エージェントから仕入れる: Claude などの AI に自然言語で検索〜発注させる → ガイド「AI エージェントから仕入れる（MCP）」へ
リファレンス: 全エンドポイントの仕様 → https://wholesale-api.orosy.com/docs
本番利用: 承認済みアカウントならそのまま本番発注できます。支払い方法の登録・適格請求書の取得はポータル内で完結します（問い合わせ不要）

困ったら: wholesale_shop_api@orosy.com