مقدمة عن API

​

ما يمكنك فعله

​

الأدلة

​

عنوان URL الأساسي

https://getqr.com/api/v1

​

الإصدارات

• تصدر التغييرات غير المتوافقة مع الإصدارات السابقة ضمن بادئة إصدار جديدة مثل /api/v2/، ويستمر /api/v1/ في العمل.
• قد تظهر التغييرات الإضافية، مثل الحقول الاختيارية الجديدة أو نقاط النهاية الجديدة، ضمن v1. تجاهل حقول الاستجابة التي لا تتعرّف عليها شيفرتك.

​

البدء السريع

curl https://getqr.com/api/v1/health

curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'

curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png

​

الطلبات والاستجابات

• الصيغة. أرسل أجسام الطلبات بصيغة JSON مع Content-Type: application/json. الاستثناء هو رفع ملف CSV في الإنشاء المجمّع، الذي يستخدم multipart/form-data.
• الاستجابات. الاستجابات بصيغة JSON. أما التنزيلات، مثل صور QR وأرشيفات ZIP المجمّعة، فتُرجع الملف نفسه.
• التواريخ. التواريخ سلاسل ISO 8601 بتوقيت UTC، مثل 2026-08-01T10:00:00.000Z.
• معاملات الاستعلام. تأخذ المعاملات المنطقية السلسلتين true أو false.
• التحديثات الجزئية. لا تغيّر نقاط النهاية PATCH إلا الحقول التي ترسلها.
• البيانات السرية. لا تتضمن الاستجابات أبدًا كلمات المرور أو المعرّفات الداخلية. لا يُبلغ رمز QR المحمي بكلمة مرور إلا عن passwordProtected: true.
• مساحة العمل. يُنفَّذ كل طلب في مساحة العمل التي ينتمي إليها مفتاح API الخاص بك. لا تمرّر معرّف مساحة العمل. راجع الوصول والأدوار.
• الأخطاء. تُرجع الطلبات الفاشلة كائن error يحتوي على code ثابت. راجع الأخطاء.

​

ترقيم الصفحات

{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}

​

عدم التكرار (Idempotency)

-H "Idempotency-Key: order-4821-qr"

• تكرار الطلب بالمفتاح نفسه خلال 24 ساعة يُرجع الاستجابة الأصلية بدلًا من إنشاء رمز QR ثانٍ.
• تكون ترويسة الاستجابة x-idempotent-replay بالقيمة true للاستجابة المُعادة وfalse للاستجابة الجديدة.
• إذا كان الطلب الأول بهذا المفتاح لا يزال قيد التنفيذ، تُرجع الواجهة 409 conflict. أعد المحاولة بعد انتهائه.
• إعادة استخدام مفتاح مع جسم طلب مختلف تُرجع 422 unprocessable_entity.
• دون الترويسة، يُعامَل جسم الطلب المطابق المُرسَل خلال 30 ثانية على أنه مكرر.

​

حدود الطلبات

​

قريبًا

​

الخطوات التالية