พื้นฐานของรีเควสต์และเรสปอนส์ (JSON)

พื้นฐานของรีเควสต์

• โปรโตคอล：บังคับใช้ HTTPS (ปฏิเสธ HTTP)
• รูปแบบ：ทั้งบอดี้รีเควสต์และเรสปอนส์เป็น JSON
• ชุดอักขระ：UTF-8
• การยืนยันตัวตน：Authorization: Bearer {access_token}

เฮดเดอร์ที่จำเป็น・แนะนำ

Authorization: Bearer eyJhbGciOi...    ← จำเป็น
Content-Type: application/json          ← จำเป็นสำหรับ POST/PUT
Accept: application/json                ← แนะนำ
User-Agent: MyApp/1.2.3                 ← แนะนำ (ใช้ระบุตัวตนเมื่อติดต่อสอบถาม)
Idempotency-Key: 01HV6N3M2K...          ← แนะนำสำหรับ POST/PUT (ป้องกันการซ้ำ)

โครงสร้างพื้นฐานของเรสปอนส์

รีซอร์สเดี่ยว

{
  "id": "rcp_xyz789",
  "object": "receipt",
  "created_at": "2026-04-27T10:15:23Z",
  "store_id": "str_abc123",
  "total_amount": 3850,
  "currency": "JPY"
}

รายการ (แบบมีการแบ่งหน้า)

{
  "object": "list",
  "data": [
    { "id": "rcp_001", ... },
    { "id": "rcp_002", ... }
  ],
  "has_more": true,
  "next_cursor": "cur_xxx"
}

การแบ่งหน้า (แบบเคอร์เซอร์)

API แบบรายการใช้แบบเคอร์เซอร์ ดึงหน้าถัดไปด้วย ?limit=50&cursor={next_cursor ของครั้งก่อน}

• limit เริ่มต้น: 20, สูงสุด: 100
• ถ้า has_more: false แสดงว่าเป็นหน้าสุดท้าย
• เคอร์เซอร์มีอายุ 6 ชั่วโมง
• โดยหลักแล้วเรียงลำดับจากใหม่ไปเก่า (created_at DESC)

การกรอง

กรองด้วยควิรีพารามิเตอร์

GET /v1/receipts?store_id=str_abc&issued_after=2026-04-01&issued_before=2026-04-30

ตัวดำเนินการเปรียบเทียบที่รองรับ：
?total_amount[gte]=1000     ← 1000 ขึ้นไป
?total_amount[lt]=5000      ← น้อยกว่า 5000
?status[in]=issued,refunded ← อย่างใดอย่างหนึ่ง

รูปแบบวันที่-เวลา

• ทั้งหมดเป็นรูปแบบ ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)
• เรสปอนส์เป็นUTCเสมอ (ลงท้ายด้วย Z)
• เวลารีเควสต์สามารถส่งพร้อมไทม์โซนได้ (แปลงเป็น UTC โดยอัตโนมัติ)

การแสดงจำนวนเงิน

• จำนวนเงินเป็นจำนวนเต็มในหน่วยสกุลเงินที่เล็กที่สุด (เช่น JPY คือ 1=1 เยน, USD คือ 1=1 เซนต์)
• ไม่รวมจุดทศนิยม・เครื่องหมายคั่นหลักพัน
• สกุลเงินระบุด้วยฟิลด์ currency (ISO 4217)

รูปแบบของ ID

รีซอร์ส ID ทุกตัวมีคำนำหน้า (prefix) สามารถแยกแยะชนิดได้ในทันที

คีย์ความเป็นอิเดมโพเทนต์ (Idempotency-Key)

เมื่อระบุ Idempotency-Key เดียวกันใน POST/PUT ฝั่ง ReceiptRoller จะตรวจจับการซ้ำและคืนผลลัพธ์แรก ช่วยป้องกันการสร้างซ้ำเมื่อลองใหม่จากปัญหาเครือข่าย

• ใช้ค่าที่ไม่ซ้ำ เช่น UUID หรือ ULID
• คีย์จะถูกเก็บไว้ 24 ชั่วโมง
• ไม่แชร์ข้ามเอนด์พอยต์ที่ต่างกัน

คู่มือที่เกี่ยวข้อง

• เอนด์พอยต์และการทำเวอร์ชัน
• ตัวอย่าง API ที่ใช้บ่อย
• รหัสข้อผิดพลาดและแนวทางการรีทราย
• กลับไปที่ศูนย์ช่วยเหลือสำหรับนักพัฒนา