รายการสโคป OAuth และเงื่อนไขการใช้งาน

oauth scope api permission liff
เกี่ยวกับคู่มือนี้
รวบรวมสโคปทั้งหมดที่ระบุได้ใน OAuth API ของ ReceiptRoller พร้อมข้อมูลว่าแต่ละสโคปจะให้สิทธิ์แก่แอปประเภทใด โปรดตรวจสอบก่อนลงทะเบียนแอป OAuth หรือก่อนประกอบ authorization URL

รายการสโคป OAuth และเงื่อนไขการใช้งาน

API ของ ReceiptRoller ควบคุมทรัพยากรที่เข้าถึงได้ด้วยสโคปของ OAuth 2.0 เมื่อลงทะเบียนแอปและเมื่อนำผู้ใช้ไปยังหน้าให้สิทธิ์ โปรดระบุเฉพาะสโคปที่จำเป็นให้น้อยที่สุด สามารถระบุหลายสโคปได้โดยคั่นด้วยช่องว่างแบบครึ่งความกว้าง (half-width space)

การแบ่งประเภทสโคป

สโคปถูกแบ่งออกเป็น 4 หมวดหมู่ตามวัตถุประสงค์

  • กลุ่ม Store — ข้อมูลธุรกิจของร้านค้า/บัญชีธุรกิจ (สินค้า คำสั่งซื้อ สต็อก การจอง พนักงาน ฯลฯ)
  • กลุ่ม CRM — โปรไฟล์ลูกค้าและข้อมูลเซกเมนต์
  • กลุ่ม SNS / Analytics — โพสต์ SNS ผู้ชม การวิเคราะห์ และรายงานยอดขาย
  • กลุ่ม User (ผู้บริโภค) — ใบเสร็จ การใช้จ่าย ร้านค้าโปรด ฯลฯ ของผู้ใช้แต่ละราย

ดังจะกล่าวต่อไป สโคปกลุ่ม User โดยหลักการจะให้สิทธิ์เฉพาะแอปของผู้พัฒนาหลัก (first-party) และพาร์ตเนอร์ที่ได้รับการอนุมัติแล้วเท่านั้น ถือเป็นสโคปที่มีข้อจำกัดเข้มงวด

สโคปกลุ่ม Store

เป็นสโคปสำหรับให้เจ้าของร้านหรือผู้ดูแลบัญชีธุรกิจจัดการข้อมูลร้านของตนผ่าน OAuth สามารถให้สิทธิ์แก่แอปพาร์ตเนอร์ภายนอกได้เช่นกัน แต่ฝั่งร้านค้าจะต้องอนุญาตในหน้ายินยอม OAuth

สโคป สิทธิ์ที่ได้รับ
store.products.readดูข้อมูลสินค้าและสต็อก
store.products.writeลงทะเบียนและอัปเดตสินค้า
store.orders.readดูข้อมูลคำสั่งซื้อ
store.orders.writeอัปเดตสถานะคำสั่งซื้อ
store.customers.readดูข้อมูลลูกค้า
store.customers.writeสร้าง อัปเดต และลบลูกค้า
store.coupons.readดูข้อมูลคูปอง
store.coupons.writeสร้างและอัปเดตคูปอง
store.inventory.readดูข้อมูลคลังและสต็อก
store.inventory.writeปรับจำนวนสต็อกและบันทึกผลการตรวจนับ
store.flyers.readดูใบปลิวร้านค้า
store.flyers.writeสร้าง อัปเดต และเผยแพร่ใบปลิวร้านค้า
store.staff.readดูข้อมูลพนักงานและสตาฟ
store.staff.writeสร้าง อัปเดต และลบพนักงาน
store.business-hours.readดูเวลาทำการ วันหยุดพิเศษ และช่วงเวลาที่พร้อมทำงาน
store.business-hours.writeอัปเดตเวลาทำการ วันหยุดพิเศษ และช่วงเวลาที่พร้อมทำงาน
store.reservations.readดูข้อมูลการจอง ช่องการจอง และที่นั่ง
store.reservations.writeสร้าง แก้ไข และอัปเดตสถานะการจอง รวมถึงสร้างช่องการจอง
store.info.readดูข้อมูลพื้นฐานของร้าน (ชื่อร้าน ช่องทางติดต่อ ที่อยู่)
store.info.writeอัปเดตข้อมูลพื้นฐานของร้าน (ชื่อร้าน ช่องทางติดต่อ ที่อยู่)

สโคปกลุ่ม CRM

สโคป สิทธิ์ที่ได้รับ
crm.profiles.readดูโปรไฟล์ลูกค้า CRM
crm.segments.readดูเซกเมนต์และแรงก์ของ CRM

สโคปกลุ่ม SNS / Analytics

