API v2 + TypeScript SDK

واجهة Revolink وحزمة SDK
أدِر روابطك من الكود

أنشئ روابط بقواعد توجيه، وأدِر الوسوم والنطاقات المخصصة، واقرأ تحليلات النقرات عبر واجهة REST بمواصفات OpenAPI 3.1 أو عبر حزمة TypeScript SDK المكتوبة الأنواع وبلا اعتماديات.

احصل على مفتاح API مرجع الـ API GitHub

أنشئ مفتاحًا من الملف الشخصي ← API

آخر تحديث: نوفمبر 2026

الطرفية

npm install revolink

تعمل مع Node.js 18 أو أحدث ومع أي بيئة تدعم fetch العام. بلا اعتماديات، مع أنواع TypeScript كاملة مولَّدة من مواصفات الـ API.

بدء سريع

من الصفر إلى أول رابط قصير في ثلاث خطوات.

أنشئ مفتاح API

في Revolink افتح الملف الشخصي ← API وأنشئ مفتاحًا. اختر الصلاحيات التي يحتاجها المفتاح فقط.

انسخ معرّف مساحة العمل

يُرسَل معرّف مساحة العمل مع كل طلب، فيعمل المفتاح دائمًا في مساحة واحدة.

أنشئ رابطًا

هيّئ العميل بالمفتاح ومعرّف المساحة ثم استدعِ links.create.

احتفظ بالمفتاح على خادمك. من يملكه يستطيع التصرف في مساحتك ضمن صلاحيات المفتاح.

ادمج مشروعك بسلاسة

مع Revolink SDK يمكنك إنشاء روابط قصيرة بقواعد توجيه في بضعة أسطر من الكود.

احصل على مفتاح API مرجع الـ API

index.ts

import {Revolink} from 'revolink';

const revolink = new Revolink({
  apiKey: process.env.REVOLINK_API_KEY!,
  workspaceId: process.env.REVOLINK_WORKSPACE_ID!,
});

const {shortLink} = await revolink.links.create({
  url: 'https://example.com',
});
console.log(shortLink); // https://rvlnk.link/k3x9a

استكشف نقاط نهاية الـ API

الطلب

TypeScript

await revolink.links.create({
  url: 'https://example.com',
});

الاستجابة

JSON

{
  id: "65f1c0a2e4b0a1d2c3b4a5f6",
  name: "example.com",
  domain: "rvlnk.link",
  slug: "k3x9a",
  shortLink: "https://rvlnk.link/k3x9a",
  url: "https://example.com",
  active: true,
  clicks: 0,
  ...
}

ما تغطيه الحزمة

أربعة موارد واستدعاء me. كل دالة تقابل نقطة نهاية REST واحدة.

المورد	الدوال	ما تفعله
revolink.links	`createupsertgetlistiterateupdatedeletecreateManyupdateManydeleteMany`	إنشاء الروابط وقراءتها وتحديثها وحذفها، وupsert بحسب slug، وعرضها بالفلاتر والترقيم، والمرور على كل الصفحات، والعمليات الجماعية (حتى 100 في الاستدعاء).
revolink.tags	`listgetcreateupdatedelete`	إنشاء الوسوم وعرضها وإعادة تسميتها وحذفها.
revolink.domains	`listgetcreatedelete`	إضافة نطاق مخصص ومعرفة حالة التحقق منه وحذفه.
revolink.analytics	`linkworkspace`	تحليلات النقرات لرابط واحد أو لمساحة العمل كلها في نطاق تاريخ.
revolink.me()		من يتصرف بالمفتاح، ومساحة العمل، وصلاحيات المفتاح.

توجيه ذكي من الكود

وجّه الزوار المختلفين إلى وجهات مختلفة. قاعدة واحدة بالضبط هي الافتراضية، وتنطبق الأخرى بحسب الدولة والجهاز ونظام التشغيل وشروط أخرى.

routing.ts

await revolink.links.create({
  name: 'App download',
  rules: [
    {isDefault: true, targetUrl: 'https://example.com/download'},
    {
      isDefault: false,
      targetUrl: 'https://apps.apple.com/app/id1',
      device: ['mobile'],
      os: ['iOS'],
    },
  ],
});

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

كل مفتاح يحمل scopes. تردّ نقطة النهاية بـ 403 حين ينقص الـ scope المطلوب، فامنح كل تكامل ما يستخدمه فقط.

ترويسات المصادقة

Authorization: Bearer <key>

أرسل المفتاح كرمز bearer.

X-Api-Key

أو أرسل المفتاح في هذه الترويسة.

X-Workspace-Id

مطلوبة. مساحة العمل التي يتصرف فيها الطلب. يجب أن يكون مالك المفتاح عضوًا فيها.

الـ Scopes

Scope	يسمح بـ
`links:read`	عرض الروابط وقراءتها
`links:write`	إنشاء الروابط وupsert وتحديثها
`links:delete`	حذف الروابط
`links:bulk`	الإنشاء والتحديث والحذف الجماعي (حتى 100 رابط في الطلب)
`analytics:read`	قراءة تحليلات النقرات
`tags:read`	عرض الوسوم وقراءتها
`tags:write`	إنشاء الوسوم وتحديثها
`tags:delete`	حذف الوسوم
`domains:read`	عرض النطاقات المخصصة وقراءتها
`domains:write`	إضافة نطاقات مخصصة
`domains:delete`	حذف النطاقات المخصصة

