واجهة API وخادم MCP من GetLinkFast

فيمَ تفيد

• الوكالات وفرق SEO: اربط أدواتك الداخلية ولوحات المتابعة بحسابك. الكتالوج والسلة والطلبات والحالات كلها تُقرأ بصيغة JSON.
• وكلاء الذكاء الاصطناعي: اطلب من Claude Code أو Cursor «اعثر لي على 5 مواقع مالية بـ DR 40+ واطلبها». يبحث الوكيل ويعرض عليك الملخّص ولا يطلب إلا بعد موافقتك.
• Make، n8n، Zapier: تكفي وحدة HTTP ومفتاح.

تبيع واجهة API المقال الضيف (guest_post) وإدراج الرابط (link_insertion) وحزم SEO/GEO، بالرصيد فقط. يبقى شراء الرصيد والعروض الأخرى في لوحة التحكم.

إنشاء مفتاح

1. افتح لوحة التحكم ← الوصول إلى API.
2. سمِّ المفتاح (مثلًا «وكيل Claude» أو «تقارير Make») واختر صلاحياته. على مفتاح يمكنه الطلب، يمكنك تحديد سقف لكل طلب وسقف على مدى 24 ساعة.
3. انسخ المفتاح. يبدأ بـ glf_live_ ولا يُعرض إلا مرة واحدة: لا نحتفظ إلا ببصمة منه.
4. أرسله في ترويسة كل طلب: Authorization: Bearer glf_live_…

10 مفاتيح نشطة كحد أقصى لكل مؤسسة. يتوقف المفتاح الملغى عن العمل فورًا، وكذلك مفاتيح العضو الذي يغادر المؤسسة. أبقِ المفتاح خارج مستودعات الشيفرة: من يملكه يتصرّف باسم مؤسستك.

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

يحمل كل مفتاح صلاحية واحدة أو أكثر. يتلقى الطلب الذي يفتقد الصلاحية اللازمة 403 insufficient_scope، ولا يرى وكيل الذكاء الاصطناعي إلا الأدوات المسموح بها.

بدء سريع

تبدأ كل المسارات بـ https://www.getlinkfast.com/api/v1. أبقِ www: العنوان بلا www يعيد التوجيه، وعميل HTTP لا يعود يرسل ترويسة Authorization بعد إعادة التوجيه.

المبالغ باليورو دون ضريبة القيمة المضافة. الردود بصيغة JSON، والحقول بصيغة snake_case.

curl https://www.getlinkfast.com/api/v1/account \
  -H "Authorization: Bearer glf_live_…"

curl "https://www.getlinkfast.com/api/v1/sites?dr_min=40&language=fr&product=guest_post&sort=dr&dir=desc&page_size=10" \
  -H "Authorization: Bearer glf_live_…"

curl -X POST https://www.getlinkfast.com/api/v1/cart/items \
  -H "Authorization: Bearer glf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"8a1f0c3e-5b7d-4e2a-9c61-0f3b2d4e6a17","product_type":"guest_post","target_url":"https://www.example.com/invoicing","anchor":"invoicing software","topic":"How to choose invoicing software for a small business"}'

استبدل site_id بمعرّف موقع من الخطوة 2. لا ترسل سعرًا أبدًا: الخادم يحسبه.

curl -X POST https://www.getlinkfast.com/api/v1/checkout \
  -H "Authorization: Bearer glf_live_…" \
  -H "Idempotency-Key: order-2026-10-14-001"

يعطي الرد معرّف الطلب والمبلغ المخصوم ورصيدك المتبقي. ثم تابع تقدّمه عبر GET /orders/{id}.

الطلب بالرصيد

تطلب واجهة API بالرصيد فقط ولا تُطلق أبدًا دفعًا بالبطاقة. يُشحن الرصيد من لوحة التحكم.

يأخذ الطلب بنود guest_post وlink_insertion من السلة. تبقى البنود الأخرى، المضافة من لوحة التحكم، في السلة وتُدرج في skipped_items.

لا سقف افتراضيًا: رصيدك هو الحد الوحيد. على مفتاح يمكنه الطلب، حدّد سقفًا لكل طلب وسقفًا على مدى 24 ساعة متحركة. يُرفض الطلب الذي يتجاوزهما (403 spending_limit_exceeded، مع المتبقي المتاح)، دون خصم.

رصيد غير كافٍ: 402 insufficient_credits، مع المبلغ الناقص ورابط صفحة الرصيد، لإرساله إلى شخص في فريقك. لا يُخصم شيء.

