สำหรับร้านค้า: คู่มือออกใบเสร็จดิจิทัลในแอปของตนเองและแจ้งเตือนผ่าน Webhook

ในคู่มือนี้จะอธิบายขั้นตอนตั้งแต่การลงทะเบียนแอปนักพัฒนาของ ReceiptRoller ยืนยันตัวตนด้วย OAuth เพื่อรับแอ็กเซสโทเคน จากนั้นตั้งค่า Webhook เพื่อรับอีเวนต์ใบเสร็จแบบเรียลไทม์

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

ขั้นตอนที่ 1: ลงทะเบียนแอปนักพัฒนา

1. ล็อกอินเข้า ReceiptRoller แล้วเปิดแดชบอร์ดของบัญชีธุรกิจเป้าหมาย
2. เลือก นักพัฒนา → รายการแอป จากเมนูด้านข้าง
3. คลิกปุ่ม สร้างแอป
4. กรอกรายการต่อไปนี้
   • ชื่อแอป: เช่น ชื่อบริการของตนเอง
   • Redirect URI: URL ที่ใช้รับ authorization code ของ OAuth (เช่น https://your-app.example.com/callback)
   • สโคป: เลือกสโคปที่จำเป็นสำหรับการรับใบเสร็จ (ดูด้านล่าง)
5. เมื่อสร้างเสร็จ ระบบจะออก Client ID และ Client Secret
   Client Secret จะแสดงเพียงครั้งเดียวเท่านั้น โปรดบันทึกไว้ในที่ปลอดภัยเสมอ

สโคปที่จำเป็น

เมื่อร้านค้าออกและอ้างอิงใบเสร็จให้ลูกค้าของตน จะต้องใช้สโคปต่อไปนี้

※ user.receipts.read และ user.profile.read ใช้สำหรับแอปแบบวอลเล็ตที่ลูกค้าเชื่อมบัญชี Receipt Roller ของตนเอง หากร้านออกใบเสร็จเองก็ไม่จำเป็น

ขั้นตอนที่ 2: รับแอ็กเซสโทเคนด้วย OAuth

Receipt Roller ใช้ OAuth 2.0 authorization code flow (รองรับ PKCE)

1. คำขอให้สิทธิ์

รีไดเรกต์ผู้ใช้ไปยัง URL ต่อไปนี้:

GET /oauth/authorize
  ?client_id=app_xxxxxxxxxxxxxxxx
  &redirect_uri=https://your-app.example.com/callback
  &response_type=code
  &scope=store.orders.read store.orders.write store.products.read store.customers.read
  &code_challenge=<S256 แฮช>
  &code_challenge_method=S256

2. แลก authorization code

เมื่อผู้ใช้ยินยอม ระบบจะรีไดเรกต์ไปที่ redirect_uri พร้อมแนบ ?code=xxx ให้นำโค้ดนี้ไปแลกเป็นแอ็กเซสโทเคน:

POST /api/v1/auth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "xxx",
  "code_verifier": "<PKCE code verifier>",
  "client_id": "app_xxxxxxxxxxxxxxxx",
  "client_secret": "your-client-secret",
  "redirect_uri": "https://your-app.example.com/callback"
}

3. การตอบกลับ

{
  "access_token": "...",   // อายุ: 1 ชั่วโมง
  "refresh_token": "...",  // อายุ: 30 วัน
  "token_type": "Bearer",
  "expires_in": 3600
}

คำขอ API ต่อ ๆ ไปให้แนบเฮดเดอร์ Authorization: Bearer {access_token}

ขั้นตอนที่ 3: ลงทะเบียน Webhook

เมื่อใช้ Webhook คุณจะรับการแจ้งเตือนแบบเรียลไทม์ไปยัง URL ที่กำหนด …