إنشاء رمز QR عبر واجهة REST API: دليل مع أمثلة curl

الخطوة 1: إنشاء المفتاح

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

الخطوة 2: الطلب الأول

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

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

يعرض الطلب الأول حسابك وباقتك وحدودك، ويعرض الثاني رموز QR الخاصة بك مع المعرّف والاسم والوجهة والتسميات وعدد المسحات والحالة _rev.

الخطوة 3: إنشاء رمز QR

للإنشاء تحتاج إلى مفتاح ثانٍ بصلاحية «قراءة + كتابة». مع مفتاح قراءة ترد الواجهة على الطلبات التي تغيّر شيئًا بالرمز 403 والكود NUR_LESEN. يحتاج رمز QR الجديد إلى اسم ووجهة على الأقل:

curl -X POST https://sameqr.com/api/v1/qr \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Speisekarte","targetUrl":"https://example.com/karte"}'

امسح رمز QR الجديد بهاتفك قبل المتابعة. للإنشاء يجب أن يكون عنوان بريدك الإلكتروني مؤكدًا، ويُحتسب رمز QR ضمن حصة باقتك.

الخطوة 4: تغيير الوجهة

تغييرات الوجهة محمية بشكل خاص. تحتاج إلى مفتاح «كامل» وترسل الحالة الحالية لرمز QR في ترويسة X-Confirm. وتحصل على الحالة من طلب القراءة:

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

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

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

الخطوة 5: فهم الأخطاء والحدود

تعود الأخطاء دائمًا بالشكل نفسه: كائن error فيه status وcode وmessage. عالجها في برنامجك بدل أن تتابع ببساطة.

• 401: المفتاح مفقود أو خاطئ أو منتهي أو مسحوب.
• 403: المفتاح ينقصه المستوى المطلوب، أو أن باقتك لا تسمح بهذا الإجراء.
• 400 مع BESTAETIGUNG_FEHLT: لتغيير الوجهة أو الإيقاف أو الحذف تنقص ترويسة X-Confirm مع الحالة الحالية.
• 409: غيّر أحدهم رمز QR في الأثناء.
• 429: طلبات كثيرة جدًا. يُسمح بـ 120 في الدقيقة لكل مفتاح، وفي الساعة 60 في الباقة المجانية، و300 في Start، و1.000 في Pro، و5.000 في Agentur.

كل الطلبات موصوفة في /api/v1/openapi.json، والدليل على sameqr.com/entwickler.

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

واجهة REST API في Same-QR منظمة وموثقة جيدًا ومتاحة في كل باقة. تستطيع فعل كل ما تفعله لوحة التحكم، وتحمي رموز QR المطبوعة من تغييرات الوجهة غير المقصودة بالتأكيد والحدود، وتتيح مفاتيح بثلاثة مستويات، وترد بأخطاء مفهومة.

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

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