คู่มือการยืนยันตัวตน API

คู่มือการยืนยันตัวตน

ReceiptRoller API ใช้ OAuth 2.0 authorization code flow เมื่อนักพัฒนาฝั่งบุคคลที่สามลงทะเบียนแอป และเจ้าของธุรกิจอนุญาตการเข้าถึง นักพัฒนาจะสามารถรับโทเคนและเรียก API ได้

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

1. ล็อกอินเข้าบัญชี ReceiptRoller
2. ไปที่ รายละเอียดบัญชีธุรกิจ → เมนู ⋮ → แอปนักพัฒนา
3. คลิก สร้างแอป
4. กรอกชื่อแอป, Redirect URI และเลือกสโคป API ที่จำเป็น
5. เมื่อสร้างเสร็จ ระบบจะออก client_id และ client_secret

ขั้นตอนที่ 2: รีไดเรกต์เจ้าของธุรกิจไปยังหน้าให้สิทธิ์

เมื่อเจ้าของธุรกิจเชื่อมบัญชีเข้ากับแอป ให้รีไดเรกต์เบราว์เซอร์ไปยัง URL ต่อไปนี้:

GET https://your-domain/oauth/authorize
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=YOUR_REDIRECT_URI
    &response_type=code
    &scope=store.products.read store.orders.read
    &state=RANDOM_STATE_STRING

เจ้าของธุรกิจจะเห็นหน้ายินยอมที่แสดงชื่อแอปและสิทธิ์การเข้าถึงที่ร้องขอ สามารถเลือกอนุญาตหรือปฏิเสธได้

ขั้นตอนที่ 3: รับ authorization code

หากได้รับอนุญาต เบราว์เซอร์ของเจ้าของธุรกิจจะถูกรีไดเรกต์ไปยัง redirect_uri:

GET https://your-app.com/callback
    ?code=AUTHORIZATION_CODE
    &state=RANDOM_STATE_STRING

กรณีถูกปฏิเสธ:

GET https://your-app.com/callback
    ?error=access_denied
    &state=RANDOM_STATE_STRING

ขั้นตอนที่ 4: แลกโค้ดเป็นโทเคน

จากฝั่งเซิร์ฟเวอร์ (ไม่ใช่จากเบราว์เซอร์) ให้แลกโค้ดเป็นแอ็กเซสโทเคนด้วยคำขอ POST ต่อไปนี้:

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

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

การตอบกลับสำเร็จ (200):

{
    "accessToken": "aBcDeFgH1234567890...",
    "refreshToken": "xYzAbCdEfG098765...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "scope": "store.products.read store.orders.read"
}

ขั้นตอนที่ 5: เรียก API

ใส่แอ็กเซสโทเคนในเฮดเดอร์ Authorization แล้วส่งคำขอ:

GET /api/v1/store/products
Authorization: Bearer aBcDeFgH1234567890...
Content-Type: application/json

API จะคืนข้อมูลที่ผูกกับบัญชีธุรกิจที่อนุมัติแอป เข้าถึงได้เฉพาะข้อมูลที่อนุญาตด้วยสโคปที่อนุมัติแล้วเท่านั้น

ขั้นตอนที่ 6: รีเฟรชโทเคนที่หมดอายุ

เมื่อแอ็กเซสโทเคนหมดอายุ ให้ใช้รีเฟรชโทเคนเพื่อรับคู่โทเคนใหม่:

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

{
    "grantType": "refresh_token",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "refreshToken": "xYzAbCdEfG098765..."
}

รูปแบบการตอบกลับเหมือนขั้นตอนที่ 4 แอ็กเซสโทเคนและรีเฟรชโทเคนเดิมจะถูกยกเลิก และมีการคืนคู่ใหม่มาให้

การเพิกถอนโทเคน

หากต้องการเพิกถอนแอ็กเซสโทเคนหรือรีเฟรชโทเคน:

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

{
    "token": "โทเคนที่ต้องการเพิกถอน",
    "clientId": "YOUR_CLIENT_ID"
}

เจ้าของธุรกิจสามารถเพิกถอนการเข้าถึงของแอปได้ทุกเมื่อจากการตั้งค่าบัญชี

การตอบกลับข้อผิดพลาด

สโคปที่ใช้ได้

Store (ร้านค้า)

CRM (การจัดการความสัมพันธ์ลูกค้า)

SNS / การวิเคราะห์

แผนผังโฟลว์

┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│  แอปของคุณ    │     │ เจ้าของ       │     │  ReceiptRoller   │
│  (นักพัฒนา)   │     │ ธุรกิจ        │     │  แพลตฟอร์ม        │
└──────┬───────┘     └──────┬───────┘     └────────┬─────────┘
       │                    │                      │
       │  1. รีไดเรกต์ไปยัง /oauth/authorize        │
       │────────────────────▶│────────────────────▶│
       │                    │                      │
       │                    │  2. แสดงหน้ายินยอม    │
       │                    │◀─────────────────────│
       │                    │                      │
       │                    │  3. อนุญาต           │
       │                    │─────────────────────▶│
       │                    │                      │
       │  4. รีไดเรกต์ด้วย ?code=authorization code  │
       │◀───────────────────│◀─────────────────────│
       │                    │                      │
       │  5. POST /api/v1/auth/token               │
       │  (code + client_id + client_secret)       │
       │───────────────────────────────────────────▶│
       │                                           │
       │  6. { accessToken, refreshToken }         │
       │◀──────────────────────────────────────────│
       │                                           │
       │  7. GET /api/v1/store/products            │
       │  Authorization: Bearer {accessToken}      │
       │───────────────────────────────────────────▶│
       │                                           │
       │  8. { data: [...] }                       │
       │◀──────────────────────────────────────────│

แนวปฏิบัติที่ดีด้านความปลอดภัย

• เก็บ client_secret ไว้ที่ฝั่งเซิร์ฟเวอร์เท่านั้น ห้ามใส่ไว้ในโค้ดฟรอนต์เอนด์หรือแอปมือถือโดยเด็ดขาด
• เพื่อป้องกันการโจมตี CSRF โปรดตรวจสอบพารามิเตอร์ state เสมอ
• สำหรับแอปมือถือหรือแอปแบบ single-page โปรดใช้ PKCE (code_challenge / code_verifier)
• เก็บโทเคนไว้อย่างปลอดภัย อย่าบันทึกแอ็กเซสโทเคนลงล็อกหรือใส่ไว้ใน URL
• เพื่อหลีกเลี่ยงการหยุดชะงักของบริการ โปรดพัฒนาการรีเฟรชโทเคนก่อนที่จะหมดอายุ
• โปรดร้องขอเฉพาะสโคปที่แอปต้องใช้จริงเท่านั้น