ابدأ

مرجع API

أنشئ وأدر الروابط القصيرة برمجيًا. كل طلب يتطلب رمز Bearer من شاشة مفاتيح API في لوحة التحكم.

المصادقة

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

العنوان الأساسيhttps://urlvis.com

إنشاء رابط

ينشئ رابطًا قصيرًا جديدًا. تمر الوجهة بفلتر الاحتيال لحظة الإنشاء — عمليات الكتابة أبطأ من أي مختصر عادي.

POST/api/linkslinks:write
curl -X POST https://urlvis.com/api/links \
  -H "Authorization: Bearer urlvis_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://example.com/campaign",
    "domainId": "<domain-uuid>",
    "slug": "spring",
    "expiresAt": "2026-12-31T23:59:00.000Z"
  }'

destination, domainId — required · slug, expiresAt — optional

عرض الروابط

يُعيد جميع الروابط في حسابك.

GET/api/linkslinks:read
curl https://urlvis.com/api/links \
  -H "Authorization: Bearer urlvis_live_..."

تغيير وجهة الرابط

يحدّث أين يشير رابط موجود. يبقى الرابط القصير ورمز QR وسجل النقرات كما هي. تمر الوجهة الجديدة بنفس الفحص الأمني الذي يمر به رابط جديد، لذا قد تُعيد 422 blocked_by_filter.

PATCH/api/links/{id}links:write
curl -X PATCH https://urlvis.com/api/links/<link-id> \
  -H "Authorization: Bearer urlvis_live_..." \
  -H "Content-Type: application/json" \
  -d '{"destination": "https://example.com/new-target"}'

destination — required · utm — optional. The short link, its QR code and click history stay the same. The new destination runs through the same security scan as a new link, so this can return 422 blocked_by_filter.

حذف رابط

يزيل رابطًا من حسابك. يُعيد 204 عند النجاح، 404 إذا لم يكن الرابط موجودًا.

DELETE/api/links/{id}links:write
curl -X DELETE https://urlvis.com/api/links/<link-id> \
  -H "Authorization: Bearer urlvis_live_..."

204 on success, 404 if no such link exists on your account.

تصدير التحليلات

يُصدّر إحصائيات النقرات بصيغة CSV. تصفية اختيارية حسب linkId. مدة الاحتفاظ بالبيانات تعتمد على خطتك.

GET/api/analytics/export?linkId=links:read
curl "https://urlvis.com/api/analytics/export?linkId=<link-uuid>" \
  -H "Authorization: Bearer urlvis_live_..." \
  -o analytics.csv

حدود المعدل

يحمل كل رد حصتك المتبقية. الحدود لكل مفتاح، وليس لكل عنوان IP.

X-RateLimit-Limit: 60       # links:write
X-RateLimit-Limit: 600      # links:read
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 42        # seconds
Retry-After: 42              # 429 only

الأخطاء

تُعاد الأخطاء بصيغة JSON مع حقل error وحالة HTTP المطابقة.

401 invalid_api_key      key unknown, revoked, or plan no longer includes API
403 insufficient_scope   key lacks the scope this endpoint needs
404 not_found            no such link on this account
422 blocked_by_filter    destination rejected by the fraud filter
402 link_quota           monthly plan quota exhausted
429 rate_limited         see Retry-After

الحصول على معرّف النطاق

نقطة الطرف POST /api/links تتطلب domainId. لا توجد حاليًا نقطة طرف API لعرض نطاقاتك — نقطة طرف domains تتطلب جلسة لوحة التحكم. للحصول على معرّف النطاق:

  1. افتح لوحة التحكم وانتقل إلى النطاقات.
  2. تعرض كل بطاقة نطاق معرّفها مع زر نسخ بجانبه — انسخه من هناك.