# POST /api/orders/search

注文検索

呼び出し元のショップの注文を検索し、一覧で取得します。

注文日の範囲、注文状態、決済手段、注文の種類、キーワードで絞り込めます。
指定した並び順とページングで返し、注文日の範囲を省略すると直近 3 ヶ月が対象になります。

注文日の範囲は最長 1 年です。
終了日には開始日の 1 年後の前日まで指定できます（開始日が 2025-09-18 なら終了日は 2026-09-17 まで）。

各注文は概要を返します。
注文明細、部分発送履歴、決済トランザクション、売上残高ログなどの詳細は、`GET /api/orders/{unique_key}` で取得することができます。
取得による注文情報の変更や通知の送信はありません。

## 要求スコープ

- `orders.read`

## リクエストボディ

`application/json`

- `keyword` string（任意 / 255 文字以下）: キーワード。注文番号・購入者情報・商品名・注文メモなどを対象に絞り込みます。
- `ordered_from_date` string (date)（任意）: 注文日の範囲開始（YYYY-MM-DD, JST）。この日の 0 時以降が対象です。省略時は終了日の 3 ヶ月前です。終了日より後の日付は指定できません。
- `ordered_to_date` string (date)（任意）: 注文日の範囲終了（YYYY-MM-DD, JST）。この日の終わりまでが対象です。省略時は当日です。開始日の 1 年後以降の日付は指定できません。
- `statuses` "ordered" | "dispatched" | "cancelled"[]（任意）: 注文状態での絞り込み。複数指定した場合はいずれかに一致する注文が対象です。未指定の場合は全状態が対象です。
- `payments` "creditcard" | "cvs" | "base_bt" | "atobarai" | "bnpl" | "bt" | "cod" | "carrier" | "paypal" | "amazon_pay" | "paypay"[]（任意）: 決済手段での絞り込み（例: creditcard / cvs / paypay）。複数指定した場合はいずれかに一致する注文が対象です。未指定の場合は全決済手段が対象です。
- `order_types` "normal" | "pre" | "subscription" | "digital" | "lottery" | "takeout"[]（任意）: 注文の種類での絞り込み。複数指定した場合はいずれかに一致する注文が対象です。未指定の場合は全種類が対象です。
- `properties` "has_order_remark" | "has_remark" | "has_delivery_date" | "has_option_property" | "has_reserved_kantan_delivery"[]（任意）: その他条件での絞り込み。複数指定した場合はいずれかに一致する注文が対象です。has_order_remark=ショップメモあり、has_remark=購入者備考あり、has_delivery_date=配送希望日指定あり、has_option_property=商品オプションあり、has_reserved_kantan_delivery=かんたん発送予約あり
- `sort` "ordered_desc" | "ordered_asc" | "scheduled_date_asc" | "delivery_date_asc" | "payment_date_asc"（任意）: 並び順。ordered_desc=注文日時の新しい順、ordered_asc=古い順、scheduled_date_asc=予約商品の発送予定日が近い順、delivery_date_asc=配送希望日が近い順、payment_date_asc=入金日（発送可能日）が近い順
- `limit` integer（任意 / ≥ 1 / ≤ 200）: 1 ページあたりの取得件数（1〜200）
- `page` integer（任意 / ≥ 1 / ≤ 500）: 取得するページ番号（1 始まり、最大 500）

## レスポンスボディ（200）

`application/json`