بعد ذلك يجري كل شيء كما من لوحة التحكم: بريد تأكيد ومتابعة في شاشة الطلبات، حيث يحمل الطلب اسم المفتاح الذي أنشأه.

ترويسة Idempotency-Key

• إلزامية على POST /checkout وPOST /packs/orders: من 8 إلى 128 حرفًا من محارف ASCII القابلة للطباعة، دون مسافات. من دونها: 400 idempotency_key_required.
• القيمة الواحدة تساوي نية شراء واحدة. إعادة إرسال القيمة نفسها تُرجع الطلب الأصلي (200، "replayed": true) دون خصم ثانٍ، حتى لو تغيّرت السلة منذ ذلك الحين.
• بعد انتهاء المهلة أو انقطاع الشبكة، أعد المحاولة بالقيمة نفسها: لن تدفع مرتين.
• لعملية شراء جديدة، أنشئ قيمة جديدة، مثل UUID.
• على POST /checkout كما على POST /packs/orders، تُرفض القيمة التي استُخدمت لعملية شراء أخرى: 409 idempotency_conflict، دون خصم. وفي الحزمة، تُرفض أيضًا القيمة نفسها المرسلة بمحتوى مختلف.
• في جهة MCP، يؤدي رمز التأكيد هذا الدور: لا شيء عليك إنشاؤه.

الحدود

• 120 طلبًا في الدقيقة لكل مفتاح للقراءة، ومثلها، بشكل منفصل، للسلة: لا يستهلك أحدهما من الآخر.
• 10 استدعاءات في الدقيقة لكل مفتاح نحو مسارات الشراء أو أدواته — بما في ذلك إعادة الإرسال والرفض وخطوة الملخّص في MCP.
• 300 طلب HTTP في الدقيقة لكل مفتاح على خادم MCP. وكل أداة تُستدعى تُحتسب أيضًا ضمن حد صلاحيتها.
• بعد ذلك: 429 rate_limited. مدة الانتظار بالثواني تحدّدها الترويسة Retry-After عبر HTTP، وdetails.retry_after_seconds في نتيجة أداة MCP.
• 100 نتيجة كحد أقصى في الصفحة (page_size).
• جسم الطلب: 1 ميغابايت كحد أقصى.

رموز الأخطاء

كل خطأ له الشكل نفسه. اختبر code: فهو ثابت. message بالإنجليزية وموجّهة إلى المطوّر؛ وdetails تحدّد الحقل الخاطئ أو المبالغ.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this order. Nothing was debited. Ask a human to top up at credits_url, then retry with the same Idempotency-Key.",
    "details": {
      "missing_amount": 42,
      "credits_url": "https://www.getlinkfast.com/dashboard/credits"
    }
  }
}

خادم MCP

يمنح خادم MCP وكيلك الذكي الوظائف نفسها التي تقدّمها واجهة API، بالمفتاح نفسه. عنوانه: https://www.getlinkfast.com/api/mcp.

Claude Code

أمر واحد في الطرفية:

claude mcp add --transport http getlinkfast https://www.getlinkfast.com/api/mcp --header "Authorization: Bearer glf_live_…"

Cursor

في ~/.cursor/mcp.json. تجنّب ملف .cursor/mcp.json الخاص بمشروع: فكثيرًا ما ينتهي في المستودع، ومعه المفتاح.

{
  "mcpServers": {
    "getlinkfast": {
      "url": "https://www.getlinkfast.com/api/mcp",
      "headers": {
        "Authorization": "Bearer glf_live_…"
      }
    }
  }
}

Claude Desktop

لا يرسل Claude Desktop ترويسات مخصّصة إلى خادم بعيد، لذا لا يستطيع تمرير مفتاحك. سيتصل مباشرةً عبر اتصال OAuth المخطط له في إصدار قادم. اليوم، استخدم Claude Code أو Cursor: فهما يرسلان المفتاح في ترويسة Authorization.

الأدوات

لا يرى الوكيل إلا الأدوات التي تسمح بها صلاحيات المفتاح: المفتاح الذي لا يملك حق الطلب ليس لديه أي أداة شراء.

read

search_sitesget_sitelist_site_pageslist_categoriesget_accountlist_ordersget_orderget_auditquote_packlist_auditsget_plan

cart

get_cartadd_to_cartupdate_cart_itemremove_cart_itemadd_audit_pagerun_auditcancel_planned_link

purchase

checkoutorder_packplan_links

الشراء على مرحلتين

