List Sales Orders

ดึงรายการคำสั่งขาย (Sales Orders) ที่ผู้ใช้งานมีสิทธิ์เข้าถึง

Endpoint นี้เหมาะสำหรับ:

• สร้างรายงานยอดขาย
• ซิงค์ข้อมูลเข้าสู่ Data Warehouse
• เชื่อมต่อระบบ BI เช่น Power BI, Tableau หรือ Looker Studio
• สร้าง Dashboard และระบบวิเคราะห์ข้อมูลภายนอก

Required Scope

read:sales

Access Token ต้องได้รับ Scope read:sales มิฉะนั้นระบบจะปฏิเสธคำขอ

---

Endpoint

GET /api/partner/v1/sales

Request Headers

Authorization: Bearer <access_token>

---

Query Parameters

---

Filtering by Date Range

ใช้ from และ to เพื่อจำกัดช่วงเวลาที่ต้องการดึงข้อมูล

ข้อจำกัด

• ดึงข้อมูลย้อนหลังได้ สูงสุด 30 วันจากวันปัจจุบัน เท่านั้น — from ที่เก่ากว่านี้จะได้รับ 400 invalid_request
• ช่วง from ถึง to ต้องไม่เกิน 30 วัน — หากส่ง range เกินนี้จะได้รับ 400 invalid_request
• หากไม่ส่ง from: ระบบใช้ 30 วันก่อนหน้า to อัตโนมัติ
• หากไม่ส่ง to: ระบบใช้วันและเวลาปัจจุบัน (UTC) อัตโนมัติ

ตัวอย่าง:

GET /api/partner/v1/sales?from=2026-06-01&to=2026-06-15

จะคืนรายการที่มี order_date อยู่ในช่วงวันที่ 1–15 มิถุนายน 2026

---

Filtering by Branch

สามารถระบุหลายสาขาได้

ตัวอย่าง:

GET /api/partner/v1/sales?branch_id=uuid1&branch_id=uuid2

ระบบจะคืนเฉพาะรายการที่อยู่ในสาขาที่ระบุ

Branch Access Enforcement

ทุก Access Token จะมีรายการสาขาที่ได้รับอนุญาต (allowed_branch_ids)

หากส่ง branch_id ที่ไม่มีสิทธิ์เข้าถึง ระบบจะไม่คืนข้อมูลของสาขาดังกล่าว

ผลลัพธ์สุดท้ายจะเป็น Intersection ระหว่าง:

Requested Branches
Allowed Branches in Token

ตัวอย่าง:

Token Allowed:
- Branch A
- Branch B

Request:
- Branch B
- Branch C

Result:
- Branch B

---

Filtering by Status

รองรับสถานะดังต่อไปนี้

ตัวอย่าง:

GET /api/partner/v1/sales?status=COMPLETED

---

Pagination

Endpoint นี้ใช้ Cursor-based Pagination เพื่อรองรับข้อมูลจำนวนมาก

ตัวอย่าง Request:

GET /api/partner/v1/sales?limit=100

ตัวอย่าง Response:

{
  "pagination": {
    "next_cursor": "eyJpZCI6IjEyMyJ9",
    "has_more": true,
    "limit": 100
  }
}

หาก has_more เป็น true ให้เรียก Request ถัดไปโดยใช้ next_cursor

GET /api/partner/v1/sales?cursor=eyJpZCI6IjEyMyJ9

Important

ค่า Cursor เป็น Opaque Value

Partner ไม่ควรอ่าน แก้ไข หรือสร้าง Cursor เอง

ควรส่งค่าที่ได้รับจาก API กลับมาตรง ๆ เท่านั้น

---

Example Request

curl -X GET \
  "https://<host>/api/partner/v1/sales?from=2026-06-01&to=2026-06-30&limit=50" \
  -H "Authorization: Bearer <access_token>"

---

Example Response

{
  "data": [
    {
      "id": "4e3509ea-6e79-4243-b861-2d6d96e22af3",
      "order_number": "ORD493736",
      "branch_id": "b1f85720-71cf-420e-a584-e36b75d3fd20",
      "customer_id": null,
      "order_date": "2026-06-15T03:22:16.709Z",
      "status": "COMPLETED",
      "order_type": "DINE_IN",
      "subtotal": "120",
      "discount_amount": "0",
      "tax_amount": "7.85",
      "service_charge_amount": "0",
      "total_amount": "120",
      "paid_amount": "120",
      "refunded_amount": "0",
      "payment_status": "PAID",
      "created_at": "2026-06-15T03:22:16.709Z",
      "updated_at": "2026-06-15T03:22:16.709Z"
    }
  ],
  "pagination": {
    "next_cursor": "...",
    "has_more": true,
    "limit": 50
  }
}

---

SalesOrder Object

Monetary Fields

ฟิลด์เกี่ยวกับจำนวนเงินทั้งหมดถูกส่งกลับในรูปแบบ Decimal String

ตัวอย่าง:

{
  "subtotal": "120",
  "tax_amount": "7.85",
  "total_amount": "127.85"
}

เหตุผลที่ใช้ String แทน Number คือเพื่อป้องกันปัญหาความคลาดเคลื่อนของ Floating Point ในแต่ละภาษาโปรแกรม

Partner ควรใช้ Decimal Library หรือ Big Number Library ในการคำนวณทางการเงิน

Order Types

Payment Status

Timestamp Format

ฟิลด์วันที่และเวลาใช้มาตรฐาน ISO 8601 (UTC)

ตัวอย่าง:

2026-06-15T03:22:16.709Z

Partner ควรแปลงเป็น Time Zone ที่ต้องการก่อนนำไปแสดงผล

---

Sync Best Practice

สำหรับการดึงข้อมูลจำนวนมาก แนะนำให้:

1. API ดึงข้อมูลย้อนหลังได้สูงสุด 30 วันจากวันปัจจุบัน — กำหนดช่วง from และ to ไม่เกิน 30 วันต่อ request
2. ใช้ limit=200 ซึ่งเป็นค่าสูงสุดที่รองรับ เพื่อลดจำนวน request
3. ดึงข้อมูลต่อเนื่องผ่าน Cursor จนกว่า has_more จะเป็น false
4. สำหรับ Real-time Sync ใช้ Webhook (sales.order.created, sales.order.completed ฯลฯ) แทนการ Poll ซ้ำ เนื่องจาก API ไม่รองรับ filter ด้วย updated_at

วิธีนี้ช่วยลดปริมาณข้อมูลที่ต้องดึงซ้ำและเพิ่มประสิทธิภาพในการซิงค์ข้อมูลระยะยาว