- `orders` OrderSummary[]（必須）: 検索条件に一致した注文の一覧。並び順は sort に従います。該当が無い場合は空配列です。
  - `unique_key` string（必須）: 注文の一意キー。注文詳細の取得に使う識別子です。
  - `status` string（必須）: 注文状態を表す文字列。値は固定された列挙ではありません。現在の仕様で返る主な値は 'ordered'（発送待ち）、'unpaid'（入金待ち）、'unshippable'（対応開始前）、'dispatched'（発送済み）、'cancelled'（キャンセル済み）、'shipping'、'arrived' です。今後の機能追加により、新しい値が返る場合があります。
  - `ordered_at` string (date-time)（必須）: 注文日時（RFC 3339, 秒精度 UTC）
  - `cancelled_at` string (date-time) | null（必須）: キャンセル日時（RFC 3339, 秒精度 UTC）。未キャンセルは null です。
  - `modified_at` string (date-time)（必須）: 注文の最終更新日時（RFC 3339, 秒精度 UTC）
  - `via` string（必須）: 注文経路。記録が無い場合は 'default' です。
  - `remark` string | null（必須）: 購入者が入力した備考
  - `add_comment` string | null（必須）: ショップから注文者へのメッセージ
  - `shop_memo` OrderShopMemo（必須）
    - `text` string（必須）: ショップメモ本文。未入力の場合は空文字列です。
  - `mail_magazine_opt_in` boolean | null（必須）: メールマガジン購読の同意。購入時に同意を取得していない注文は null です。
  - `customer` OrderCustomer（必須）
    - `name` OrderCustomerName（必須）
      - `first` string（必須）: 名
      - `last` string（必須）: 姓
      - `first_kana` string | null（必須）: 名（カナ）。未登録時は null です。
      - `last_kana` string | null（必須）: 姓（カナ）。未登録時は null です。
    - `mail_address` string（必須）: 購入時に登録されたメールアドレス。未登録時は空文字です。
    - `address` OrderCustomerAddress（必須）
      - `country` string（必須）: 国名。日本国内であれば 'Japan' です。
      - `country_code` string | null（必須）: 国コード（ISO 3166-1 alpha-2）。国コードを特定できない場合は null です。
      - `zip_code` string（必須）: 郵便番号。ハイフンの有無は保存時のままです。
      - `prefecture` string（必須）: 都道府県
      - `address` string（必須）: 市区町村・番地
      - `address2` string（必須）: 建物名・部屋番号など
      - `tel` string | null（必須）: 電話番号。未登録時は null です。
  - `shipping` OrderShipping（必須）
    - `name` OrderShippingName（必須）
      - `first` string | null（必須）: 名。配送先未登録時は null です。
      - `last` string | null（必須）: 姓。配送先未登録時は null です。
    - `address` OrderShippingAddress（必須）
      - `country` string | null（必須）: 国名。配送先未登録時は null です。
      - `country_code` string | null（必須）: 国コード（ISO 3166-1 alpha-2）。未登録または国コードを特定できない場合は null です。
      - `zip_code` string | null（必須）: 郵便番号。配送先未登録時は null です。
      - `prefecture` string | null（必須）: 都道府県。配送先未登録時は null です。
      - `address` string | null（必須）: 市区町村・番地。配送先未登録時は null です。
      - `address2` string | null（必須）: 建物名・部屋番号など。配送先未登録時は null です。
      - `tel` string | null（必須）: 電話番号。未登録時は null です。
  - `subscription` OrderSubscription（必須）: 定期便情報。通常注文では null です。
    - `unique_key` string | null（必須）: 定期便の一意キー。未取得時は null です。
    - `repeat_number` integer | null（必須）: 何回目の配送か
    - `repeat_times` integer | null（必須）: 配送回数の総数
  - `referrer` OrderReferrer（必須）: 流入元情報。記録が無い注文は null です。
    - `site_domain` string | null（必須）: 流入元ドメイン
    - `site_param` string | null（必須）: 流入元から引き継ぐ値
  - `item_count` integer（必須）: 注文に含まれる商品の点数（キャンセル明細を除いた各明細の数量の合計）
  - `amounts` OrderAmounts（必須）
    - `subtotal` integer（必須）: 商品合計（円）。明細 total の合計です。
    - `shipping_fee` integer（必須）: 送料（円）。無料は 0 です。
    - `cod_fee` integer（必須）: 代引手数料（円）。対象外は 0 です。
    - `total` integer（必須）: 注文合計（円）。クーポン・送料・代引手数料・金額調整を反映した値です。
    - `coupon_discount` OrderCouponDiscount（必須）
      - `amount` integer（必須）: クーポン割引額（円）。割引なしは 0 です。
      - `note` string | null（必須）: 割引メモ（クーポンコード等）
      - `allocates_balance_log` boolean（必須）: 売上残高ログの金額配分に含めるクーポン割引かどうか
    - `coin_discount` OrderCoinDiscount（必須）
      - `amount` integer（必須）: コイン割引額（円）。割引なしは 0 です。
      - `note` string | null（必須）: 割引メモ
    - `adjustment` OrderAmountAdjustment（必須）
      - `amount` integer（必須）: 金額調整（円）。調整なしは 0 です。
    - `service_charge` OrderServiceCharge（必須）
      - `collected_fee` integer（必須）: BASE 徴収手数料（円）。未徴収の注文は 0 です。
      - `fee_type` "base" | "payid_app"（必須）: 手数料種別（base / payid_app）
    - `additional_charges` OrderAdditionalCharge[]（必須）: 追加料金の内訳。無い場合は空配列です。
      - `name` string | null（必須）: 追加料金の種別名
      - `collected_fee` integer | null（必須）: 追加料金額（円）
  - `delivery` OrderSummaryDelivery（必須）
    - `delivery_company_id` integer（必須）: 注文全体の配送業者 ID。未指定は 0 です。
    - `tracking_number` string | null（必須）: 注文全体の伝票番号
    - `delivery_date` string (date) | null（必須）: 配送希望日（YYYY-MM-DD）。未指定は null です。
    - `delivery_time_zone` string | null（必須）: 配送希望時間帯（4 桁。例: '1214' = 12 時-14 時）。未指定は null です。
    - `dispatched_at` string (date-time) | null（必須）: 最終発送日時（RFC 3339, 秒精度 UTC）。未発送は null です。
  - `payment` OrderSummaryPayment（必須）
    - `method` string | null（必須）: 注文確定時の決済手段。未確定は null です。