สโคป สิทธิ์ที่ได้รับ
sns.content.readดูข้อมูลโพสต์ SNS
sns.content.writeสร้าง อัปเดต เผยแพร่ ตั้งเวลา และลบโพสต์ SNS
sns.audience.readดูข้อมูลผู้ชม SNS
analytics.readดูสแนปช็อตการวิเคราะห์
sales.readดูรายงานยอดขาย ข้อมูลธุรกรรม และข้อมูลเชิงลึกทางธุรกิจ

สโคปกลุ่ม User (ผู้บริโภค)

สำคัญ: สโคปกลุ่ม User ต้องผ่านการตรวจสอบล่วงหน้า
สโคปเหล่านี้เข้าถึงข้อมูลส่วนบุคคลของผู้บริโภค เช่น ใบเสร็จ การใช้จ่าย และร้านค้าโปรดของผู้ใช้แต่ละราย จึงให้สิทธิ์เฉพาะแอปของผู้พัฒนาหลัก (first-party) ของ ReceiptRoller และแอปพาร์ตเนอร์ที่ได้รับการอนุมัติอย่างชัดเจนเท่านั้น
หากแอปที่ยังไม่ผ่านการตรวจสอบระบุสโคป user.* แล้วเรียก authorization URL จะได้รับข้อผิดพลาด app_not_approved
สโคป สิทธิ์ที่ได้รับ
user.profile.readดูข้อมูลพื้นฐานของผู้ใช้
user.profile.writeอัปเดตข้อมูลพื้นฐานของผู้ใช้
user.receipts.readดูใบเสร็จที่ผู้ใช้ได้รับ
user.spending.readดูสรุปการใช้จ่ายรายเดือน
user.spending.writeอัปเดตข้อมูลการใช้จ่ายและงบประมาณ
user.coupons.readดูคูปองของร้านค้าโปรด
user.favorites.readดูรายการร้านค้าโปรด
user.favorites.writeเพิ่มและลบร้านค้าโปรด

ข้อจำกัดสำคัญ

1. สโคปกลุ่ม User ต้องผ่านการตรวจสอบล่วงหน้า

หากรวมสโคป user.* ตอนลงทะเบียนแอป OAuth ค่า UserScopeStatus ของแอปจะกลายเป็น pending (รอการตรวจสอบ) จนกว่าทีมงาน ReceiptRoller จะตรวจสอบและเปลี่ยนเป็น approved หากระบุสโคป user.* ในโฟลว์การให้สิทธิ์ก่อนหน้านั้นจะได้รับข้อผิดพลาด

กรณีที่ร้านค้า/พาร์ตเนอร์ภายนอกต้องการ "แสดงใบเสร็จทั้งหมดที่ผู้ใช้ได้รับในแอป LIFF หรือแอปมือถือของตน" โดยหลักการแล้วจะต้องผ่านการตรวจสอบนี้ ยินดีให้คำปรึกษา โปรดติดต่อฝ่ายสนับสนุน

2. ไม่สามารถผสมสโคปกลุ่ม Store และกลุ่ม User ในโฟลว์การให้สิทธิ์เดียวกัน

ไม่สามารถระบุ store.orders.read และ user.receipts.read พร้อมกันในคำขอให้สิทธิ์เดียวได้ เพราะสองสโคปนี้มีผู้ดำเนินการ (actor) ต่างกัน (ร้านค้า vs. ผู้ใช้) เซิร์ฟเวอร์ให้สิทธิ์จึงจะปฏิเสธ

หากต้องการสร้างบริการที่จัดการข้อมูลทั้งสองด้าน ให้ลงทะเบียนแอป OAuth สองตัว แล้วขอโทเคนผ่านโฟลว์การให้สิทธิ์แยกกัน

3. หลักการสิทธิ์ขั้นต่ำ (least privilege)

เพื่อรักษาความไว้วางใจของผู้ใช้ (หรือเจ้าของร้าน) โปรดระบุเฉพาะสโคปที่จำเป็นจริง ๆ ไม่แนะนำให้ "ใส่ write ไว้เผื่อ" หรือ "ขอสโคปอื่นที่ไม่ได้ใช้"

สโคปที่แนะนำตามกรณีการใช้งาน

