このガイドの目的

レシートローラーの販売管理API（Orders / OMS API）を使って、ビジネスアカウント配下の受注を作成・取得・更新・状態遷移（確認／処理中／キャンセル／店舗POS受け取り）・削除する方法をまとめます。Web受注・電話注文・マーケットプレイス連携など、店舗の販売チャネルを統合したいときの入り口になるガイドです。

前提

• OAuth 2.0 認可コードフローでアクセストークンを取得済みであること
• アプリのスコープに store.orders.read（読み取り）／store.orders.write（作成・更新・削除・状態遷移）を含めていること
• ビジネスアカウントID（UUID）が分かっていること（ビジネスアカウント・店舗・POS端末の一覧を取得する）
• ベースURL: https://receiptroller.io

エンドポイント一覧

注文ステータスの種類

1. 注文一覧を取得する

GET /api/v1/orders?organizationId={organizationId}&status=Pending
Authorization: Bearer {access_token}

クエリパラメータ（任意）

• status — 注文ステータスで絞り込み
• channel — Web / POS / Phone / Manual / Marketplace
• paymentStatus — Unpaid / Paid / Refunded / PartialRefund

レスポンスは orders 配列に注文オブジェクト。各オブジェクトの主要フィールドは下の「注文オブジェクトの構造」を参照してください。

2. 1注文の詳細を取得する

GET /api/v1/orders/{orderId}?organizationId={organizationId}
Authorization: Bearer {access_token}

3. 注文を新規作成する

POST /api/v1/orders?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "orderNumber": "RR-2026-0002",
  "channel": "Phone",
  "customerName": "佐藤花子",
  "customerEmail": "hanako@example.com",
  "customerPhone": "080-9876-5432",
  "shippingAddress": {
    "postalCode": "100-0001",
    "prefecture": "東京都",
    "city": "千代田区",
    "line": "千代田1-1"
  },
  "items": [
    { "productId": "prd-002", "productName": "アイスティー", "sku": "TEA-ICE-001",
      "quantity": 3, "unitPrice": 380, "subtotal": 1140 }
  ],
  "paymentMethod": "BankTransfer",
  "paymentStatus": "Unpaid",
  "subtotalAmount": 1140,
  "taxAmount": 114,
  "shippingAmount": 500,
  "totalAmount": 1754,
  "linkedStoreId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "notes": "電話受注。日中の配達希望。"
}

ポイント

• customerName のみ必須
• リクエストボディに organizationId を含めても無視されます。トークン／クエリで解決したビジネスアカウントが必ず使われます
• 初期ステータスは常に Pending。ステータスを進めるには専用の遷移エンドポイントを使ってください

4. 注文を更新する

PUT /api/v1/orders/{orderId}?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "customerName": "佐藤花子",
  "customerPhone": "080-9876-5432",
  "shippingAddress": { "postalCode": "100-0001", "prefecture": "東京都",
                       "city": "千代田区", "line": "千代田1-1-1（番地修正）" },
  "items": [ ... ],
  "subtotalAmount": 1140, "taxAmount": 114, "shippingAmount": 500, "totalAmount": 1754
}

ポイント

• ステータス変更には使わないでください。ステータスは /confirm / /process / /cancel / /fulfill-via-pos 経由で更新するのがルールです（監査ログに操作種別が正しく残るため）
• POS受け取りで紐付いた linkedPosTransaction 情報も PUT では更新できません — 専用エンドポイント経由のみ
• 支払いステータス（paymentStatus）は更新可能
• orderNumber と createdAt は更新できません（サーバー側で保護）

5. ステータスを進める（確認 → 処理中 → 出荷など）

確認する（Pending → Confirmed）

POST /api/v1/orders/{orderId}/confirm?organizationId={organizationId}

処理中にする（Confirmed → Processing）

POST /api/v1/orders/{orderId}/process?organizationId={organizationId}

キャンセルする

POST /api/v1/orders/{orderId}/cancel?organizationId={organizationId}

状態遷移エンドポイントはレスポンスとして更新後の完全な注文オブジェクトを返します。

※ 出荷（Shipped）／配達完了（Delivered）／返金（Refunded）への遷移は、現状WMS／決済システム連携経由で自動的に発生します。アプリから直接遷移させたい場合は コミュニティ でユースケースをお知らせください。

6. 店舗POSでの受け取り（オンライン注文の店頭受け渡し）

顧客がオンラインで注文 → 店舗カウンターで受け取り → レジで会計、というフローを一度の操作で完結させるエンドポイントです。POS取引と OMS 注文を相互にリンクし、注文を一気に Delivered ＋ Paid に遷移させます。

