مرجع الواجهة البرمجية

واجهة REST بإصدارات (v1) مع مواصفات OpenAPI 3.1 كاملة.

المصادقة

أنشئ رمزًا من المطورون ← رموز API واختر الصلاحيات. يظهر الرمز مرة واحدة ويُخزّن الهاش فقط. يتطلب الوصول خطة تتضمنه.

curl https://linkora-demo.devorbit.dev/api/v1/me \
  -H "Authorization: Bearer lk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

إنشاء رابط

أرسل ترويسة Idempotency-Key حتى لا تؤدي إعادة المحاولة إلى تكرار.

curl -X POST https://linkora-demo.devorbit.dev/api/v1/links \
  -H "Authorization: Bearer $LINKORA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f7e-campaign-42" \
  -d '{"destination_url":"https://example.com/offer","title":"Offer","tags":["email"],
       "utm":{"utm_source":"newsletter","utm_medium":"email","utm_campaign":"spring"}}'

نقاط النهاية

الطريقة	المسار	الصلاحية
GET	/api/v1/me	—
GET	/api/v1/links	links:read
POST	/api/v1/links	links:write
GET	/api/v1/links/{id}	links:read
PATCH	/api/v1/links/{id}	links:write
DELETE	/api/v1/links/{id}	links:write
POST	/api/v1/links/{id}/pause\|resume\|archive\|unarchive	links:write
GET	/api/v1/links/{id}/analytics	analytics:read
GET	/api/v1/analytics	analytics:read
GET	/api/v1/links/{id}/qr?format=png\|svg	qr:read

الأخطاء

تستخدم الأخطاء غلاف JSON موحدًا مع رمز آلي ومعرّف الطلب (وأيضًا في ترويسة X-Request-Id).

{ "error": { "code": "plan_limit", "message": "…", "request_id": "c0a8…", "details": { "feature": "links_active", "limit": 25 } } }

توقيع Webhooks

يحمل كل تسليم Linkora-Signature (t=الطابع الزمني، v1=HMAC-SHA256 لـ "timestamp.body") و Linkora-Event و Linkora-Delivery. ارفض الطوابع القديمة وتجنب تكرار المعرفات.

// Node.js verification example
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
const valid = fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
// Then de-duplicate on the Linkora-Delivery header before processing.

حدود الطلبات

الطلبات محدودة لكل رمز (افتراضيًا 120 في الدقيقة). التجاوز يُرجع 429 مع Retry-After.