ดึงรายการบัญชีธุรกิจ・ร้านค้า・เครื่อง POS

วัตถุประสงค์ของคู่มือนี้

คู่มือนี้สรุปวิธีใช้ API เมื่อต้องการแสดงรายการบัญชีธุรกิจ・ร้านค้า・เครื่อง POSของ ReceiptRoller จากแอปมือถือหรือแอปเซิร์ฟเวอร์ ยูสเคสที่พบบ่อยมีดังนี้

• หน้าจอให้ผู้ใช้เลือกว่า「จะดำเนินการในฐานะบัญชีธุรกิจใด」ภายในแอป
• หน้าจอที่แสดงรายการร้านค้าภายใต้บัญชีธุรกิจที่เลือก เพื่อสลับรายงานหรือเป้าหมายการดำเนินการ
• หน้าจอที่แสดงรายการเครื่อง POS ของร้านที่เลือก เพื่อเลือกเป้าหมายสำหรับกระทบยอดธุรกรรมหรือการเชื่อม QR ของเครื่อง
• แอปธุรกิจที่ผู้ใช้คนเดียวเข้าถึงข้ามหลายบัญชีธุรกิจ

ข้อกำหนดเบื้องต้น

• ลงทะเบียนแอปพลิเคชันในแดชบอร์ดนักพัฒนาเรียบร้อยแล้ว
• ได้รับaccess token ที่ผูกกับผู้ใช้ผ่าน OAuth 2.0 authorization code flow เรียบร้อยแล้ว（กรณีรองรับหลายบัญชีธุรกิจ ให้ปิดเช็กบ็อกซ์「ผูกโทเคนกับบัญชีธุรกิจเดียวตอนอนุมัติ」ในการตั้งค่าแอป — รายละเอียดดูที่ คู่มือสำหรับแอปมือถือเนทีฟ）
• Base URL: https://receiptroller.io

1. ดึงรายการบัญชีธุรกิจที่ผู้ใช้สังกัด

ก่อนอื่น ดึงบัญชีธุรกิจที่ผู้ใช้ปัจจุบันเป็นสมาชิกอยู่

GET /api/v1/me/organizations
Authorization: Bearer {access_token}

พารามิเตอร์คิวรี（ไม่บังคับ）

• page — หมายเลขหน้า（เริ่มที่ 1, ค่าเริ่มต้น 1）
• pageSize — จำนวนต่อหน้า（ค่าเริ่มต้น 100, สูงสุด 1000）

ตัวอย่างการตอบกลับ

{
  "organizations": [
    {
      "id": "a04507de-043a-4b47-b0a3-6204562f6e20",
      "name": "株式会社レシートローラー",
      "role": "Owner"
    },
    {
      "id": "7c2e0e9b-1f3a-4c6d-8a01-2b9f4d5e6c00",
      "name": "サンプル小売株式会社",
      "role": "Member"
    }
  ],
  "page": 1,
  "pageSize": 100,
  "totalCount": 2,
  "totalPages": 1
}

ข้อควรทราบ

• id คือ ID ของบัญชีธุรกิจ（UUID）ใช้ค่านี้ต่อในคำขอถัดไปได้เลย
• role คือบทบาทสิทธิ์ของผู้ใช้นั้น（Owner / Member / ProductManager ฯลฯ）
• เมื่อ totalPages มากกว่า 2 ให้เลื่อน page ไปดึงจนครบทุกรายการ — จุดสำคัญคือฝั่งแอปมือถืออย่าแสดงแค่หน้าแรกแล้วจบ

2. ดึงรายการร้านค้าภายใต้บัญชีธุรกิจ

ใช้ id ที่ได้จากขั้นตอนที่ 1 เพื่อดึงรายการร้านค้า

GET /api/v1/me/organizations/{organizationId}/stores
Authorization: Bearer {access_token}

พารามิเตอร์คิวรี（ไม่บังคับ）

• includeDeleted — จะรวมร้านค้าที่ลบแล้วหรือไม่（ค่าเริ่มต้น false）โดยทั่วไปไม่ต้องระบุ

ตัวอย่างการตอบกลับ

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "role": "Owner",
  "stores": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "渋谷店",
      "storeType": "Retail",
      "primaryCategory": "コーヒーショップ",
      "status": "Active",
      "isDeleted": false,
      "isPosConnected": true,
      "address": {
        "country": "JP",
        "prefecture": "東京都",
        "city": "渋谷区",
        "line1": "宇田川町1-1",
        "line2": "",
        "postalCode": "150-0042",
        "latitude": 35.6595,
        "longitude": 139.7005
      },
      "phone": "03-1234-5678",
      "websiteUrl": "https://example.com/shibuya",
      "updatedAt": "2026-05-30T12:34:56Z"
    }
  ],
  "totalCount": 1
}

ข้อควรทราบ

• id คือ ID ของร้านค้า ส่งเป็น storeId ให้กับ API รายงาน เช่น /api/v1/sales/*
• หากผู้ใช้ที่เรียกไม่ได้เป็นสมาชิกของบัญชีธุรกิจนั้น จะได้ 403 Forbidden
• includeDeleted=true จะรวมร้านค้าที่ลบแล้วด้วย แต่ในแอปทั่วไปอย่าใส่（มิฉะนั้นอาจเผลอแสดงร้านที่ปิดไปแล้ว）

3. ดึงรายการเครื่อง POS ภายใต้ร้านค้า

ใช้ id ของร้านค้าที่ได้จากขั้นตอนที่ …