POST /api/v1/orders/{orderId}/fulfill-via-pos?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "posTerminalId": "term-001",
  "posTransactionId": "tx-9001"
}

動作

• OMS注文の linkedPosTransaction に { terminalId, transactionId } を記録
• POS取引の links.omsOrderId に注文IDを記録（逆方向リンク）
• 注文ステータスを Delivered に遷移
• 支払いステータスが Unpaid なら Paid に変更し、paidAt を記録（レジで決済済みのため）
• タイムラインに「FulfilledViaPos」エントリを追加
• 注文更新Webhook（order.updated）が発火 — ペイロードに linked_pos_terminal_id と linked_pos_transaction_id が含まれます

べき等性

• 同じ注文IDに同じ posTransactionId で再度呼んでも副作用なし。リトライ／二重タップに安全

エラーケース

• 注文 / POS取引が見つからない → 404
• POS取引が別のOMS注文に既に紐付いている → 404（コンフリクト防止）
• POS取引がこのビジネスアカウントに属さない → 404（クロステナント防御）

レスポンス例（注文オブジェクトの一部）

{
  "id": "ord-001",
  "status": "Delivered",
  "payment": { "method": "CreditCard", "status": "Paid", "paidAt": "2026-06-01T13:42:00Z" },
  "linkedStore": { "id": "f47ac10b-...", "name": "渋谷店" },
  "linkedPosTransaction": {
    "terminalId": "term-001",
    "transactionId": "tx-9001"
  },
  ...
}

利用シナリオ

• 顧客がWebで Pending 注文 → 店舗のレジアプリで POST /confirm → 商品を渡す → レジで会計 → POS取引が記録された直後にレジアプリから POST /fulfill-via-pos
• 取引一覧（Transactions API）で、POS行とOMS行の両方が相互にリンクを持つようになり、UI側で重複表示の制御が可能になります

7. 注文を削除する

DELETE /api/v1/orders/{orderId}?organizationId={organizationId}
Authorization: Bearer {access_token}

レスポンスは 204 No Content。削除済み注文は一覧・検索結果から消えます。

注文オブジェクトの構造

{
  "id": "ord-001",
  "orderNumber": "RR-2026-0001",
  "channel": "Web",
  "status": "Pending",
  "customer": { "name": "...", "email": "...", "phone": "..." },
  "shippingAddress": { "postalCode": "...", "prefecture": "...", "city": "...", "line": "..." },
  "items": [ { "productId": "...", "productName": "...", "sku": "...",
               "quantity": 2, "unitPrice": 480, "subtotal": 960 } ],
  "itemCount": 2,
  "payment": { "method": "CreditCard", "status": "Paid", "paidAt": "..." },
  "amounts": { "subtotal": 960, "tax": 96, "shipping": 500, "discount": 0, "total": 1556 },
  "linkedStore": { "id": "...", "name": "..." },
  "linkedPosTransaction": null,        // 店舗POS受け取り済みなら { terminalId, transactionId }
  "notes": "...",
  "preOrder": { "isPreOrder": false, "targetShipDate": null },
  "createdAt": "...",
  "updatedAt": "..."
}

明細（Items）の構造

{
  "productId": "prd-001",
  "productName": "ブレンドコーヒー M",
  "sku": "CFE-BLD-M",
  "quantity": 2,
  "unitPrice": 480,
  "subtotal": 960,
  "unit": "個"
}

productId はレシートローラー商品マスターのID（商品管理API で取得可能）。POSやEC外部システム経由の注文では、productIdなしで productName + sku のみ送ることもできます。

典型的なフロー（モバイルアプリ）

1. OAuthでアクセストークン取得 → スコープに store.orders.read と store.orders.write
2. GET /api/v1/me/organizations でビジネスアカウント選択
3. 受注ダッシュボード画面で GET /api/v1/orders?status=Pending を取得
4. 新規受注画面で POST /api/v1/orders（その前に GET /api/v1/products で商品を選ばせる）
5. 注文詳細画面で「確認する」ボタン → /confirm
6. 梱包担当者が「処理中にする」 → /process
7. 店舗のレジアプリで「店舗で受け取り完了」 → POS取引IDを指定して /fulfill-via-pos
8. 顧客都合のキャンセル → /cancel

エラーレスポンス

関連情報

• ビジネスアカウント・店舗・POS端末の一覧を取得する
• 商品管理API（Products API）の使い方
• 売上実績API（Sales API）の使い方
• 取引一覧API（Transactions API：POS＋OMS統合フィード）の使い方
• OAuthスコープ一覧と利用可否