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

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

## 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なので、自社の参照を更新します。

:::warning
配送申請を読み直したとき、`items[].commitmentId` が元の掲載IDと一致しない・`null` の場合は、出荷・返品を止めて店舗の管理者へ確認してください。この場合、正しい元のIDを指定しても `commitment_not_on_shipment` になることがあります。拒否を避けるために価格指定を削除したり、別の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` が添えられる場合があります。[権限とエラー](/api/scopes-and-errors)も参照してください。
