انتقل إلى المحتوى
حلول

للمطوّرين

ابنِ على واجهة حلول البرمجية

واجهة REST واحدة لكل النظام — نفس الواجهة التي تعمل عليها تطبيقات سطح المكتب والهواتف لدينا. رموز وصول Bearer، وعزل صارم لكل شركة، وخادم MCP لعملاء الذكاء الاصطناعي.

تصفّح مرجع الواجهة تنزيل ملف OpenAPI

البداية السريعة

من الصفر إلى أول استدعاء في ثلاث خطوات.

١. احصل على رمز وصول

سجّل الدخول إلى تطبيق الويب وأنشئ رمزًا من الإعدادات ← رموز API — يُعرض الرمز مرة واحدة فقط، فاحفظه في مكان آمن. ويمكن للعملاء البرمجيين بدلًا من ذلك استبدال بيانات الدخول عند نقطة إصدار الرموز (وعلى الحسابات المفعّل لها التحقق بخطوتين إرفاق رمز التحقق).

افتح الإعدادات ← رموز API

٢. اختر الشركة

استدعِ GET /me برمزك لعرض الشركات التي تنتمي إليها، ثم أرسل معرّف الشركة المختارة ضمن ترويسة X-Company مع كل طلب. سجلات الشركات الأخرى لا تظهر أصلًا ضمن الطلب.

٣. نفّذ أول استدعاء

نقاط القوائم تدعم التصفح عبر ?page و?per_page (الافتراضي ٢٥ والحد الأقصى ١٠٠) وتردّ دائمًا بصيغة {data, links, meta}.

# 1) Issue a token (or create one in Settings → API tokens)
curl -X POST https://app.hlooltech.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "••••••••", "device_name": "my-integration"}'

# 2) List your companies
curl https://app.hlooltech.com/api/v1/me \
  -H "Authorization: Bearer <token>"

# 3) First call — list contacts of one company
curl "https://app.hlooltech.com/api/v1/contacts?per_page=25" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company: <company-uuid>"

المصادقة

أرسل الرمز ضمن ترويسة Authorization: Bearer مع كل طلب. يعمل الرمز بصلاحياتك أنت: دورك داخل الشركة يحدّد ما تسمح به كل نقطة، وكل عملية في المرجع تُظهر الصلاحية التي تتطلبها. تنتهي صلاحية الرموز بعد 90 يومًا؛ ويمكنك إلغاء أي رمز في أي وقت من الإعدادات ← رموز API، أو باستدعاء DELETE /auth/token مستخدمًا إياه.

سياق الشركة (X-Company)

حلول نظام متعدد الشركات. ترويسة X-Company تختار مساحة العمل الخاصة بالطلب، وهي مطلوبة في كل مكان عدا نقطة إصدار الرموز و GET /me. إذا سمّت الترويسة شركة لا تنتمي إليها، يُرفض الطلب.

الأخطاء والحدود والتصفح

تأتي الأخطاء بالصيغ التالية حصرًا — دون أي صيغة مخصّصة. تسمح الواجهة بـ ١٢٠ طلبًا في الدقيقة لكل رمز؛ وأخطاء التحقق (422) تسرد كل الحقول المخالفة.

401 الرمز مفقود أو غير صالح أو منتهي الصلاحية.
403 دورك في هذه الشركة لا يملك الصلاحية المطلوبة، أو السجل يخص شركة أخرى.
404 السجل غير موجود في الشركة المختارة.
422 فشل التحقق — راجع خريطة أخطاء الحقول.
{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

عملاء الذكاء الاصطناعي (MCP)

الرمز نفسه يفتح خادم MCP من حلول: يمكن لعملاء ذكاء اصطناعي مثل Claude وChatGPT الاستعلام عن جهات الاتصال والفواتير وأوامر البيع ومستويات المخزون والموظفين والمهام — وإنشاء المهام — دائمًا ضمن صلاحياتك ونطاق شركتك.

نقطة الاتصال: POST https://app.hlooltech.com/mcp

على خارطة الطريق

الويب هوكس الصادرة (الاشتراك في أحداث مثل دفع فاتورة) وتطبيقات OAuth الخارجية غير متاحة بعد — اليوم تُصادَق التكاملات برموز وصول شخصية. أما ردود المزوّدين التي نستقبلها (المدفوعات وواتساب وتسليم البريد) فهي بنية داخلية وليست سطحًا للمطوّرين.