Mosaqo API สำหรับนักพัฒนา

REST API บน workspace เดียวกับที่คุณใช้ในแอป ทุกอย่างด้านล่างนี้ทำงานได้ด้วย API key เพียงอันเดียวกับ HTTP client ตัวใดก็ได้

สิ่งที่คุณทำได้

• สร้าง QR code จากข้อมูลของคุณเอง — ทีละอัน หรือหมื่นอันจากไฟล์ CSV
• เปลี่ยนปลายทางของโค้ดที่พิมพ์ไปแล้ว ด้วยการเรียกครั้งเดียว โดยไม่ต้องพิมพ์ใหม่
• ดาวน์โหลดการ์ดที่เสร็จแล้วเป็น PNG, SVG หรือ PDF แล้วแนบเข้ากับเรกคอร์ดใน CRM
• อ่านข้อมูลการสแกนและ analytics แบบรวม โดยกรองตามกฎความเป็นส่วนตัวของ workspace คุณ
• รับ webhook ที่ลงลายเซ็นเมื่อมีการสร้าง เผยแพร่ แก้ไข หรือเก็บเข้าคลังโค้ด

Quickstart

สร้าง key ใน Bulk & API ภายใน workspace ของคุณ ติ๊กสโคป qr:write และ qr:read แล้วคัดลอก secret ไว้ — ระบบแสดงให้เห็นเพียงครั้งเดียว

ตรวจสอบ key และดูว่ามันเปิด workspace ไหน:

curl https://api.mosaqo.app/v1/public-api/me \
  -H "Authorization: Bearer $MOSAQO_KEY"

สร้าง QR code แบบไดนามิก:

curl -X POST https://api.mosaqo.app/v1/public-api/qr \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Autumn campaign",
    "mode": "dynamic",
    "contentType": "url",
    "content": { "targetUrl": "https://example.com/autumn" }
  }'

เผยแพร่โค้ด ซึ่งเป็นขั้นที่ทำให้การเปลี่ยนเส้นทางทำงาน แล้วดึงภาพที่พร้อมพิมพ์:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/publish \
  -H "Authorization: Bearer $MOSAQO_KEY"

curl https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image?format=png&size=2048 \
  -H "Authorization: Bearer $MOSAQO_KEY" -o campaign.png

อีกหลายเดือนต่อมา เมื่อแคมเปญย้ายไปที่อื่น ให้เปลี่ยนปลายทางของโค้ดที่พิมพ์ไปแล้วโดยไม่ต้องพิมพ์ใหม่:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/destination \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/winter" }'

การยืนยันตัวตน

ส่ง secret ของคุณด้วยวิธีใดก็ได้ รองรับทั้งสองแบบตลอดอายุของ v1

Authorization: Bearer mosaqo_xxx
X-Mosaqo-API-Key: mosaqo_xxx

key หนึ่งอันผูกกับ workspace เดียวเท่านั้น พาธจึงไม่ต้องระบุ workspace id: /v1/public-api/qr ก็พอ รูปแบบเดิม /v1/public-api/workspaces/{workspaceId}/qr ยังใช้ได้อยู่

key สามารถเพิกถอน กำหนดวันหมดอายุ และจำกัดด้วย IP allow-list ได้ หาก key ถูกปฏิเสธจาก allow-list ระบบจะแจ้งไว้อย่างชัดเจน แทนที่จะทำให้ดูเหมือน key ใช้ไม่ได้

การแบ่งหน้า

รายการต่าง ๆ ใช้การแบ่งหน้าแบบ keyset ส่งค่า pagination.nextCursor กลับมาโดยไม่ต้องแก้ไข แถวจะไม่ซ้ำและไม่หายไปเพราะมีการแก้ไขข้อมูลระหว่างซิงก์ ซึ่งสำคัญมากสำหรับการซิงก์ข้ามคืน

curl "https://api.mosaqo.app/v1/public-api/qr?limit=50&cursor=$CURSOR" \
  -H "Authorization: Bearer $MOSAQO_KEY"

หากต้องการ poll เฉพาะสิ่งที่เปลี่ยนแปลงแทนการไล่ทั้งหมด ให้เพิ่ม updatedSince=2026-08-05T00:00:00Z

ข้อผิดพลาด

ทุกความล้มเหลวจะมี code ที่คงที่สำหรับแยกเงื่อนไข message ที่อ่านเข้าใจได้ และ requestId ที่ควรแจ้งเมื่อติดต่อฝ่ายสนับสนุน

{
  "error": "This API key does not have the qr:write scope.",
  "message": "This API key does not have the qr:write scope.",
  "code": "insufficient_scope",
  "details": { "required": "qr:write", "granted": ["qr:read"] },
  "requestId": "req-42"
}

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

ทุก response จะบอกโควตาคงเหลือของคุณ ไม่ใช่เฉพาะคำขอที่ถูกปฏิเสธ:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1785942718

ขีดจำกัดนี้เป็นการป้องกันการใช้งานในทางที่ผิด ไม่ใช่แพ็กเกจ จึงไม่เกี่ยวกับโควตา การเรียกเก็บเงิน หรือการอัปเกรดใด ๆ

Idempotency

Idempotency-Key เป็นตัวเลือกเสริม ส่งมาสักค่า — สตริงอะไรก็ได้ที่ไม่ซ้ำ — แล้วการส่งคำขอเดิมซ้ำภายใน 24 ชั่วโมงจะได้ response เดิมกลับไป แทนที่จะทำงานสองครั้ง การใช้ key เดิมกับข้อมูลที่ต่างออกไปจะได้ 409 หากไม่ส่ง key คำขอจะทำงานตามปกติ โดยไม่มีการป้องกันการทำซ้ำ

ขั้นถัดไป

• Webhooks — แคตตาล็อกอีเวนต์และวิธีตรวจสอบการส่ง
• สูตรการใช้งาน — รูปแบบสำหรับ Make, Zapier, n8n และ CRM
• API reference — ทุก endpoint พร้อมคอนโซลทดลองใช้งานจริง