検索クエリとフィルター
Search APIを使用すると、指定されたデータタイプ（スコープ）内のレコードをクエリできます。複数のフィールドにわたるテキスト検索にはクエリパラメータを使用し、特定の属性への正確なマッチングにはフィルターを使用します。
基本検索
基本検索にはscopeパラメータが必要で、ページネーションされた結果（デフォルトで1ページあたり30件）が新しいものから順に返されます。
curl https://api.omise.co/search?scope=charge \
-u $OMISE_SECRET_KEY:
クエリパラメータ
queryパラメータは、スコープ固有のテキスト属性を検索します：
# 検索可能なフィールドに「somchai」が含まれる課金を検索
curl https://api.omise.co/search?scope=charge&query=somchai \
-u $OMISE_SECRET_KEY:
クエリはスコープに応じて複数のフィールドを検索します。課金の場合、id、card_bank、card_name、description、failure_message、metadataを検索します。
フィルターパラメータ
filtersパラメータは、特定の条件に一致するオブジェクトをマッチングします：
# 正確に1000 THBの課金を検索
curl "https://api.omise.co/search?scope=charge&filters[amount]=1000&filters[currency]=THB" \
-u $OMISE_SECRET_KEY:
ブール値
ブールフィルターは自然言語の同等表現を受け入れます：
| 真の値 | 偽の値 |
|---|---|
yes | no |
on | off |
true | false |
# キャ プチャ済みの課金を検索
curl "https://api.omise.co/search?scope=charge&filters[captured]=yes" \
-u $OMISE_SECRET_KEY:
範囲構文
数値フィールドと日付フィールドに範囲を指定するには..を使用します：
数値範囲：
# 1000から5000の間の課金を検索（基本通貨単位）
curl "https://api.omise.co/search?scope=charge&filters[amount]=1000..5000" \
-u $OMISE_SECRET_KEY:
日付範囲：
# 2025年1月に作成された課金を検索
curl "https://api.omise.co/search?scope=charge&filters[created]=2025/01/01..2025/01/31" \
-u $OMISE_SECRET_KEY:
相対日付範囲：
| 値 | 説明 |
|---|---|
today | 当日 |
yesterday | 前日 |
this_week | 今週 |
last_week | 先週 |
this_month | 今月 |
last_month | 先月 |
# 今月作成された課金を検索
curl "https://api.omise.co/search?scope=charge&filters[created]=this_month" \
-u $OMISE_SECRET_KEY:
金額フィールドを検索する際は、最小単位/補助単位（例：10000サタン）ではなく、通貨の基本単位（例：100 THBの場合は100）を使用してください。
追加パラメータ
オブジェクトの展開
IDフィールドを完全なオブジェクトとして返すにはexpand=trueを使用します：
curl "https://api.omise.co/search?scope=charge&expand=true" \
-u $OMISE_SECRET_KEY:
結果のエクスポート
エクスポートを作成するにはexport=trueとfilter_typeを使用します：
curl "https://api.omise.co/search?scope=charge&export=true&filter_type=monthly_captured" \
-u $OMISE_SECRET_KEY:
利用可能なフィルタータイプ：
monthly_captured- 月間のキャプチャ済み課金monthly_created- 月間の作成された課金monthly_date- 月間の日付別課金
検索可能なスコープ
charge
課金と支払いを検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
amount | integer | 基本通貨単位での課金金額 |
authorized | boolean | 課金が承認されているかどうか |
capture | boolean | 自動キャプチャが有効かどうか |
captured | boolean | 課金がキャプチャされたかどうか |
captured_at | datetime | 課金がキャプチャされた日時 |
credit_card_brand | string | カードブランド（visa、mastercardなど） |
card_last_digits | string | カードの下4桁 |
created | datetime | 課金が作成された日時 |
currency | string | 通貨コード |
disputed | boolean | 課金が異議申し立てされているかどうか |
failure_code | string | 失敗した場合の失敗コード |
fraud | boolean | 不正としてフラグ付けされているかどうか |
is_installment | boolean | 分割払いかどうか |
refunded | boolean | 課金が返金されたかどうか |
refund_amount | integer | 返金総額 |
scheduled | boolean | スケジュールされた課金かどうか |
source_of_fund | string | 資金源 |
source_type | string | 支払いソースタイプ |
status | string | 課金ステータス |
voided | boolean | 課金が無効化されたかどうか |
installment_terms | integer | 分割回数 |
クエリ可能な属性： id、card_bank、card_name、description、failure_message、metadata
customer
顧客レコードを検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
created | datetime | 顧客が作成された日時 |
クエリ可能な属性： id、description、email、metadata
dispute
異議申し立てレコードを検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
amount | integer | 異議申し立て金額 |
card_first_digits | string | カードの上6桁 |
card_last_digits | string | カードの下4桁 |
charge_id | string | 関連する課金ID |
closed_at | datetime | 異議申し立てが終了した日時 |
created | datetime | 異議申し立てが作成された日時 |
currency | string | 通貨コード |
fraud | boolean | 不正としてフラグ付けされているかどうか |
status | string | 異議申し立てステータス |
クエリ可能な属性： id、card_brand、card_id、card_name、metadata、message、reason_code、reason_message
link
支払いリンクを検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
amount | integer | リンク金額 |
created | datetime | リンクが作成された日時 |
currency | string | 通貨コード |
multiple | boolean | 複数回の支払いが許可されているかどうか |
used | boolean | リンクが使用されたかどうか |
used_at | datetime | リンクが使用された日時 |
クエリ可能な属性： id、description、link_reference、title
receipt
領収書レコードを検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
created | datetime | 領収書が作成された日時 |
クエリ可能な属性： id
recipient
振込受取人を検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
active | boolean | 受取人がアクティブかどうか |
activated_at | datetime | 受取人がアクティブ化された日時 |
bank_last_digits | string | 銀行口座の下桁 |
created | datetime | 受取人が作成された日時 |
deleted | boolean | 受取人が削除されたかどうか |
failure_code | string | 検証失敗コード |
type | string | 受取人タイプ（individual/corporation） |
verified | boolean | 受取人が検証されたかどうか |
verified_at | datetime | 受取人が検証された日時 |
クエリ可能な属性： id、bank_name、bank_brand、description、email、metadata、name、tax_id
refund
返金レコードを検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
amount | integer | 返金金額 |
card_first_digits | string | カードの上6桁 |
card_last_digits | string | カードの下4桁 |
charge_id | string | 関連する課金ID |
created | datetime | 返金が作成された日時 |
status | string | 返金ステータス |
voided | boolean | 返金が無効化されたかどうか |
クエリ可能な属性： id、card_bank、card_brand、card_id、card_name、charge_description、currency、metadata
transfer
振込レコードを検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
amount | integer | 振込金額 |
created | datetime | 振込が作成された日時 |
currency | string | 通貨コード |
fee | integer | 振込手数料 |
paid | boolean | 振込が支払われたかどうか |
paid_at | datetime | 振込が支払われた日時 |
sent | boolean | 振込が送信されたかどうか |
sent_at | datetime | 振込が送信された日時 |
クエリ可能な属性： id、bank_name、bank_brand、failure_code、failure_message、metadata、recipient_email、recipient_id、recipient_name、transaction_id
transaction
取引レコードを検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
amount | integer | 取引金額 |
created | datetime | 取引が作成された日時 |
currency | string | 通貨コード |
hold_until | datetime | 保留期限日 |
kind | string | 取引タイプ |
クエリ可能な属性： id、record_id
charge_schedule
課金スケジュール（定期支払い）を検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
status | string | スケジュールステータス |
active | boolean | スケジュールがアクティブかどうか |
amount | integer | スケジュールされた課金金額 |
created | datetime | スケジュールが作成された日時 |
card_last_digits | string | カードの下4桁 |
クエリ可能な属性： recurrence_id、currency、description、customer_email、card_brand、card_bank、card_name
transfer_schedule
振込スケジュールを検索します。
フィルター可能な属性：
| 属性 | 型 | 説明 |
|---|---|---|
status | string | スケジュールステータス |
active | boolean | スケジュールがアクティブかどうか |
created | datetime | スケジュールが作成された日時 |
クエリ可能な属性： recurrence_id、recipient_name
例
高額のキャプチャ済み課金を検索
curl "https://api.omise.co/search?scope=charge&filters[amount]=10000..&filters[captured]=true&filters[created]=this_month" \
-u $OMISE_SECRET_KEY:
メールドメインで顧客を検索
curl "https://api.omise.co/search?scope=customer&query=@company.com" \
-u $OMISE_SECRET_KEY:
保留中の異議申し立てを検索
curl "https://api.omise.co/search?scope=dispute&filters[status]=pending" \
-u $OMISE_SECRET_KEY:
失敗した振込を検索
curl "https://api.omise.co/search?scope=transfer&filters[paid]=false&query=failure" \
-u $OMISE_SECRET_KEY:
FAQ
同じリクエストでクエリとフィルターを組み合わせることはできますか？
はい、queryとfiltersパラメータを一緒に使用できます。クエリはテキストフィールドを検索し、フィルターは正確な属性値にマッチします。結果は両方の条件に一致する必要があります。
クエリとフィルターの違いは何ですか？
queryパラメータは複数のフィールドにわたってテキスト検索を実行し（検索ボックスのように）、filtersは特定の属性の正確な値にマッチします。曖昧なテキストマッチングにはクエリを、正確なフィルタリングにはフィルターを使用してください。
メタデータ内を検索するにはどうすればよいですか？
メタデータの内容を検索するにはqueryパラメータを使用します。例えば、query=order123は、メタデータに「order123」が含まれるレコードを検索します。メタデータはクエリ可能ですが、フィルター可能ではないことに注意してください。
どの日付形式がサポートされていますか？
日付はYYYY/MM/DD、YYYY-MM-DD、またはtoday、this_week、this_monthなどの相対値で指定できます。範囲は..構文を使用します：2025/01/01..2025/01/31。
金額検索で期待通りの結果が返ってこないのはなぜですか？
補助単位ではなく、基本通貨単位を使用することを忘れないでください。THBの場合、1000 THBの課金を検索するには1000を検索してください。100000（サタン単位）ではありません。
1ページあたり何件の結果が返されますか？
Search APIはデフォルトで1ページあたり30件の結果を返します。より大きな結果セットをナビゲートするには、ページネーションパラメータを使用してください。