REST API · v1

REST API — مكتوب لتُقرأ، لا فقط لتُستخدم.

Base URL ثابت، مصادقة قياسية، JSON في كل مكان، حدود واضحة. لا surprises.

https://api.cd4cd.com

المصادقة

كل طلب يجب أن يحمل header Authorization مع API key بدئ بـ cd_live_ للإنتاج أو cd_test_ للاختبار.

$ curl https://api.cd4cd.com/v1/links \
  -H "Authorization: Bearer cd_live_xxxx"

الـ Endpoints

الطريقة	Path	الوصف
POST	/v1/auth/login	تسجيل دخول وإرجاع JWT.
POST	/v1/auth/refresh	تجديد token عبر refresh.
POST	/v1/links	إنشاء رابط قصير جديد.
GET	/v1/links	قائمة كل الروابط.
GET	/v1/links/:id	تفاصيل رابط.
PATCH	/v1/links/:id	تعديل الوجهة أو الـ alias.
DELETE	/v1/links/:id	حذف رابط.
GET	/v1/links/:id/clicks	نقرات الرابط مع breakdown.
POST	/v1/qr	إنشاء QR (15+ نوع).
GET	/v1/bio/:username	بيانات صفحة Bio عامة.
POST	/v1/users/me/export	تصدير كل بياناتك (JSON).

مثال: إنشاء رابط

POST /v1/links
Authorization: Bearer cd_live_xxx
Content-Type: application/json

{
  "longUrl": "https://example.com/long/path",
  "alias":   "promo-2026",
  "tags":    ["campaign-q2"],
  "expiresAt": "2026-12-31T23:59:59Z"
}

→ 201 Created
{
  "id":        "lnk_8f3c_a91",
  "shortCode": "promo-2026",
  "shortUrl":  "https://cd4cd.com/promo-2026",
  "longUrl":   "https://example.com/long/path",
  "createdAt": "2026-05-13T05:42:00Z"
}

حدود الاستخدام

Free: 60 req/min · 10K/شهر
Pro: 600 req/min · 100K/شهر
Business: قابل للتفاوض

كل رد يحمل headers X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset.

أكواد الأخطاء

الكود	الرسالة	السبب
400	Bad Request	JSON غير صحيح أو حقل ناقص.
401	Unauthorized	token مفقود أو منتهي.
403	Forbidden	صلاحيات غير كافية.
404	Not Found	الـ ID غير موجود.
422	Validation	فشلت قواعد التحقق (Zod).
429	Rate Limited	تجاوزت الحد.
500	Server Error	خطأ من جانبنا — اتصل بالدعم.

تحتاج مساعدة؟ [email protected].