מתכוני אינטגרציה

ארבעה דפוסים מכסים כמעט כל אינטגרציה שאנחנו רואים. כל אחד מהם הוא קומץ קריאות, והם מתחברים זה לזה.

הפניה מחדש של קוד מודפס

הסיבה שרוב הצוותים ניגשים ל-API מלכתחילה. קוד על אריזה, על מדבקה או על כרזה ממשיך לעבוד בזמן שהקמפיין שמאחוריו עובר.

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

בקוד מפורסם השינוי נכנס לתוקף מיד — אין שלב פרסום נוסף — והתשובה מציינת אם הקוד live או עדיין טיוטה.

צירוף QR לרשומת CRM

צרו את הקוד עם כתובת ה-URL של הרשומה עצמה, פרסמו אותו, ואז משכו את התמונה ישירות לשדה קובץ. נקודת הקצה של התמונה מחזירה את הבתים בגוף התשובה, ולכן רוב מערכות ה-CRM מקבלות אותה כקובץ מצורף בלי העלאה ביניים.

const headers = { Authorization: `Bearer ${process.env.MOSAQO_KEY}` };

const created = await fetch('https://api.mosaqo.app/v1/public-api/qr', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: `Deal ${deal.id}`,
    mode: 'dynamic',
    contentType: 'url',
    content: { targetUrl: `https://crm.example.com/deals/${deal.id}` },
  }),
}).then((r) => r.json());

const qrId = created.data.id;
await fetch(`https://api.mosaqo.app/v1/public-api/qr/${qrId}/publish`, { method: 'POST', headers });

const png = await fetch(
  `https://api.mosaqo.app/v1/public-api/qr/${qrId}/image?format=png&size=1024`,
  { headers },
).then((r) => r.arrayBuffer());

שמרו את qrId על הרשומה. זו הידית לכל מה שיבוא אחר כך — הפניה מחדש, ארכיון, אנליטיקה.

הנפקת קודים באצווה

קוד לכל מוצר, לכל שולחן, לכל נכס. שלחו CSV, תשאלו את סטטוס המשימה, ואז מפו את התוצאות בחזרה לשורות שלכם — כל שורה נושאת את ה-qrId שנוצר ממנה.

curl -X POST https://api.mosaqo.app/v1/public-api/bulk \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "url",
    "mode": "dynamic",
    "csv": "name,destination\nTable 1,https://example.com/menu?t=1\nTable 2,https://example.com/menu?t=2"
  }'

curl "https://api.mosaqo.app/v1/public-api/bulk/$JOB_ID?limit=500" \
  -H "Authorization: Bearer $MOSAQO_KEY"

שלחו קודם "dryRun": true כדי לאמת כל שורה בלי לכתוב דבר.

הטמעת התמונה לפי URL

Airtable, Notion ו-Sheets מציגות תמונה מקישור שהן מושכות בעצמן, ולכן הן לעולם אינן שולחות את הכותרת Authorization שלכם ואינן יכולות להשתמש בנקודת הקצה שלמעלה. בקשו במקום זאת קישור חתום:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image-url \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "png", "size": 1024 }'

רק קודים מפורסמים מתאימים — קוד מפורסם כבר מודפס ונמצא בעולם, ואילו טיוטה עשויה להיות קמפיין שטרם הוכרז. שימו את ה-url שחוזר ישירות בשדה קובץ מצורף או תמונה. העברה לארכיון או מחיקה של הקוד עוצרת מיד את פעולת הקישור, וכך מבטלים קישור שהתפשט רחוק מכפי שהתכוונתם.

תגובה לסריקות

סריקות לעולם אינן נדחפות: אין webhook לכל סריקה, ואיננו שולחים אנליטיקה ברמת הסריקה לנקודות קצה של צד שלישי. הירשמו ל-scan.aggregate_ready אם צבירה מספיקה, או משכו סריקות בודדות בעצמכם לפי לוח זמנים:

curl "https://api.mosaqo.app/v1/public-api/scans?since=$LAST_SEEN&limit=500" \
  -H "Authorization: Bearer $MOSAQO_KEY"

שמרו את pagination.nextCursor שחוזר והחזירו אותו בפעם הבאה. הסדר יציב, כך שתשאול חוזר לעולם אינו קורא סריקה פעמיים ואינו מדלג עליה. אילו שדות יופיעו תלוי בהגדרות פרטיות האנליטיקה של סביבת העבודה שלכם — התשובה מפרטת את allowedDimensions כדי שתדעו למה לצפות.

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

פלטפורמות no-code

Make, Zapier, n8n ו-Pipedream כולן יכולות לדבר עם Mosaqo כבר היום דרך מודול HTTP גנרי, והחלקים שהן צריכות קיימים: GET /me כבדיקת חיבור, עימוד לפי סמן לאיטרטורים, ומנויי webhook שטריגר יכול ליצור ולהסיר בעצמו.

אותו מסמך OpenAPI מיובא ל-Postman ול-Insomnia, ומייצר לקוח מוטיפס עם openapi-typescript או עם כל מחולל OpenAPI.

שני כללים ששווה להקפיד עליהם

• שמרו את `qrId`, לא את כתובת ה-URL הציבורית. ה-URL יציב, אבל המזהה הוא מה שכל קריאה מאוחרת צריכה.
• העבירו לארכיון במקום למחוק. מחיקה היא סופית ושוברת כל עותק מודפס; העברה לארכיון מורידה קוד מהאוויר וניתנת לביטול.

פרטי נקודות הקצה המלאים נמצאים בתיעוד ה-API.