واجهة برمجة رموز QR: أنشئ رموز QR وعدّلها وحلّل نتائجها تلقائيًا

ما فائدة واجهة برمجة رموز QR

واجهة برمجة رموز QR هي واجهة برمجية: بدل النقر في المتصفح، يرسل برنامجك طلبات إلى خدمة رموز QR ويتلقى الردود. وهكذا تُنشأ رموز QR مباشرة من متجر أو نظام مستودعات أو سكربت أو جدول.

يستحق هذا العناء حين يتكرر العمل: مئة رمز QR للطاولات أو المنتجات، وتقارير مسح شهرية، وتغيير وجهات كثيرة بعد إعادة إطلاق الموقع. وهو يعمل فقط مع رموز QR الديناميكية. يحتوي رمز QR الديناميكي من Same-QR على عنوان قصير ثابت، أما الوجهة خلفه فتبقى عندنا ويمكن تغييرها في أي وقت دون إعادة الطباعة.

ما الذي تغطيه واجهة Same-QR

تقع واجهة REST على العنوان https://sameqr.com/api/v1. وهي تستدعي الوظائف نفسها الموجودة في لوحة التحكم، بحدود الباقة نفسها وعمليات التحقق نفسها:

• عرض رموز QR وقراءتها وإنشاؤها وتعديلها وحذفها.
• إحصاءات رمز QR: عدد المسح وتاريخ الإنشاء وعدد مرات تغيير الوجهة.
• إنشاء صفحات الضيوف وتعديلها ونشرها وإيقافها، مثل قائمة الطعام وقائمة الأسعار وساعات العمل وصفحة الروابط والعرض ومعصرة النبيذ وملصق النبيذ الإلكتروني جهة الاتصال.
• قراءة قائمة طعام من سبع صور كحد أقصى أو من ملف PDF.
• إدارة التصنيفات ومشاريع العملاء وقراءة الطلبات الواردة من نماذج الاتصال.

يوجد وصف قابل للقراءة آليًا لكل الطلبات على /api/v1/openapi.json، والدليل على sameqr.com/entwickler.

مفاتيح API والصلاحيات

تنشئ المفتاح في لوحة التحكم ضمن الحساب، في قسم «الوصول لـ CLI والسكربتات والوكلاء». تختار واحدًا من ثلاثة مستويات: «للقراءة فقط» أو «قراءة + كتابة» (إنشاء وتغيير الأسماء والنصوص) أو «كامل» (وبالإضافة إلى ذلك تغيير الوجهات وإيقاف الرمز وحذفه)، ومدة صلاحية 30 أو 90 أو 180 أو 365 يومًا، وعند الحاجة بلا حد. يبدأ المفتاح بـ sqr_live_ ويظهر مرة واحدة فقط. وما نحفظه عندنا هو مجموع تحقق فقط.

المفتاح الذي يملك صلاحية القراءة فقط يتلقى رفضًا واضحًا عند كل طلب يغيّر شيئًا. وهو الخيار الصحيح للتقارير والتحليلات. وكل ما يغيّر وجهة رمز QR مطبوع محميّ بشكل إضافي: تغيير الوجهة وإيقاف الرمز وحذفه تتطلب المستوى «كامل» وتأكيدًا بالحالة التي قرأتها سابقًا، ولا يُسمح عبر API إلا بـ 10 منها كحد أقصى في الساعة و30 في اليوم. في لوحة التحكم لا يوجد هذا الحد. ويمكن إلغاء كل مفتاح في أي وقت فيصبح غير صالح فورًا.

سير عمل نموذجي

مكان المفتاح في ترويسة Authorization، وليس في عنوان URL أبدًا. احفظ المفتاح قبل ذلك كمتغير بيئة. هكذا تعرض رموز QR الخاصة بك وتغيّر وجهة رمز QR واحد:

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr

curl -X PATCH https://sameqr.com/api/v1/qr/<id> \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -H "X-Confirm: <stand>" \
  -d '{"targetUrl":"https://example.com/karte-neu"}'

قيمة X-Confirm، أي الحالة، يعيدها طلب القراءة على /api/v1/qr/<id>. لا يتغير إلا ما ترسله. ومن أراد التأكد من أن أحدًا لم يعدّل رمز QR نفسه في الأثناء، يرسل الحالة التي قرأها كـ _rev. وإن تغيّر شيء، لا يُستبدل شيء، ويحتوي الرد على الحالة الحالية. تأتي الأخطاء دائمًا بالصيغة نفسها، مع الحالة ورمز QR ورسالة مفهومة.

الحدود والممارسات الجيدة

يُسمح لكل مفتاح بـ 120 طلبًا في الدقيقة كحد أقصى. ويضاف إلى ذلك حد في الساعة يعتمد على الباقة: 60 في الباقة المجانية، و300 في Start، و1.000 في Pro، و5.000 في Agentur. تلتقط هذه الحدود الأخطاء، مثل سكربت عالق في حلقة لا نهائية، ولا تعيق الاستخدام الصادق.

• جرّب أولًا بمفتاح للقراءة، ثم اكتب.
• اختبر السير الجديد على رمز QR واحد وامسحه بهاتفك.
• تجنّب الحذف حيث تكفي وجهة جديدة. رموز QR المحذوفة وروابطها القصيرة لا تعود.
• أنشئ مفتاحًا خاصًا لكل برنامج واحتفظ به في مدير كلمات مرور أو في متغير بيئة.

الخلاصة: لماذا Same-QR

لا تمنحك Same-QR الواجهة البرمجية كإضافة مكلفة، بل في كل باقة، بالوظائف نفسها الموجودة في لوحة التحكم: رموز QR والإحصاءات وقوائم الطعام وصفحات الضيوف والتصنيفات والمشاريع. ويضاف إلى ذلك صلاحيات واضحة لكل مفتاح، ورسائل خطأ صادقة، وفحص ليلي لكل الوجهات يخبرك بالبريد إذا تعذّر الوصول إلى إحداها.

ابدأ الآن: سجّل مجانًا على sameqr.com، فهناك 20 رمز QR ديناميكيًا مجانية بشكل دائم. الواجهة البرمجية وCLI وخادم MCP متاحة في كل باقة، والتوثيق على sameqr.com/entwickler.

الأسئلة الشائعة