1. يستدعي الوكيل checkout أو order_pack دون confirmation_token: لا يُخصم شيء. يتلقى الملخّص (البنود، المجموع، الرصيد بعد الخصم، السقف المتبقي) وconfirmation_token.
2. يعرض عليك هذا الملخّص. إن وافقت، يستدعي الأداة مجددًا مع confirmation_token: يُنشأ الطلب ويُخصم.
3. الرمز صالح لمدة 10 دقيقة. إذا تغيّرت السلة أو سعر أو المفتاح في الأثناء، يُرفض (confirmation_expired) ويعيد الوكيل الخطوة 1. إعادة الاستدعاء بالرمز نفسه بعد انقطاع تُرجع الطلب نفسه، دون خصم ثانٍ.

عميل مكتوب يدويًا

الخادم بلا جلسات: تُرسل كل رسالة JSON-RPC عبر POST ويصل الرد بصيغة JSON. أرسل Accept: application/json, text/event-stream وContent-Type: application/json، وإلا يردّ الخادم بـ 406. يردّ GET وDELETE بـ 405.

curl -X POST https://www.getlinkfast.com/api/mcp \
  -H "Authorization: Bearer glf_live_…" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

التدقيق والتخطيط

يمكن للوكيل تدقيق موقع، ثم توزيع الروابط على عدة أشهر انطلاقًا من التقرير. أربع خطوات، بأدوات خادم MCP.

1. تبدأ run_audit التدقيق الكامل لنطاق: فحوصات تقنية، والظهور في ChatGPT، والمواقع التي يفيد فيها رابط. يستغرق بضع دقائق. لا يُخصم شيء، ويُفتح التقرير بحصة التدقيق الخاصة بالمنظمة إن كانت لديها. الحد: 10 عمليات تدقيق لكل مفتاح كل 24 ساعة؛ وطلب النطاق نفسه خلال ساعة يعيد التدقيق الموجود.
2. تُرجع get_audit الحالة والخطوة الجارية، ثم التقرير في summary عندما تصبح الحالة ready. استدعِها كل 30 إلى 60 ثانية. تسرد list_audits عمليات تدقيق المنظمة من الأحدث.
3. تبني plan_links جدولًا من تدقيق جاهز: ميزانية شهرية باليورو دون ضريبة القيمة المضافة (لا تقل عن 100 €)، من شهرين إلى 12 شهرًا، واختياريًا تاريخ بدء والصفحات المستهدفة. كما في الشراء، هناك خطوتان. دون رمز لا يُحفظ شيء: يتلقى الوكيل الجدول (الروابط، تواريخ الإرسال، المجموع) ورمز confirmation_token صالحًا لمدة 10 دقيقة. بعد موافقتك يستدعي الأداة مجددًا بالحقول نفسها والرمز، فتُحفظ الخطة.
4. يتابع get_plan كل رابط: الصفحة المستهدفة والنص الرابط والسعر والحالة (مجدول، أو مطلوب، أو منشور، أو ملغى، أو فاشل مع سبب الفشل مثل insufficient_credits). يلغي cancel_planned_link رابطًا خُطّط عبر الواجهة البرمجية، أو كل روابط نطاق لم تُطلب بعد. تبقى الروابط التي جدولها فريقنا في مكانها: team_planned لرابط واحد، وskipped_team_planned لعددها.

لا يُخصم شيء عند حفظ الخطة. يُخصم كل رابط من الرصيد يوم إرساله، بالسعر المقروء مجددًا في ذلك اليوم، خلال المرور اليومي الصباحي (نحو 06:20 بالتوقيت العالمي). إذا نقص الرصيد في ذلك اليوم فلن يُطلب الرابط ويظهر فاشلًا في get_plan. لا يمكن إلغاء رابط سبق طلبه.

الصلاحيات: تتطلب run_audit وcancel_planned_link الصلاحية cart، وتتطلب plan_links الصلاحية purchase، وتتطلب get_audit وlist_audits وget_plan الصلاحية read. تسري حدود إنفاق المفتاح على الروابط المخطَّط لها أيضًا.

في لوحة التحكم، تعرض صفحة التفويض هذه الروابط في كتلة «الروابط المجدولة». يمكن لمالك المنظمة سحب الروابط المجدولة عبر API من هناك. أما التي جدولها فريقنا فهي للقراءة فقط.

المرجع

كل مسار مع صلاحيته وأداة MCP المقابلة له. المعاملات ومخططات الردود والأخطاء مسارًا مسارًا: وصف OpenAPI 3.1.

سؤال عن واجهة API؟ راسلنا، وسيجيبك شخص من الفريق.