วิธีใช้ Transactions API (ฟิลด์รวม POS + OMS)

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

Transactions API ของ ReceiptRoller เป็นเอนด์พอยต์อ่านอย่างเดียวที่รวมยอดขายที่แคชเชียร์ (POS ทรานแซกชัน) และคำสั่งซื้อในระบบจัดการการขาย (OMS) ไว้ในฟีดเดียว ครอบคลุมยูสเคส "อยากเห็นธุรกรรมทั้งหมดของบัญชีธุรกิจในหน้าจอเดียว"

ทำไมต้องเป็นเอนด์พอยต์แยก

• Sales API รวมยอด POS ทรานแซกชันแล้วคืน KPI／กราฟ
• Orders API ให้บริการ CRUD ของคำสั่งซื้อ OMS
• ทั้งสองอย่างเห็นเพียงโลกฝั่งเดียว หากต้องการ "รายการธุรกรรมทุกช่องทาง" กรุณาใช้ API นี้

หมายเหตุ: Transactions API เป็นแบบอ่านอย่างเดียว การเขียนกรุณาทำผ่าน Orders API (OMS) หรือผ่านการเชื่อมต่อ POS แต่ละตัว

เอนด์พอยต์

GET /api/v1/transactions
  ?organizationId={organizationId}
  &storeId={storeId}                 (ตัวเลือก, กรองด้วยร้านค้า)
  &since=2026-05-01T00:00:00Z        (ตัวเลือก, ค่าเริ่มต้น: 30 วันก่อน)
  &until=2026-06-01T00:00:00Z        (ตัวเลือก, ค่าเริ่มต้น: ปัจจุบัน)
  &source=all|pos|oms                (ตัวเลือก, ค่าเริ่มต้น: all)
  &page=1
  &pageSize=100                      (สูงสุด 500)
Authorization: Bearer {access_token}

สโคปที่จำเป็น: store.orders.read หรือ sales.read อย่างใดอย่างหนึ่ง

ตัวอย่างเรสปอนส์

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "window": {
    "since": "2026-05-01T00:00:00Z",
    "until": "2026-06-01T00:00:00Z"
  },
  "transactions": [
    {
      "id": "pos:term-001:tx-9001",
      "source": "pos",
      "occurredAt": "2026-05-31T18:22:14Z",
      "storeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "channel": "POS",
      "status": "Completed",
      "amounts": { "subtotal": 960, "tax": 96, "shipping": 0, "discount": 0, "total": 1056 },
      "itemCount": 2,
      "customer": null,
      "links": {
        "posTransactionId": "tx-9001",
        "posTerminalId": "term-001",
        "omsOrderId": null
      }
    },
    {
      "id": "oms:ord-001",
      "source": "oms",
      "occurredAt": "2026-05-31T09:10:00Z",
      "storeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "channel": "Web",
      "status": "Delivered",
      "amounts": { "subtotal": 1140, "tax": 114, "shipping": 500, "discount": 0, "total": 1754 },
      "itemCount": 3,
      "customer": { "name": "佐藤花子", "email": "hanako@example.com" },
      "links": {
        "posTransactionId": null,
        "posTerminalId": null,
        "omsOrderId": "ord-001"
      }
    }
  ],
  "page": 1,
  "pageSize": 100,
  "totalCount": 247,
  "totalPages": 3
}

วิธีอ่านฟิลด์

• source — "pos" หรือ "oms" บอกว่าธุรกรรมมาจากโลกฝั่งไหน
• occurredAt — POS คือวันเวลาที่เกิดธุรกรรม, OMS คือวันเวลาที่สร้าง เรียงปนกันแบบ DESC ไว้แล้ว
• channel — POS เป็น "POS" เสมอ, OMS เป็น Web / Phone / Manual / Marketplace ฯลฯ
• status — POS เป็น Completed / Voided, OMS เป็น Pending / Confirmed / Processing / Shipped / Delivered / Cancelled / Refunded
• customer — POS เป็น null, OMS หากมีการกรอกจะมีชื่อ・อีเมล
• links — ID ที่ใช้เมื่อต้องการดึงรายละเอียดแบบ follow-up แถว POS จะฝัง posTransactionId + posTerminalId, แถว OMS จะฝัง omsOrderId

ข้อจำกัด

• ช่วงเวลาดึงได้สูงสุด 365 วัน หากเกินจะได้ 400 Bad Request
• ดึงภายในและ merge สูงสุด 5000 รายการต่อ source สำหรับเทนันต์ที่มีช่วงเวลายาวหรือธุรกรรมจำนวนมากเกินนั้น กรุณากรองด้วย since / until…