تُحتسب استدعاءات الـ API ضمن حصة الـ API الشهرية لخطة مالك مساحة العمل. وعندما يوقف حدّ الخطة طلبًا ما، يكون رمز الخطأ license_limit_reached.

الأخطاء وإعادة المحاولة

كل طلب فاشل يُلقي RevolinkError يحمل حالة HTTP ورمزًا مقروءًا آليًا ورسالة تبيّن ما يجب إصلاحه.

errors.ts

import {RevolinkError} from 'revolink';

try {
  await revolink.links.create({url: 'https://example.com', slug: 'taken'});
} catch (error) {
  if (error instanceof RevolinkError) {
    error.status;              // 409
    error.code;                // 'conflict'
    error.licenseLimitReached; // true when the plan's limit stopped the request
    error.requiredPermission;  // e.g. 'tags:write' when the key lacks a scope
    error.retryAfter;          // seconds, on 429
  }
}

إعادة محاولات لا تكرّر رابطًا أبدًا

يُعاد الطلب بعد 429 دائمًا بعد مهلة Retry-After. أما أخطاء الشبكة واستجابات 5xx فتُعاد فقط مع GET وPUT وDELETE. أما POST أو PATCH التي ربما عُولجت فلا تُكرَّر أبدًا، فلا يُنشأ رابط مرتين. الإعدادات الافتراضية: مهلة 30 ثانية لكل محاولة ومحاولتان إضافيتان، وضبط maxRetries على 0 يعطّل إعادة المحاولة.

الرمز	المعنى
`invalid_request`	الطلب خاطئ (400). تبيّن الرسالة السبب.
`unauthorized`	لا يوجد مفتاح، أو المفتاح غير صالح أو منتهي (401).
`forbidden`	ينقص المفتاحَ إذنٌ، أو لا يسمح دورك بذلك (403).
`license_limit_reached`	بلغتَ حدّ الخطة: الروابط أو الوسوم أو النطاقات أو استدعاءات الـ API (403).
`not_found`	لا يوجد هذا العنصر في مساحة العمل هذه (404).
`conflict`	موجود مسبقًا، مثل slug أو اسم وسم مستخدم (409).
`rate_limited`	أكثر من 300 طلب في الدقيقة للمفتاح (429).
`network_error`	لا استجابة: انقطاع شبكة أو انتهاء مهلة (الحالة 0).

التوثيق والمواصفات والمصدر

مرجع API التفاعلي

جرّب كل نقطة نهاية في API v2 من المتصفح.

مواصفات OpenAPI 3.1

ولّد عميلك الخاص بأي لغة.

الـ SDK على GitHub

المصدر وREADME والـ issues لحزمة TypeScript SDK.

revolink على npm

ثبّت الحزمة وتحقق من أحدث إصدار.

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

هل يجب استخدام الـ SDK؟

لا. الـ SDK طبقة رقيقة مكتوبة الأنواع فوق واجهة REST. يمكنك استدعاء https://api.revolink.link/apiv2 مباشرة من أي لغة بمفتاح API وترويسة X-Workspace-Id، أو توليد عميل من مواصفات OpenAPI 3.1.

ما بيئات التشغيل التي تدعمها الحزمة؟

Node.js 18 أو أحدث وأي بيئة تدعم fetch العام. بلا اعتماديات، وتأتي بنسخ ESM وCommonJS مع أنواع TypeScript مولَّدة من مواصفات الـ API.

ما حدود الطلبات؟

الطلبات محدودة بـ 300 في الدقيقة لكل مفتاح API. وما زاد عن ذلك ترد الواجهة بـ 429 مع ترويسة Retry-After، وتنتظر الحزمة وتعيد المحاولة تلقائيًا. وبشكل منفصل تُحتسب استدعاءات الـ API ضمن الحصة الشهرية لخطة مالك مساحة العمل.

ماذا عن API v1؟

واجهة API v1 مجمَّدة وتحمل استجاباتها ترويسات Deprecation. ينبغي أن تستخدم التكاملات الجديدة API v2.

هل قد تنشئ الحزمة روابط مكررة عند إعادة المحاولة؟

لا. لا تُعاد أبدًا طلبات POST أو PATCH التي ربما عُولجت. تُعاد فقط استجابات 429 والطلبات المتكافئة (GET وPUT وDELETE).

هل يمكنني استخدام Revolink من وكيل ذكاء اصطناعي؟

نعم. يتيح خادم Revolink MCP لـ Claude وCursor وغيرهما من عملاء MCP إدارة الروابط بلغة طبيعية. والـ SDK هو الخيار لكودك وسكربتاتك.

تابع الاستكشاف

Revolink MCP

أدِر الروابط من Claude أو Cursor أو أي عميل MCP.

تكامل Zapier

أتمت إنشاء الروابط دون كتابة كود.

تتبع النقرات

بيانات التحليلات التي يمكنك جلبها عبر الـ API.

هل أنت مستعد للبدء مع Revolink؟

انضم إلى الفرق والمبدعين الذين يتحكمون في كل نقرة من خلال التوجيه الذكي. أطلق حملات أذكى، وحسّن حركة المرور في الوقت الفعلي، وانمو بلا حدود.

ابدأ مجانًا

خطة مجانية · بدون بطاقة ائتمان · إلغاء في أي وقت

لديك روابط بالفعل؟ استوردها

واجهة Revolink وحزمة SDK أدِر روابطك من الكود

التثبيت بسطر واحد