- `pagination` Pagination（必須）
  - `page` integer（必須 / ≥ 1）: 現在のページ番号（1 始まり）
  - `limit` integer（必須 / ≥ 1）: 1 ページあたりの最大件数
  - `total_count` integer（必須 / ≥ 0）: 検索条件に一致した注文の総件数
  - `total_pages` integer（必須 / ≥ 0）: 総ページ数。total_count と limit から算出した値です。0 件のときは 0 です。
  - `has_next` boolean（必須）: 次のページが存在するか
  - `has_previous` boolean（必須）: 前のページが存在するか

## リクエスト例

```sh
curl -X POST "https://apiv2.thebase.com/api/orders/search" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "keyword": "サンプル商品"
}'
```

## レスポンス

| Status | Description |
| --- | --- |
| `200` | 検索成功。条件に一致した注文の概要一覧とページング情報を返します。 |

## エラー

エラーは `application/problem+json` の Problem 形式で返します。認証・スコープ・予期しない内部エラーなど、すべてのエンドポイントに共通のエラーと構造・判別方法は [エラーレスポンス](/docs/errors.md) を参照してください。

このエンドポイントが返すその他のエラーは次のとおりです。

| Status | Type | Description |
| --- | --- | --- |
| `400` | `/errors/request/malformed-body` | リクエストボディをこのエンドポイントが要求する形式として解釈できない場合に返します。 |
| `400` | `/errors/orders/invalid-body` | リクエストボディがエンドポイントのスキーマを満たさない場合に返します。 |
| `413` | `/errors/request/body-too-large` | JSON リクエストボディが 1 MiB の上限を超える場合に返します。 |
| `415` | `/errors/request/unsupported-media-type` | JSON 形式のリクエストボディを要求するエンドポイントに、対応していない Content-Type が指定された、または Content-Type が指定されていない場合に返します。 |
| `502` | `/errors/internal/bad-gateway` | BASE API が処理を完了するために必要な内部処理で不整合が発生した場合に返します。 |
| `504` | `/errors/internal/gateway-timeout` | BASE API が処理を完了するために必要な内部処理が制限時間内に完了しなかった場合に返します。 |