Buy API

購入依頼を候補取得、発注、チェックアウト連携、仕入請求、会計連携前の確認へ進めるためのAPIです。

最終更新日: 2026/6/20

概要

Buy API は、購買ワークフロー向けのベータ版 AI API です。購入したい内容を、Sanka 上の候補取得、承認、購買、仕入請求連携に必要な構造化データへ変換したいときに使います。Buy API は /v2/buy 名前空間を使います。最初のベータ版では、次の処理に対応します。

手動入力または AI が整理した内容から Buy Request を作成
Shopify Global Catalog から商品候補を取得
依頼明細ごとに候補を選択
Sanka の発注を作成
手動確認用のチェックアウト URL を準備
チェックアウト後の外部注文 ID を記録
証憑ファイル付きで Sanka の仕入請求を作成
会計エクスポート前の準備状況を確認

この API は支払いを自動実行しません。チェックアウト準備では、ユーザーが手動で確認するための URL またはチェックアウト情報を返します。

認証

開発者 API キーを Authorization: Bearer <api_key> として送信します。
Buy API は Buy Request、会社、発注、仕入請求を作成するため、書き込み権限のあるキーを使います。
依頼作成、候補選択、発注作成、チェックアウト準備、注文確認、仕入請求作成などの書き込み処理では Idempotency-Key を送信します。
1つのワークフロー全体で同じキーを使い回さず、ユーザー操作ごとに安定したキーを使ってください。

ワークフロー

標準的な流れは次の通りです。

Buy Request を作成します。
依頼に対して商品候補を取得します。
依頼明細ごとに候補を選択します。
承認または購買に進められる状態として送信します。
発注と購入先別の購入レコードを作成します。
チェックアウトを準備し、ユーザーが購入先サイトで手動確認します。
外部注文 ID を記録します。
証憑ファイル付きで仕入請求を作成します。
会計レコード作成や会計ソフト連携の前に、準備状況を確認します。

複数明細の依頼では、候補選択を明細単位で管理します。Sanka は選択済み明細を購入先ごとにまとめ、購入先別にチェックアウトや仕入請求へ引き継げるようにします。

依頼を作成

1つ以上の明細を持つ Buy Request を作成します。

cURL

curl -X POST "https://api.sanka.com/v2/buy/requests" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-request-001" \
  -d '{
    "title": "配送ラベルの補充",
    "source": "manual",
    "currency": "USD",
    "business_purpose": "倉庫備品の補充",
    "lines": [
      {
        "description": "感熱配送ラベル 4 x 6 inch",
        "quantity": 10,
        "unit": "roll"
      }
    ]
  }'

自然文から依頼の下書きを構造化したい場合は、POST /v2/buy/intents を使います。

候補取得と承認

依頼に対して候補取得を開始します。

cURL

curl -X POST "https://api.sanka.com/v2/buy/requests/<request_id>/source" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-source-001" \
  -d '{
    "provider": "shopify_global_catalog"
  }'

候補取得の結果は次のエンドポイントで確認します。

GET /v2/buy/requests/<request_id>
GET /v2/buy/requests/<request_id>/sourcing-runs
GET /v2/buy/sourcing-runs/<sourcing_run_id>

依頼明細に対して候補を選択します。

cURL

curl -X POST "https://api.sanka.com/v2/buy/requests/<request_id>/select-offer" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-select-001" \
  -d '{
    "line_id": "<request_line_id>",
    "offer_snapshot_id": "<offer_snapshot_id>"
  }'

選択済み明細を承認または購買へ進める準備ができたら、POST /v2/buy/requests/<request_id>/submit を使います。

購買レコードを作成

承認済みまたは購買可能な Buy Request から発注を作成します。

cURL

curl -X POST "https://api.sanka.com/v2/buy/requests/<request_id>/create-purchase-order" \
  -H "Authorization: Bearer <api_key>" \
  -H "Idempotency-Key: buy-po-001"

購入先は Sanka の会社レコードとして作成または再利用されます。これにより、発注、仕入請求、会計連携で正式な取引先として扱えます。購入先別の購入レコードに対してチェックアウトを準備します。

cURL

curl -X POST "https://api.sanka.com/v2/buy/merchant-purchases/<merchant_purchase_id>/prepare-checkout" \
  -H "Authorization: Bearer <api_key>" \
  -H "Idempotency-Key: buy-checkout-001"

ユーザーが購入先サイトでチェックアウトを完了したら、外部注文 ID を記録します。

cURL

curl -X POST "https://api.sanka.com/v2/buy/merchant-purchases/<merchant_purchase_id>/confirm-order" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-order-001" \
  -d '{
    "external_order_id": "SHOP-10042"
  }'

仕入請求と会計連携前の確認

注文確認後、仕入請求を作成します。

cURL

curl -X POST "https://api.sanka.com/v2/buy/merchant-purchases/<merchant_purchase_id>/create-bill" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-bill-001" \
  -d '{
    "evidence_files": [
      {
        "file_id": "<uploaded_file_id>",
        "evidence_type": "receipt"
      }
    ]
  }'

会計連携前の準備状況を確認します。

cURL

curl -X POST "https://api.sanka.com/v2/buy/merchant-purchases/<merchant_purchase_id>/accounting-preview" \
  -H "Authorization: Bearer <api_key>"

確認結果には、未完了項目、注意事項、紐づくレコード、証憑ファイル数が含まれます。この確認だけでは、仕訳作成や会計ソフトへのエクスポートは実行されません。

次のステップ

ワークフローで作成される発注や仕入請求はオブジェクト API で確認します。
仕入請求作成時に領収書や請求書の証憑を添付する場合は、事前に File API を使います。
会計エクスポートなどの後続処理は Workflow API を使います。
一括処理の前にレート制限を確認してください。

PreviousAI API Nextデータエンリッチメント