コンテンツにスキップ
トレカクラウド
Esc
↑↓移動↵開く⌘Jプレビュー
コピー・AI連携

在庫の同期・確保・出荷・移動

すべてのパスは https://api.toreca-cloud.com/partner/v1 からの相対パスです。先に認可と接続を済ませます。項目・上限・応答の詳細はAPIリファレンスで確認してください。

1. 在庫を同期する

  1. GET /inventory/sites で拠点と棚を取得します。
  2. GET /inventory/changes をカーソルなしで読み、hasMore: true の間は nextCursor を次の cursor に渡します。受け取った type と id ごとに data を上書き保存します。
  3. 最後のカーソルを保存し、次から続きを読みます。Webhookは更新の合図なので、通知を受けたら同じ変更フィードを読みます。

inventory:read が必要です。連携先の在庫範囲が「割り当てのみ」なら、店舗がその連携先へ割り当てた範囲だけが見えます。holdable は取得時点で確保可能かどうかの目安です。取得後の別操作で状態が変わることもあるため、確保の成功は書き込み応答で判断します。

価格だけの更新は個体の変更フィードに出ません。現在の評価額は POST /inventory/market-values に {"ids":["個体のUUID"]} を渡して読みます。最大200件、重複不可です。見える個体に価格がない場合は marketValue: null、存在しない・範囲外の個体は結果から除かれます。

2. 販売から出荷までを選ぶ

どちらも inventory:read と inventory:write が必要で、接続を許可したメンバーにも現在の inventory.write 権限が必要です。読む操作も、確保・掲載・配送の詳細には両スコープが必要です。

使う場面 流れ
1個体の販売を確保して出荷する holds → 必要なら confirm → ship
オリパ・販売へ掲載し、当選・購入後に顧客の配送依頼をまとめる commitments → allocate → shipments → ship

確保して出荷する

POST /inventory/holds に requestId、inventoryItemId、purpose(oripa または sale)、destinationLabel、reason を渡します。externalRef は任意の自社側参照番号です。

操作 結果・注意
作成 reserved。expiresAt は現在より後、90日以内。省略時は無期限
POST /inventory/holds/{id}/extend reserved の期限を変更
POST /inventory/holds/{id}/release reserved を解除して cancelled。発送待ちは解除不可
POST /inventory/holds/{id}/confirm、本文 {} 購入・当選が確定し awaiting_shipment。期限が消え、パートナーから解除不可
POST /inventory/holds/{id}/ship reserved または awaiting_shipment を出荷して shipped

一括作成は /inventory/holds/batch、解除は /release-batch、出荷は /ship-batch。最大100件で、1件の拒否で新しい変更は全件取り消されます。詳細は GET /inventory/holds/{id} で読み直せます。

掲載・当選から配送申請する

  1. POST /inventory/commitments に requestId、inventoryItemId、purpose、label、任意の externalRef を渡します。個体は棚に残り、オリパ・販売への掲載(on_sale)になります。この時点では配送伝票を作りません。
  2. 当選・購入後に POST /inventory/commitments/{id}/allocate を呼びます。任意の allocationRef に自社の注文・開封番号を残せます。allocated は顧客保有のまま店で保管している状態です。
  3. 顧客が配送を希望したら POST /inventory/shipments に requestId、commitmentIds、destinationLabel、reason を渡します。最大200件の allocated をまとめ、commitmentは shipping になります。
  4. 実際の発送時に POST /inventory/shipments/{id}/ship を呼びます。追跡番号は trackingNumber です。

掲載の一括作成・当選・解除は /inventory/commitments/batch、/allocate-batch、/release-batch で、最大200件、全件成功または全件取り消しです。

出荷前の配送取り消しは POST /inventory/shipments/{id}/cancel。個体は allocated に戻ります。掲載・当選自体の解除は /inventory/commitments/{id}/release を使い、配送申請中なら先に配送を取り消します。setAside: true は解除後もこの連携先への割り当てを残します。紛失個体を解除しても紛失状態は変わらず、販売可能には戻りません。

配達失敗などで実物が戻ったときは POST /inventory/shipments/{id}/returns を使います。元の棚へ返品し、顧客保有の新しい allocated commitmentを作ります。応答の commitmentId は返品元、commitment.id は新しいIDなので、自社の参照を更新します。

3. 出荷時の金額

金額は通貨の最小単位の整数で、JPYなら円です。0〜10,000,000,000を指定できます。

  • 確保の出荷では saleAmountMinor を指定します。省略すると最新の円評価額を使い、評価額もない場合は sale_amount_required で出荷を拒否します。
  • 配送申請の出荷では items に commitmentId と saleAmountMinor を渡します。指定しない行は円評価額を使います。
  • saleCurrency の既定は JPY。確保では金額、配送申請では items が必要です。配送申請をJPY以外で出荷する場合は、全行の金額を指定します。

金額未取得を0円に置き換えて再送しないでください。自社の売価を確認してから同じ対象を出荷し直します。

4. 棚・拠点・持ち出し

inventory:read と inventory:move、メンバーの inventory.write 権限が必要です。取得も同じ権限で、自社が作成した伝票だけを扱えます。

操作 入力と結果
POST /inventory/items/{id}/move toLocationId と reason。同じ拠点内の棚へ移動。同じ棚なら moved: false
POST /inventory/transfers requestId、toSiteId、inventoryItemIds、reason。1拠点から別拠点へ最大200件発送し、移動中にする
POST /inventory/transfers/{id}/receive toLocationId は移動先拠点の棚。任意の inventoryItemIds を受取。省略時は移動中の全件
POST /inventory/transfers/{id}/return reason と任意の inventoryItemIds。移動中の個体を元の棚へ戻す。受取済みは対象外
POST /inventory/checkouts requestId、inventoryItemIds、destinationLabel、reason。撮影・イベントなどへ最大200件持ち出す
POST /inventory/checkouts/{id}/return items の各 inventoryItemId・toLocationId と reason。持ち出した実物を棚へ戻す

持ち出し中の個体は removed で、棚・販売可能在庫から外れます。販売出荷としては扱いません。拠点間移動は GET /inventory/transfers/{id}、持ち出しは GET /inventory/checkouts/{id} で読み直します。

5. 再試行・拒否への対処

作成時の requestId は、自社の1回の業務操作に対して1つのUUIDを保存し、通信失敗後も同じ内容で再利用します。初回は201、同じ作成の再実行は200と現在の状態を返します。別の内容へ流用すると idempotency_conflict です。応答を受け取れなかったことだけを理由に新しいIDを発行しないでください。

未知の項目・空の理由・重複ID・上限超過は拒否されます。理由は前後空白除去後1〜2,000文字で、不正な制御文字は使えません。クライアントから個体の version は送りません。

エラー 対処
conflict 対象を読み直し、現在の状態を確認してから同じ操作を再試行
receipt_not_confirmed 店舗側の受取確認を完了してから再試行
unit_unavailable / unit_not_allocated 在庫・割り当てを同期し直す。別の個体へ変えるなら新しい業務操作として作成
hold_confirmed / hold_shipped 確保解除できない段階。店舗側で伝票を確認
commitment_shipping 出荷前なら配送申請を取り消してから解除
shipment_shipped 出荷前取り消し不可。実物が戻った場合だけ返品を記録
*_blocked / *_refused 状態・紛失・棚・拠点などを店舗で確認。拒否を成功扱いしない

エラーには対象の inventoryItemIds、holdIds、commitmentIds、requestId が添えられる場合があります。権限とエラーも参照してください。

最終更新

このページは役に立ちましたか?