Mosaqo API למפתחים

ממשק REST מעל אותה סביבת עבודה שאתם משתמשים בה באפליקציה. כל מה שלהלן עובד עם מפתח API יחיד וכל לקוח HTTP.

מה אפשר לעשות

• ליצור קודי QR מהרשומות שלכם — אחד בכל פעם, או עשרת אלפים מקובץ CSV.
• לשנות את היעד של קוד מודפס, בקריאה אחת, בלי להדפיס דבר מחדש.
• להוריד את הכרטיס המוגמר כקובץ PNG, SVG או PDF ולצרף אותו לרשומה ב-CRM.
• לקרוא סריקות ואנליטיקה מצרפית, מסוננות לפי כללי הפרטיות של סביבת העבודה שלכם.
• לקבל webhooks חתומים כשקודים נוצרים, מתפרסמים, משתנים או מועברים לארכיון.

התחלה מהירה

צרו מפתח במסך Bulk & API בסביבת העבודה שלכם, סמנו את ההרשאות qr:write ו-qr:read, והעתיקו את הסוד — הוא מוצג פעם אחת בלבד.

בדקו את המפתח וגלו לאיזו סביבת עבודה הוא פותח:

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

צרו קוד QR דינמי:

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" }'

אימות

שלחו את הסוד באחת משתי הדרכים. שתיהן נתמכות לאורך כל v1.

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

מפתח שייך לסביבת עבודה אחת בדיוק, ולכן הנתיבים אינם זקוקים למזהה סביבה: הנתיב /v1/public-api/qr מספיק. הצורה הישנה /v1/public-api/workspaces/{workspaceId}/qr עדיין עובדת.

אפשר לבטל מפתחות, לקבוע להם תאריך תפוגה ולהגביל אותם לרשימת כתובות IP מותרות. מפתח שנדחה על ידי הרשימה מקבל על כך הודעה מפורשת, במקום להיראות שגוי.

עימוד

הרשימות משתמשות בעימוד keyset. החזירו את pagination.nextCursor כפי שהוא; שורות לעולם אינן חוזרות ואינן נעלמות בגלל עריכה באמצע הסנכרון, וזה מה שחשוב בסנכרון לילי.

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

כדי לתשאל שינויים במקום לעבור על הכול, הוסיפו 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"
}

מגבלות קצב

כל תשובה נושאת את המכסה הנוכחית שלכם, לא רק אלה שנדחו:

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

המגבלה היא הגנה מפני שימוש לרעה, לא תוכנית: אין בה מכסה, חיוב או מסלול שדרוג.

אידמפוטנטיות

הכותרת Idempotency-Key היא רשות. שלחו אחת — כל מחרוזת ייחודית — וניסיון חוזר של אותה בקשה בדיוק בתוך 24 שעות ישחזר את התשובה המקורית במקום לפעול פעמיים. שימוש חוזר באותו מפתח עם קלט שונה מחזיר 409. בלי מפתח הבקשה פשוט רצה, ללא הגנה משחזור.

הבא

• Webhooks — קטלוג האירועים ואיך לאמת מסירה.
• מתכונים — דפוסים ל-Make, Zapier, n8n ו-CRM.
• תיעוד ה-API — כל נקודת קצה, עם קונסולה חיה.