การจำกัดอัตราการเรียก (Rate Limit) และการควบคุมปริมาณ
บทความนี้อธิบายว่า API ของ ReceiptRoller รับคำขอได้มากเพียงใด จะได้รับการตอบกลับแบบใดเมื่อถึงขีดจำกัด และวิธีควบคุมปริมาณการเรียกจากไคลเอนต์ของคุณให้อยู่ในระดับที่เหมาะสม API ของร้านค้าและบัญชีธุรกิจที่เรียกด้วยแอ็กเซสโทเคนของแอปจะอยู่ภายใต้โควตารายเดือนตามแพ็กเกจของบัญชีธุรกิจ นอกจากนี้ บางเอนด์พอยต์ เช่น การรับใบเสร็จหรือการส่งใบเสร็จจากเครื่องพิมพ์ ยังมีขีดจำกัดระยะสั้นของตัวเองด้วย
API ที่เรียกด้วยโทเคนของแอป
การเรียกเอนด์พอยต์ /api/v1/... ด้วยแอ็กเซสโทเคนที่ออกให้กับบัญชีธุรกิจ (สินค้า ยอดขาย การจอง ฯลฯ) จะถูกนับรวมในโควตารายเดือนของบัญชีธุรกิจนั้น
| แพ็กเกจ | จำนวนการเรียก API ที่รวมอยู่ต่อเดือน | ค่าแนะนำต่อนาที |
|---|---|---|
| Starter | 5,000 | 60 |
| Growth | 50,000 | 300 |
| Enterprise | 500,000 | 1,000 |
- แพ็กเกจ Basic และช่วงทดลองใช้ฟรีไม่รวมการเข้าถึง API
- หนึ่งเดือนนับตั้งแต่วันที่ 1 ถึงวันสุดท้ายของเดือนตามเวลาญี่ปุ่น
- การเรียกจากแอปของ ReceiptRoller เองจะไม่ถูกนับ นับเฉพาะแอปของบุคคลภายนอกเท่านั้น
- การเรียกจะไม่ถูกหยุดเมื่อถึงโควตา และไม่มีค่าใช้จ่ายสำหรับการเรียกที่เกินโควตา เมื่อบัญชีธุรกิจใช้ถึง 80% และ 100% ของโควตา ระบบจะแจ้งเจ้าของบัญชีทางอีเมล
- คำขออาจถูกจำกัดเมื่อบัญชีธุรกิจเรียกเกินสองเท่าของโควตารายเดือน หรือส่งคำขอเกินค่าแนะนำต่อนาที
- การตอบกลับจะไม่มี header ด้านการจำกัดอัตรา เช่น
X-RateLimit-Limit,X-RateLimit-RemainingหรือX-RateLimit-Reset - เอนด์พอยต์โทเคน
POST /api/v1/auth/tokenไม่มีขีดจำกัดสำหรับการแลก authorization code (authorization_code) หรือรีเฟรชโทเคน (refresh_token)
เจ้าของบัญชีธุรกิจสามารถดูจำนวนการเรียกของเดือนนี้แยกตามวันและตามแอปได้ที่หน้าการใช้งานแพ็กเกจ ดูรายละเอียดที่ วิธีอ่านหน้าการใช้งานแพ็กเกจ (ภาษาอังกฤษ)
เอนด์พอยต์ที่มีขีดจำกัดของตัวเอง
เอนด์พอยต์ต่อไปนี้จำกัดจำนวนคำขอในช่วง 1 นาทีล่าสุด (สำหรับอีเมลคือ 1 ชั่วโมงล่าสุด) โดยนับตาม IP address ของไคลเอนต์ หรือตามการจับคู่ในคอลัมน์ "นับตาม"
| เอนด์พอยต์ | ขีดจำกัด | นับตาม |
|---|---|---|
POST /api/v1/devices/printer/receipts, POST /api/v1/devices/printer/receipts/{token}/ad-printed | 300 ครั้งต่อนาที | IP address |
GET /api/v1/apps/{shopId}/ads | 30 ครั้งต่อนาที | IP address |
GET /api/v1/receipt-ad | 60 ครั้งต่อนาที | IP address |
GET /api/v1/terminals/{publicTerminalId}/last-receipt, GET /api/v1/rx/{claimToken} | 10 ครั้งต่อนาที | IP address และเทอร์มินัล (หรือโทเคน) |
POST /api/v1/terminals/{publicTerminalId}/claim, POST /api/v1/rx/{claimToken}/claim | 3 ครั้งต่อนาที (นับรวมใน 10 ครั้งต่อนาทีข้างต้นด้วย) | IP address และเทอร์มินัล (หรือโทเคน) |
POST /api/v1/user/terminals/{publicTerminalId}/claim, POST /api/v1/user/rx/{claimToken}/claim | 3 ครั้งต่อนาที | IP address และเทอร์มินัล (หรือโทเคน) |
POST /api/v1/rx/{claimToken}/claim แบบส่งทางอีเมล | 3 ครั้งต่อชั่วโมง | อีเมลปลายทาง |
การลงเวลาเข้าออกงาน (POST /api/v1/stores/{storeId}/timecards/punch) ไม่มีการจำกัดอัตรา แต่หากใส่ PIN ผิดติดกัน 5 ครั้งสำหรับบุคคลเดียวกัน การลงเวลาของบุคคลนั้นจะถูกล็อก 15 นาที และการเรียกจะได้ 429 พร้อม {"error": "pin_locked", "message": "...", "lockedUntil": "..."}
ขั้นตอนการลงชื่อเข้าใช้ของแอปทางการของ ReceiptRoller (การแลก ID token การสร้างบัญชีแบบไม่ระบุตัวตน) ก็มีขีดจำกัดของตัวเองเช่นกัน แต่ไม่มีผลกับการแลก authorization code และรีเฟรชโทเคนที่แอปของนักพัฒนาใช้
การตอบกลับเมื่อถึงขีดจำกัด
สถานะจะเป็น 429 Too Many Requests เสมอ ส่วนที่เหลือของการตอบกลับขึ้นอยู่กับขีดจำกัดที่ถึง
- ขีดจำกัดของบัญชีธุรกิจสำหรับการเรียกด้วยโทเคนของแอป: body เป็น JSON ที่มี
errorและmessageพร้อม headerRetry-Afterโดยerrorเป็นrate_limitedเมื่อเกินค่าแนะนำต่อนาที (Retry-After: 60) หรือmonthly_limit_exceededเมื่อเกินสองเท่าของโควตารายเดือน (Retry-Afterคือจำนวนวินาทีจนถึงต้นเดือนถัดไปตามเวลาญี่ปุ่น) - การส่งจากเครื่องพิมพ์ (
/api/v1/devices/printer/...),GET /api/v1/apps/{shopId}/adsและขีดจำกัด 3 ครั้งต่อนาทีของแต่ละ.../claim: มี headerRetry-After: 60และ body เป็นข้อความToo many requests. Please try again in a minute. - ขีดจำกัดเฉพาะเอนด์พอยต์อื่น ๆ (
last-receipt,GET /api/v1/rx/{claimToken},GET /api/v1/receipt-ad, 10 ครั้งต่อนาทีของ claim และ 3 ครั้งต่อชั่วโมงของอีเมล): ได้429ที่ไม่มี body และไม่มีRetry-After
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
{ "error": "rate_limited", "message": "Too many requests for this business account. Try again in a minute." }
ให้ตรวจจับ 429 จาก status code ก่อน แล้วจึงใช้ error (หากมี) เพื่อแยกแยะกรณี
การควบคุมปริมาณการเรียกให้เหมาะสม
- งานจำนวนมากให้ส่งทีละคำขอตามลำดับ อย่ายิงคำขอหลายร้อยรายการพร้อมกันด้วย
Promise.allหรือวิธีที่คล้ายกัน - ใช้เอนด์พอยต์แบบรายการแทนการดึงทีละรายการ เช่น รายการสินค้า
GET /api/v1/productsจะส่งสินค้าทั้งหมดกลับมาในการตอบกลับครั้งเดียว การซิงก์จึงดึงเพียงครั้งเดียวแล้วจับคู่ในระบบของคุณ - แคชข้อมูลที่ไม่ค่อยเปลี่ยน เช่น ข้อมูลร้านค้าและข้อมูลหลักของสินค้า
- ใช้ Webhook แทนการ polling เพื่อติดตามการเปลี่ยนแปลง (ภาพรวมของ Webhook)
แนวทางการลองเรียกใหม่
429ที่มีrate_limitedหรือ429อื่น ๆ: หากมีRetry-Afterให้รอตามจำนวนวินาทีนั้นแล้วส่งใหม่ หากไม่มี ให้รอประมาณ 1 นาที เนื่องจากขีดจำกัดเหล่านั้นนับช่วง 1 นาทีล่าสุด429ที่มีmonthly_limit_exceeded: อย่าลองใหม่อัตโนมัติ การเรียกจะถูกรับอีกครั้งตั้งแต่ต้นเดือนถัดไป หรือเมื่อบัญชีธุรกิจเปลี่ยนไปใช้แพ็กเกจที่มีโควตามากขึ้น503และ5xxอื่น ๆ, timeout และข้อผิดพลาดในการเชื่อมต่อ: ลองใหม่สองสามครั้ง โดยเพิ่มเวลารอเป็นสองเท่าในแต่ละครั้งและเพิ่ม jitter แบบสุ่ม400,401,403,404: การส่งคำขอเดิมซ้ำจะได้ผลเหมือนเดิม สำหรับ401ให้รีเฟรชโทเคนแล้วลองใหม่หนึ่งครั้ง- การส่ง
POSTสำหรับสร้างข้อมูลซ้ำหลังเกิด timeout อาจทำให้เกิดข้อมูลซ้ำ เนื่องจากไม่มี headerIdempotency-Keyแบบทั่วไป ให้ตรวจสอบว่ารายการถูกสร้างแล้วหรือยัง (เช่น ดูในรายการ) ก่อนส่งใหม่
async function callWithRetry(send, maxAttempts = 5) {
for (let attempt = 1; ; attempt++) {
const response = await send();
const retryable = response.status === 429 || response.status >= 500;
if (!retryable || attempt === maxAttempts) return response;
const retryAfter = Number(response.headers.get("Retry-After"));
if (response.status === 429 && retryAfter > 3600) return response; // ถึงโควตารายเดือนแล้ว: หยุดลองใหม่
const backoff = Math.min(2 ** attempt, 60) * (0.75 + Math.random() * 0.5);
const waitSeconds = response.status === 429 ? (retryAfter || 60) : backoff;
await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
}
}
คู่มือที่เกี่ยวข้อง
-
วิธีใช้ Reservations APIคู่มือ Reservations API ของ ReceiptRoller (/api/v1/reservations) อธิบายการทำ CRUD และอัปเดตสถานะการจอง การดึง・สร้าง・สร้างชุดของช่องจอง (สล็อต) การดึงข้อมูลโต๊ะ (โต๊ะ・ห้องส่วนตัว・เคาน์เตอร์) ที่ลงทะเบียนไว้ในเลย์เอาต์ร้าน และสถิติการจอง
-
วิธีใช้ In-Store Media Display API (Display API)ภาพรวมของ In-Store Android Display API ของ ReceiptRoller (/api/v1/displays/*) และขั้นตอนการจับคู่・heartbeat・การดึงเพลย์ลิสต์・การรายงานผลการเล่น คู่มือเริ่มต้นสำหรับสร้างแอปเล่นมีเดียลูปบนเครื่อง Android แบบ POS ควบคู่หรือเครื่องไซเนจของร้าน
-
การเชื่อมต่อข้อมูลการซื้อและใบเสร็จอธิบายโครงสร้างข้อมูลการซื้อและใบเสร็จที่ ReceiptRoller จัดการ วิธีการดึงข้อมูล สโคปที่เกี่ยวข้อง Webhook และกรณีการใช้งานที่พบบ่อย
-
สารบัญความช่วยเหลือสำหรับนักพัฒนาสารบัญความช่วยเหลือสำหรับนักพัฒนา ReceiptRoller รวบรวมตั้งแต่การสมัครเป็นนักพัฒนา การลงทะเบียนแอปพลิเคชัน การยืนยันตัวตน OAuth และสโคป คู่มือการพัฒนา (แอปวอลเล็ต, Webhook สำหรับร้านค้า, Survey API) คู่มือแยกตามโดเมนข้อมูล การใช้งานและความปลอดภัย คอมมูนิตี ไปจนถึงการแก้ปัญหา
-
ดึงรายการบัญชีธุรกิจ・ร้านค้า・เครื่อง POSคู่มือสรุปขั้นตอนการดึงรายการบัญชีธุรกิจที่ผู้ใช้สังกัด ร้านค้าภายใต้บัญชีนั้น และเครื่อง POS ของแต่ละร้านผ่าน REST API จากแอปมือถือ/แอปเซิร์ฟเวอร์ของ ReceiptRoller