الوصول إلى واجهة البرمجة ووكلاء الذكاء الاصطناعي

توفر SimplyQuote واجهة REST API لتمكين وكلاء الذكاء الاصطناعي والبرامج النصية والتكاملات من العمل مع عروض الأسعار والفواتير نيابة عنك. يتم التحكم في الوصول عبر رموز وصول شخصية محددة الصلاحيات وقابلة للإلغاء.

1. تفعيل الوصول إلى الواجهة

1. افتح صفحة الإعدادات وسجّل الدخول
2. قم بالتمرير إلى قسم «الوصول إلى واجهة البرمجة ووكلاء الذكاء الاصطناعي».
3. قم بتسمية الرمز واختيار الصلاحيات ثم اضغط «إنشاء رمز».
4. انسخ الرمز فوراً — لأسباب أمنية، يظهر مرة واحدة فقط.

2. إرسال طلب

أرسل الرمز كرمز Bearer في ترويسة Authorization:

curl https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here"

3. إنشاء وتحديث المستندات

إنشاء وتحديث عروض الأسعار والفواتير يستخدم الرمز نفسه مع صلاحية كتابة. تُحسب الإجماليات دائماً من الخادم بناءً على البنود التي ترسلها:

curl -X POST https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Ltd",
    "client_email": "billing@acme.example",
    "items": [
      { "description": "Consulting", "quantity": 4, "unit_price": 120 },
      { "description": "Hosting (1 month)", "quantity": 1, "unit_price": 30 }
    ],
    "currency": "USD",
    "tax_rate": 10,
    "expiry_date": "2026-10-01"
  }'

استجابة النجاح (والقوائم مماثلة، مع quotes/invoices بالإضافة إلى total/page/limit/has_more):

// Wrapped envelope (POST/PATCH/lists): { success:true, data:{ quote } }
{
  "success": true,
  "data": {
    "quote": { "id": "uuid", "quote_number": "Q-1001", "total": 528.0 }
  }
}

curl -X PATCH https://simplyquote.net/api/v1/invoices/{id} \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

القوائم وترقيم الصفحات

تقبل نقاط نهاية القوائم updated_since (بصيغة ISO 8601) وpage (الافتراضي 1) وlimit (الافتراضي 20، الحد الأقصى 100) وstatus (غير حساس لحالة الأحرف؛ القيم غير المعروفة تُتجاهل). تتضمن الاستجابات total وpage وlimit وhas_more.

GET /api/v1/quotes?status=sent&page=1&limit=20&updated_since=2026-01-01T00:00:00Z

قواعد الحقول للإنشاء والتحديث

items مطلوب في POST: مصفوفة غير فارغة، كل بند بوصف غير فارغ، وquantity أكبر من 0 (الافتراضي 1)، وunit_price أكبر من أو يساوي 0 (الافتراضي 0). tax_rate نسبة مئوية (0–100)؛ عند الإنشاء فإن tax_rate الأكبر من 0 يعني tax_enabled. تُخزن currency بأحرف كبيرة. يقبل issue_date أي تاريخ صالح (يُخزن YYYY-MM-DD). تستخدم عروض الأسعار expiry_date والفواتير due_date (كلا الاسمين مقبولان، وnull يمسح القيمة). الحالة: عروض الأسعار draft|sent، والفواتير draft|sent|viewed|paid|cancelled — وتعيين paid يسجل paid_at. تُعاد حساب الإجماليات دائماً على الخادم.

4. الاستخدام مع وكيل الذكاء الاصطناعي

أعطِ وكيلك عنوان URL الأساسي ورمزك وقائمة نقاط النهاية أدناه. مثال لتعليمات أي وكيل يستخدم الأدوات (Claude أو GPT أو LangChain وغيرها):

يمكنك الوصول إلى حسابي في SimplyQuote.
عنوان URL الأساسي: https://simplyquote.net
أرسل الترويسة التالية مع كل طلب: Authorization: Bearer sq_رمزهنا
نقاط النهاية المتاحة: GET/POST /api/v1/quotes, GET/PATCH /api/v1/quotes/{id},
GET/POST /api/v1/invoices, GET/PATCH /api/v1/invoices/{id}, POST /api/mcp
تدعم القوائم ?page و?limit (الحد الأقصى 100) و?status و?updated_since وتعيد { success:true, data:{ quotes|invoices, total, page, limit, has_more } }.
تعيد القراءات المفردة الكائن الخام. {id} هو UUID وليس رقم المستند.
استخدم POST لإنشاء المستندات — أرسل دائماً items مع description وquantity وunit_price.

5. الاتصال عبر MCP (موصى به للوكلاء)

