Base URL และการจำกัดอัตราการเรียก

endpoint อยู่ที่ไหน และเรียกได้กี่ครั้งต่อนาที

Base URL

ทุก path ในคู่มือนี้อ้างอิงจาก

text

{ABSERP_API_URL}/openapi/v1

{ABSERP_API_URL} คือ origin ของ ABSERP API ในระบบของคุณ หมายถึง scheme, host และ port เท่านั้น ไม่มี path ต่อท้าย เป็น origin เดียวกับที่เว็บแอปเรียกใช้ แต่ไม่ใช่สตริงเดียวกัน เพราะ REST API ภายในของเว็บแอปอยู่ใต้ {ABSERP_API_URL}/api/v1/… ขณะที่ Open API ติดตั้งอยู่บน origin ตรง ๆ ที่ {ABSERP_API_URL}/openapi/v1/… หากค่าที่ได้รับมาลงท้ายด้วย /api ให้ตัดส่วนนั้นออก

ควรเก็บไว้ในไฟล์ตั้งค่า ไม่ควรเขียนฝังในโค้ด เพื่อให้การย้ายระหว่างสภาพแวดล้อมเป็นเพียงการแก้ค่าตั้งค่า

bash

ABSERP_API_URL="https://api.abserp.com"
ABSERP_API_KEY="absk_your_api_key_here"

curl -X GET "$ABSERP_API_URL/openapi/v1/contacts?limit=10" \
  -H "Authorization: Bearer $ABSERP_API_KEY"

ดังนั้น GET /contacts ในคู่มือนี้หมายถึง GET {ABSERP_API_URL}/openapi/v1/contacts

คำนำหน้า /openapi/v1 เป็นส่วนหนึ่งของสัญญาการใช้งาน หากในอนาคตมีการเปลี่ยนแปลงที่กระทบผู้ใช้เดิม จะออกเป็น /openapi/v2 ควบคู่กันไป ไม่ใช่การเปลี่ยน v1 แบบเงียบ ๆ

การจำกัดอัตราการเรียก

60 ครั้งต่อนาทีต่อคีย์ นับแบบ fixed window ขนาดหนึ่งนาที

ทุก response จะบอกสถานะของ window ปัจจุบัน

Header	ความหมาย
`X-RateLimit-Limit`	จำนวน request ที่อนุญาตต่อ window ปัจจุบันคือ `60`
`X-RateLimit-Remaining`	จำนวน request ที่เหลือใน window นี้

เมื่อใช้ครบ ระบบจะตอบ 429 Too Many Requests พร้อม header Retry-After ที่บอกจำนวนวินาทีจนกว่า window จะรีเซ็ต

http

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 24

json

{
  "statusCode": 429,
  "errorCode": "OpenAPIRateLimitExceeded",
  "errorMessage": "เรียกใช้งานถี่เกินไป กรุณาลองใหม่อีกครั้ง"
}

อยู่ในโควตาอย่างไร

รอตามค่า Retry-After ค่านี้แม่นยำ การหยุดรอเท่าจำนวนวินาทีที่ระบุเพียงพอเสมอ
เฝ้าดู X-RateLimit-Remaining และชะลอความเร็วก่อนที่จะเหลือศูนย์ ไม่ควรใช้ 429 เป็นตัวควบคุมจังหวะ
ทยอยส่งงานค้าง งานกลางคืนที่ต้องออกใบกำกับภาษี 500 ฉบับ ต้องใช้เวลาส่งแบบเว้นจังหวะราวเก้านาที ไม่ใช่ retry อยู่เก้านาที ให้กระจายส่งประมาณหนึ่ง request ต่อวินาที แล้วคุณจะไม่พบ 429 เลย
อย่า retry งานเขียนแบบไม่ตรวจสอบ 429 หมายความว่า request ถูกปฏิเสธก่อนที่จะทำงานใด ๆ จึง retry ได้อย่างปลอดภัย แต่การ timeout ไม่ใช่ 429 ดูหัวข้อถัดไป
โควตานับแยกตามคีย์ การแยกระบบเดียวออกเป็นสองคีย์เพื่อเพิ่มโควตาจะทำให้ถูกจำกัดที่ระดับองค์กรแทน หากคุณต้องใช้โควตาสูงกว่านี้จริง ๆ กรุณาแจ้งเรา

Timeout และการ retry

ถ้างานเขียน timeout คุณจะไม่ทราบว่าระบบทำรายการไปแล้วหรือไม่ อย่า retry POST ที่สร้างเอกสารซ้ำแบบทันที เพราะอาจได้เอกสารสองฉบับ ให้ทำแบบนี้แทน

เรียก endpoint รายการด้วยตัวกรองที่แคบ (เช่น GET /sales/documents?type=IV&fromDate=…&toDate=…&contactId=…)
ตรวจว่าเอกสารของคุณถูกสร้างไปแล้วหรือยัง
สร้างใหม่เฉพาะกรณีที่ยังไม่มี

การอ่าน (GET) สามารถ retry ได้อย่างอิสระ

ขั้นตอนถัดไป

อ่านต่อที่ ข้อผิดพลาดและการแบ่งหน้า