สำหรับแอปวอลเล็ต: คู่มือดึงใบเสร็จของผู้ใช้ผ่าน OAuth

เป็นคู่มือนักพัฒนาสำหรับร้านค้า/แบรนด์ที่มีแอป iOS, แอป Android หรือ LINE Mini App ของตนเอง
เมื่อใช้การยืนยันตัวตน OAuth และ API ของ ReceiptRoller คุณจะสามารถดึงใบเสร็จดิจิทัลที่ออกจากร้านของคุณ โดยได้รับความยินยอมจากผู้ใช้ แล้วนำมาแสดงในแอปของตนเองได้

กรณีการใช้งาน

ยกตัวอย่างเช่น สามารถใช้งานได้ดังนี้

• ร้านสะดวกซื้อแสดง "ประวัติการซื้อ" ในแอปของตนเอง
• ร้านขายยาแสดง "ใบเสร็จของฉัน" ใน LINE Mini App
• แบรนด์ EC แสดงสรุปการใช้จ่ายรายเดือนบนแดชบอร์ดในแอป Android
• ส่งข้อมูลใบเสร็จไปยังเซิร์ฟเวอร์ของตนผ่าน Webhook พร้อมกับการซื้อเสร็จสิ้น

ภาพรวมของกลไก

ผู้ใช้ → แอปของตนเอง → หน้ายินยอม OAuth (ReceiptRoller)
                              ↓
                        ออกแอ็กเซสโทเคน
                              ↓
              แอปของตนเอง → Receipt API → ดึงใบเสร็จดิจิทัล

แอปของตนเองรับแอ็กเซสโทเคนผ่านโฟลว์ OAuth 2.0 ของ ReceiptRoller
เมื่อใช้โทเคนที่ได้เรียก API จะได้รับใบเสร็จที่ผู้ใช้รายนั้นได้รับที่ร้านของคุณกลับมา

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

1. ล็อกอินเข้าพอร์ทัลนักพัฒนาของ ReceiptRoller
2. ออก Client ID และ Secret จาก "ลงทะเบียนแอป"
3. ตั้งค่า redirect_uri (ปลายทางรีไดเรกต์หลังให้สิทธิ์)

ขั้นตอนที่ 2: พัฒนา OAuth authorization code flow

2-1. รับ authorization code

นำผู้ใช้ไปยัง URL ต่อไปนี้ในเบราว์เซอร์

GET /oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &scope=user.receipts.read user.spending.read
  &state=RANDOM_STRING

เมื่อผู้ใช้แตะ "อนุญาต" ในหน้ายินยอมของ ReceiptRoller จะมี authorization code ส่งกลับมาที่ redirect_uri

YOUR_REDIRECT_URI?code=AUTH_CODE&state=RANDOM_STRING

2-2. แลกโค้ดเป็นโทเคน

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

{
  "grantType": "authorization_code",
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "code": "AUTH_CODE",
  "redirectUri": "YOUR_REDIRECT_URI"
}

การตอบกลับ:

{
  "accessToken": "eyJ...",
  "refreshToken": "def50200...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "user.receipts.read user.spending.read"
}

2-3. รีเฟรชโทเคน

เมื่อแอ็กเซสโทเคนหมดอายุแล้วให้รีเฟรช

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

{
  "refreshToken": "def50200...",
  "clientId": "YOUR_CLIENT_ID"
}

ขั้นตอนที่ 3: ดึงใบเสร็จ

แนบเฮดเดอร์ Authorization: Bearer {access_token} ในทุกคำขอ API

รายการใบเสร็จ (รองรับตัวกรองรายเดือน)

GET /api/v1/user/receipts?year=2026&month=4
Authorization: Bearer {access_token}

รายละเอียดใบเสร็จ (รวมรายการและข้อมูลร้าน)

GET /api/v1/user/receipts/{id}
Authorization: Bearer {access_token}

สรุปการใช้จ่ายรายเดือน

GET /api/v1/user/receipts/summary?year=2026&month=4
Authorization: Bearer {access_token}

สโคป: user.spending.read
คืนค่ารายละเอียดตามหมวดหมู่ การเปร…