يوفر SimplyQuote خادم MCP (Model Context Protocol) مدمجاً على /api/mcp (HTTP بث بلا حالة، JSON-RPC 2.0). يمكن للوكلاء الذين يدعمون خوادم MCP عن بُعد (Claude وChatGPT وCursor وVS Code وغيرها) الاتصال مباشرة برمزك دون الحاجة إلى هندسة المطالبات. الأدوات المتاحة:

list_quotesget_quotecreate_quotelist_invoicesget_invoicecreate_invoice

{
  "mcpServers": {
    "simplyquote": {
      "type": "http",
      "url": "https://simplyquote.net/api/mcp",
      "headers": {
        "Authorization": "Bearer sq_your_token_here"
      }
    }
  }
}

مثال على استدعاء أداة (JSON-RPC 2.0 — تُرفض الطلبات المجمّعة، وتعيد الإشعارات 202 وGET يعيد 405):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_quotes", "arguments": { "limit": 5 } }
}

يتم التحقق من كل استدعاء أداة مقابل صلاحيات رمزك — يستطيع رمز القراءة فقط عرض القوائم والبيانات، بينما يتطلب إنشاء عروض الأسعار أو الفواتير صلاحية الكتابة المقابلة.

نقاط النهاية

الصلاحيات

• quotes:read — قراءة عروض الأسعار الخاصة بك
• invoices:read — قراءة فواتيرك
• clients:read — محجوز — لا توجد نقطة نهاية مستقلة للعملاء بعد (بيانات العميل موجودة على عروض الأسعار/الفواتير)
• quotes:write — إنشاء وتحديث عروض الأسعار
• invoices:write — إنشاء وتحديث الفواتير
• clients:write — محجوز — لا توجد نقطة نهاية مستقلة للعملاء بعد (تُنشأ بيانات العميل وتُحدَّث ضمنياً عند حفظ عروض الأسعار/الفواتير)

تنسيق الاستجابة والأخطاء

تستخدم نقاط نهاية REST صيغتين — تحقق من الصيغة المنطبقة في كل حالة:

{
  "success": true,
  "data": { ... },
  "error": { "code": "...", "message": "...", "details": { ... } }
}

تعيد القراءات المفردة الكائن الخام أعلاه (دون غلاف)، مع أخطاء مسطحة { error, message } — مثل 404 إذا كان المعرف غير معروف. أما القوائم وPOST/PATCH فتستخدم الغلاف دائماً.

// Flat envelope (single GET): bare object, no success/data wrapper
{
  "id": "uuid",
  "quote_number": "Q-1001",
  "status": "sent",
  "total": 528.0
}

// unknown id:
{ "error": "not_found", "message": "Quote not found" }

• success — true عند النجاح وfalse عند الفشل
• data — البيانات عند النجاح
• error — رمز الخطأ والرسالة والتفاصيل الاختيارية عند الفشل

رموز الخطأ الأكثر شيوعاً:

• UNAUTHORIZED — الرمز مفقود أو غير صالح أو منتهي (HTTP 401)
• FORBIDDEN — الرمز لا يملك الصلاحية المطلوبة (HTTP 403)
• VALIDATION_ERROR — فشل جسم الطلب في التحقق (HTTP 400)
• NOT_FOUND — المستند المطلوب غير موجود (HTTP 404)
• DATABASE_ERROR — خطأ في التخزين أثناء معالجة الطلب (HTTP 500)
• RATE_LIMIT — طلبات كثيرة جداً — أعد المحاولة لاحقاً (HTTP 429)

الويب هوك وOAuth والمرجع الكامل

الويب هوك: أدر الاشتراكات عبر GET/POST/PATCH/DELETE /api/v1/webhooks (أي رمز صالح، دون صلاحية محددة). يجب أن تكون url نقطة نهاية HTTPS عامة. لا يُعرض السر إلا عند الإنشاء — تحقق من التسليم عبر ترويسة X-SimplyQuote-Signature (HMAC-SHA256).

تستخدم التطبيقات الشريكة OAuth 2.0 (/api/oauth/authorize و/api/oauth/token و/api/oauth/revoke) بدلاً من الرموز الشخصية. التفاصيل في docs/API.md وفي المواصفات المقروءة آلياً على /api/v1/openapi.json.

ملاحظات أمنية

• تُخزن الرموز بشكل مشفر — لا يحتفظ SimplyQuote أبداً بالرمز الخام.
• امنح فقط الصلاحيات التي يحتاجها وكيلك؛ عادةً تكفي صلاحيات القراءة فقط.
• ألغِ الرمز في أي وقت من الإعدادات لقطع الوصول فوراً.
• مواصفات قابلة للقراءة آلياً للوكلاء متاحة على /api/v1/openapi.json