คิวรีการค้นหาและตัวกรอง

Search API ช่วยให้คุณสามารถค้นหาบันทึกภายในประเภทข้อมูลที่ระบุ (scope) ใช้พารามิเตอร์คิวรีสำหรับการค้นหาข้อความในหลายฟิลด์ หรือใช้ตัวกรองเพื่อจับคู่แอตทริบิวต์เฉพาะอย่างแม่นยำ

การค้นหาพื้นฐาน

การค้นหาพื้นฐานต้องการพารามิเตอร์ scope และส่งคืนผลลัพธ์แบบแบ่งหน้า (30 รายการต่อหน้าโดยค่าเริ่มต้น) โดยเรียงลำดับจากรายการใหม่ที่สุดก่อน

curl https://api.omise.co/search?scope=charge \
  -u $OMISE_SECRET_KEY:

พารามิเตอร์ Query

พารามิเตอร์ 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

พารามิเตอร์ 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
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:

หน่วยจำนวนเงิน

สำหรับการค้นหาฟิลด์จำนวนเงิน ให้ใช้หน่วยหลักของสกุลเงินนั้น (เช่น 100 สำหรับ 100 THB) ไม่ใช่หน่วยย่อย (เช่น 10000 สตางค์)

พารามิเตอร์เพิ่มเติม

ขยายออบเจ็กต์

ใช้ expand=true เพื่อส่งคืนฟิลด์ ID เป็นออบเจ็กต์แบบเต็ม:

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 และ filters คืออะไร?

พารามิเตอร์ query ทำการค้นหาข้อความในหลายฟิลด์ (เหมือนช่องค้นหา) ในขณะที่ filters จับคู่ค่าที่แน่นอนในแอตทริบิวต์เฉพาะ ใช้คิวรีสำหรับการจับคู่ข้อความแบบคลุมเครือและตัวกรองสำหรับการกรองที่แม่นยำ

ฉันจะค้นหาภายใน metadata ได้อย่างไร?

ใช้พารามิเตอร์ query เพื่อค้นหาเนื้อหา metadata ตัวอย่างเช่น query=order123 จะค้นหาบันทึกที่ metadata มี "order123" โปรดทราบว่า metadata สามารถค้นหาได้เท่านั้น ไม่สามารถกรองได้

รูปแบบวันที่ที่รองรับมีอะไรบ้าง?

วันที่สามารถระบุได้เป็น YYYY/MM/DD, YYYY-MM-DD หรือใช้ค่าสัมพัทธ์เช่น today, this_week, this_month ช่วงใช้รูปแบบ ..: 2025/01/01..2025/01/31

ทำไมการค้นหาจำนวนเงินของฉันไม่ส่งคืนผลลัพธ์ที่คาดหวัง?

อย่าลืมใช้หน่วยสกุลเงินหลัก ไม่ใช่หน่วยย่อย สำหรับ THB ให้ค้นหา 1000 เพื่อค้นหาการเรียกเก็บเงิน 1000 THB ไม่ใช่ 100000 (ซึ่งจะเป็นหน่วยสตางค์)

มีผลลัพธ์กี่รายการต่อหน้า?

Search API ส่งคืน 30 ผลลัพธ์ต่อหน้าโดยค่าเริ่มต้น ใช้พารามิเตอร์การแบ่งหน้าเพื่อนำทางผ่านชุดผลลัพธ์ที่ใหญ่กว่า

---

แหล่งข้อมูลที่เกี่ยวข้อง

• Universal Search
• Charges API
• Customers API
• Pagination