واجهة اختصار الروابط: JSON وأمثلة برمجية

1. قم بإنشاء مفتاح

استخدم الصفحة الرئيسية لإنشاء مفتاح API الخاص بك. أرسله في رأس طلب X-API-KEY.

2. أرسل طلبك

استخدم POST مع نوع المحتوى: application/json ونص يحتوي على حقل عنوان url.

POST https://freetoolsweb.com/short-url/?api=create
Content-Type: application/json
X-API-KEY: YOUR_API_KEY

{"url": "https://example.com"}

3. اقرأ الرد

تحتوي الاستجابة الناجحة على الحالة وshort_url. في حالة الفشل، اقرأ حقل الرسالة.

{"status": "success", "short_url": "https://gothis.link/Ab12"}

4. مثال التكامل

استبدل YOUR_API_KEY بمفتاحك. يُظهر هذا المثال المختصر من HTML وJavaScript المفتاح للزوار. للتكامل الخاص، أرسل الطلبات من خادمك وأبقِ بيانات اعتماده خارج شيفرة المتصفح.

<form id="short-url-form">
  <label for="long-url">Website URL</label>
  <input id="long-url" name="url" type="url" placeholder="https://example.com" required>
  <button type="submit">Shorten</button>
</form>
<div id="result" role="status"></div>

<script>
document.getElementById("short-url-form").addEventListener("submit", async function(event) {
  event.preventDefault();
  const button = this.querySelector("button");
  const result = document.getElementById("result");
  button.disabled = true; result.textContent = "Processing...";
  try {
    const response = await fetch("https://freetoolsweb.com/short-url/?api=create", {
      method: "POST",
      headers: {"Content-Type": "application/json", "X-API-KEY": "YOUR_API_KEY"},
      body: JSON.stringify({url: document.getElementById("long-url").value.trim()})
    });
    const data = await response.json();
    if (!response.ok || data.status !== "success") throw new Error(data.message || "Request failed.");
    const url = new URL(data.short_url);
    if (!["http:", "https:"].includes(url.protocol)) throw new Error("Invalid response.");
    const link = document.createElement("a");
    link.href = url.href; link.textContent = url.href;
    link.target = "_blank"; link.rel = "noopener noreferrer";
    result.replaceChildren(link);
  } catch (error) { result.textContent = error.message || "Connection failed."; }
  finally { button.disabled = false; }
});
</script>

التحقق من الصحة والحدود

قد يتم رفض عناوين URL غير الصالحة والوجهات الخاصة والمجالات المحظورة والطلبات المفرطة. تعرض عناوين URL المتكررة الرابط القصير الموجود.

أرسل عنوانًا واحدًا لكل طلب، بحد أقصى 2,048 بايت. يُسمح بما يصل إلى 5 طلبات إنشاء خلال ثانيتين لكل IP. عند HTTP 429، انتظر وفق Retry-After ولا تكرر الطلبات باستمرار.

تحقق من حالة HTTP وحقل status في JSON معًا. قد تعيد أخطاء التحقق أو المفتاح القديمة HTTP 200 مع status=error. يتطلب HTTP 405 استخدام POST، ويشير HTTP 503 إلى صيانة أو فحص معلّق. أعد المحاولة فقط عند توجيهك لذلك واحتفظ بالعنوان الأصلي عند الفشل.

{"status": "error", "message": "Invalid URL"}
{"status": "error", "code": "rate_limited", "message": "Too many requests, please try again."}

cURL

curl -X POST 'https://freetoolsweb.com/short-url/?api=create' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  --data '{"url":"https://example.com"}'

سياسة الخصوصية · الاتصال