البدء السريع مع API

يتحقق هذا الدليل السريع من قدرة الواجهة الخلفية على المصادقة وقراءة بيانات حسابك. تحتاج إلى خطة مدفوعة نشطة، وطرفية تدعم curl، وصلاحية الوصول إلى لوحة التحكم ← الإعدادات ← المطوّرون.

تتيح الإصدار v1 الحالي من API إدارة الموارد ومزامنتها. وهي ليست وسيلة نقل للمحادثات المخصصة: لا يمكنك إرسال رسائل بصفتك زائرًا. يمكن إنشاء العملاء المحتملين (Leads) وتحديثهم وقبولهم (leads:write)، ويمكن للمالك الرد على محادثة أو إيقافها مؤقتًا أو استئنافها (conversations:write).

1. إنشاء مفتاح بأقل الصلاحيات#

أنشئ مفتاحًا باسم Local API quickstart، وحدّد account:read وsites:read، واختر مدة صلاحية قصيرة. انسخ المفتاح بصيغته الأصلية فورًا؛ فلن يُعرض مرة أخرى.

لا تستخدم مفتاح مزوّد ذكاء اصطناعي مثل مفتاح OpenRouter أو Speko. تتطلب واجهة API العامة مفتاح Make Agent Fast يبدأ بالبادئة maf_live_.

2. تخزينه لهذه الطرفية#

export MAF_API_KEY="maf_live_..."

تأكد من وجود المتغير دون طباعة السر:

test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"

لا تضف المفتاح إلى .env أو أمثلة سجل الأوامر في الطرفية أو بيانات الاختبار الثابتة أو حزمة المتصفح. وفي الشيفرة المنشورة، استخدم مدير الأسرار الخاص بالمضيف.

3. فحص الحساب#

curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

الحالة المتوقعة: 200 OK. يحتوي نص الاستجابة على data.id ومعلومات الخطة والاستحقاقات وملخص المحفظة. كما تحتوي الاستجابة على x-request-id؛ احتفظ بهذه القيمة عند الإبلاغ عن طلب فاشل.

{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "owner@example.com",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}

قد تُضاف حقول جديدة دون تغيير المسار /v1. تجاهل الحقول غير المعروفة بدلًا من رفض الاستجابة.

4. عرض المواقع#

curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

تستخدم استجابات المجموعات هذا الغلاف:

{
  "data": [],
  "has_more": false,
  "next_cursor": null
}

إذا كانت قيمة has_more تساوي true، فأرسل قيمة next_cursor كما هي تمامًا كمعامل الاستعلام cursor في الطلب التالي. لا تفك ترميز المؤشرات ولا تنشئها بنفسك.

5. التعامل مع خطأ منظَّم#

أزل ترويسة Authorization مؤقتًا وكرر الطلب إلى /me. يجب أن تكون الاستجابة 401 مع رمز ثابت:

{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}

يجب أن تعتمد الشيفرة الإنتاجية في تفرعاتها على error.code لا على مقارنة message. سجّل العملية ورمز حالة HTTP ومعرّف الطلب دون تسجيل المفتاح.

6. تنفيذ أول عملية كتابة بأمان#

أنشئ مفتاحًا منفصلًا يتضمن أيضًا sites:write وagents:write وknowledge:write؛ ولا توسّع صلاحيات مفتاح القراءة الخاص بالبدء السريع. اتبع وصفات API لإنشاء موقع، وإضافة معرفة موثوقة، ونشره باستخدام مفاتيح idempotency صريحة.

أخطاء شائعة في الطلب الأول#

تابع مع الصلاحيات والأخطاء ومرجع API وحدود المعدّل.