وصفات التكامل

أربعة أنماط تغطي تقريبًا كل تكامل نراه. وكل واحد منها بضعة استدعاءات، وهي قابلة للتركيب معًا.

إعادة توجيه رمز مطبوع

السبب الذي يدفع معظم الفرق إلى استخدام الـ 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

أنشئ الرمز باستخدام رابط السجل نفسه، وانشره، ثم اسحب الصورة مباشرة إلى حقل ملف. وتُرجع نقطة نهاية الصورة البايتات مضمَّنة، لذا تقبلها معظم أنظمة 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 أولًا للتحقق من كل صف دون كتابة أي شيء.

تضمين الصورة عبر رابط

تعرض 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 كي تعرف ما الذي تتوقعه.

إن كان الاستطلاع غير عملي لك فعلًا واحتجت إلى تسليم عمليات المسح لحظة حدوثها، فذلك متاح عند الطلب لا بشكل افتراضي.

المنصات بلا كود

تستطيع Make وZapier وn8n وPipedream التحدث إلى Mosaqo اليوم عبر وحدة HTTP عامة، والقطع التي تحتاجها جاهزة: GET /me كاختبار اتصال، وترقيم بالمؤشر للمكرِّرات، واشتراكات webhook يستطيع المُطلِق إنشاءها وإزالتها بنفسه.

ويُستورَد مستند OpenAPI نفسه إلى Postman وInsomnia، ويولّد عميلًا مكتوب الأنواع عبر openapi-typescript أو أي مولّد OpenAPI.

قاعدتان جديرتان بالاتباع

• خزّن `qrId` لا الرابط العام. فالرابط ثابت، لكن المعرّف هو ما يحتاجه كل استدعاء لاحق.
• أرشِف بدل أن تحذف. فالحذف نهائي ويعطّل كل نسخة مطبوعة؛ أما الأرشفة فتُخرج الرمز من الخدمة ويمكن التراجع عنها.

تفاصيل نقاط النهاية كاملةً في مرجع API.