在庫の同期・確保・出荷・移動
すべてのパスは https://api.toreca-cloud.com/partner/v1 からの相対パスです。先に認可と接続を済ませます。項目・上限・応答の詳細はAPIリファレンスで確認してください。
1. 在庫を同期する
GET /inventory/sitesで拠点と棚を取得します。GET /inventory/changesをカーソルなしで読み、hasMore: trueの間はnextCursorを次のcursorに渡します。受け取ったtypeとidごとにdataを上書き保存します。- 最後のカーソルを保存し、次から続きを読みます。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} で読み直せます。
掲載・当選から配送申請する
POST /inventory/commitmentsにrequestId、inventoryItemId、purpose、label、任意のexternalRefを渡します。個体は棚に残り、オリパ・販売への掲載(on_sale)になります。この時点では配送伝票を作りません。- 当選・購入後に
POST /inventory/commitments/{id}/allocateを呼びます。任意のallocationRefに自社の注文・開封番号を残せます。allocatedは顧客保有のまま店で保管している状態です。 - 顧客が配送を希望したら
POST /inventory/shipmentsにrequestId、commitmentIds、destinationLabel、reasonを渡します。最大200件のallocatedをまとめ、commitmentはshippingになります。 - 実際の発送時に
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 が添えられる場合があります。権限とエラーも参照してください。