สิ่งที่ต้องการทำ สโคปที่จำเป็น หมายเหตุ
ซิงก์สต็อกและคำสั่งซื้อของร้านจากระบบภายนอก store.products.read store.products.write store.orders.read รับสิทธิ์ได้ด้วยความยินยอมของเจ้าของร้าน
บันทึกผลการปรับสต็อกและการตรวจนับ store.inventory.read store.inventory.write รับสิทธิ์ได้ด้วยความยินยอมของเจ้าของร้าน
รับการจองจากระบบจองภายนอกหรือแอปมือถือ store.reservations.read store.reservations.write รับสิทธิ์ได้ด้วยความยินยอมของเจ้าของร้าน
จัดการพนักงานและช่วงเวลาที่พร้อมทำงานในแอปจัดการกะ store.staff.read store.staff.write store.business-hours.read รับสิทธิ์ได้ด้วยความยินยอมของเจ้าของร้าน
อัปเดตข้อมูลร้าน (ชื่อร้าน ช่องทางติดต่อ ที่อยู่) จากแอปสตาฟหรือระบบภายนอก store.info.read store.info.write รับสิทธิ์ได้ด้วยความยินยอมของเจ้าของร้าน การดูไม่ต้องมีสิทธิ์นี้ แต่การอัปเดตต้องใช้ store.info.write
โพสต์ใบปลิวร้านของตนเองแบบรวมทีเดียวจาก CMS ภายในบริษัท store.flyers.write รับสิทธิ์ได้ด้วยความยินยอมของเจ้าของร้าน
เชื่อมเซกเมนต์ CRM ให้แผนกการตลาด crm.profiles.read crm.segments.read รับสิทธิ์ได้ด้วยความยินยอมของเจ้าของร้าน
ฝังแดชบอร์ดยอดขายเข้ากับเครื่องมือของตนเอง sales.read analytics.read รับสิทธิ์ได้ด้วยความยินยอมของเจ้าของร้าน
แสดงใบเสร็จทั้งหมดของผู้ใช้ในแอปมือถือของตน user.receipts.read ต้องผ่านการตรวจสอบล่วงหน้า
แสดงการใช้จ่ายรายเดือนเป็นภาพในแอปบัญชีครัวเรือน user.spending.read user.receipts.read ต้องผ่านการตรวจสอบล่วงหน้า
ต้องการดึงข้อมูลร้านค้าของผู้อื่นผ่าน LIFF — ไม่ได้ (ดึงได้เฉพาะสโคปกลุ่ม Store ของตนเองเท่านั้น)

เกี่ยวกับการใช้งานจาก LIFF / LINE Mini App

แม้จะเรียก API ของ ReceiptRoller จากแอป LIFF (LINE Mini App) ก็ให้ใช้โฟลว์ OAuth 2.0 Authorization Code มาตรฐาน

ไม่มีบริการแลกเปลี่ยน LINE ID token โดยตรง

ปัจจุบันเรายังไม่มีเอนด์พอยต์ที่แลกเปลี่ยน "LINE ID token → แอ็กเซสโทเคนของ ReceiptRoller" โดยตรง แอป LIFF ก็เช่นเดียวกับ Web แอปอื่น ๆ ที่ต้องนำผู้ใช้ไปยังหน้าให้สิทธิ์ของ ReceiptRoller

รูปแบบการพัฒนาบน LIFF

  1. หลังเปิดแอป LIFF ให้เริ่มต้น LIFF ด้วย liff.init()
  2. ในจังหวะที่ต้องการเรียก API ของ ReceiptRoller ให้นำผู้ใช้ไปยัง /oauth/authorize ด้วย liff.openWindow() หรือลิงก์ทั่วไป
  3. เมื่อผู้ใช้อนุญาตในหน้าให้สิทธิ์ของ ReceiptRoller จะมี authorization code ส่งกลับมาที่ redirect_uri
  4. แลก authorization code เป็นแอ็กเซสโทเคนด้วย POST /api/v1/auth/token (grantType: authorization_code)
  5. แนบโทเคนที่ได้ในเฮดเดอร์ Authorization: Bearer แล้วเรียก API

ข้อควรระวังเมื่อใช้สโคปกลุ่ม User

แม้จะระบุสโคป user.* ในแอป LIFF ก็ยังต้องผ่านการตรวจสอบล่วงหน้าตามที่กล่าวข้างต้น การออกแบบไม่ได้เป็นแบบ "เนื่องจากยืนยันตัวตนด้วย LINE แล้วจึงข้ามการยืนยันตัวตนผู้ใช้ของ ReceiptRoller ได้" การออกแบบเช่นนี้เพื่อความปลอดภัยและความโปร่งใสของความยินยอมจากผู้ใช้

คู่มือที่เกี่ยวข้อง

วันที่เผยแพร่: 2569-04-27 วันที่อัปเดต: 2569-07-05
กลับไปที่รายการวิธีใช้งาน
หมวดหมู่
ทั้งหมด ทั่วไป 14 Webhook 6 การแก้ปัญหา 6 การลงทะเบียนแอปพลิเคชัน 5 คู่มือตามประเภทข้อมูล 5 พื้นฐาน API 5 การดำเนินงานและความปลอดภัย 4 เริ่มต้นใช้งาน 4 การยืนยันตัวตนและข้อมูลรับรอง 3 คู่มือแยกตามโดเมนข้อมูล 3
แท็ก
API (22) OAuth (15) Android (10) iOS (9) Webhook (8) api (7) oauth (5) getting-started (4) การลงทะเบียนแอป (4) การแก้ปัญหา (4)
บทความที่เกี่ยวข้อง