واجهة Mosaqo البرمجية للمطوّرين

واجهة 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 — كل نقطة نهاية، مع وحدة تحكم حية.