تطبيق LeyApp للمطورين

ملخص

تُتيح واجهة برمجة التطبيقات (API) الوصول إلى نفس بيانات المحامين المعتمدين المتوفرة على موقع leyapp.es: البحث، والملفات الشخصية العامة، والتقييمات، والتوافر، ونوايا الحجز. يعمل الوصول المجهول بحدود استخدام منخفضة؛ بينما يُتيح مفتاح واجهة برمجة التطبيقات رفع هذه الحدود والوصول إلى نقاط النهاية المُفهرسة وتحليلات الاستخدام.

التشغيل السريع

من الصفر إلى نية حجز (تجريبية) في أربع طلبات. أنشئ مفتاح اختبار مجاني في لوحة التحكم ← المطور أولاً.

# 1. Get a test key at leyapp.es/dashboard/developer
export LEYAPP_API_KEY="leyk_test_..."

# 2. Find a lawyer
curl "https://leyapp.es/api/v1/lawyers/search?city=Barcelona&practice_area=immigration" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

# 3. Check availability (id from step 2)
curl "https://leyapp.es/api/v1/lawyers/<lawyer_id>/availability" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

# 4. Create a (test) booking intent
curl -X POST "https://leyapp.es/api/v1/bookings/initiate" \
  -H "Authorization: Bearer $LEYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-1" \
  -d '{"lawyer_id":"<lawyer_id>","date":"<date>","start_time":"09:00:00","end_time":"10:00:00"}'

المصادقة

أرسل مفتاحك كرمز حامل في كل طلب:

Authorization: Bearer leyk_...

• تأتي المفاتيح في نسخ حية (leyk_) واختبارية (leyk_test_) ويتم عرضها مرة واحدة فقط عند إنشائها - قم بتخزينها في مدير الأسرار.
• لا تقم أبدًا بتضمين مفتاح في كود جانب العميل أو في مستودع عام. قم بالتدوير عن طريق إنشاء مفتاح جديد، ونشره، ثم إلغاء المفتاح القديم (بدون توقف).
• الإلغاء فوري. لا يمكن استعادة المفاتيح المفقودة، بل استبدالها فقط.
• تُستخدم رموز MCP (ley_...) للتحقق من صحة مساعدي الذكاء الاصطناعي على /api/mcp وهي غير صالحة على واجهة برمجة تطبيقات REST.

مفاتيح المؤسسة

يمكن لشركة محاماة على منصة LeyApp امتلاك مفاتيح واجهة برمجة التطبيقات (API) مباشرةً، بشكل منفصل عن المفاتيح الشخصية للعاملين فيها. ينتمي مفتاح الشركة إلى المؤسسة، لذا يبقى فعالاً حتى مع تغيير الموظفين: فعندما يتغير دور الشخص الذي أنشأه أو يغادر، يستمر المفتاح في العمل، ويتم إخطار مالكي الشركة ومديريها ليتمكنوا من تحديثه بشكل مدروس بدلاً من اكتشاف انقطاع الخدمة.

يستطيع المالكون والمسؤولون إدارة مفاتيح الشركة بحكم أدوارهم. أما أي عضو آخر فلا يمكنه الوصول إليها إلا بعد منحه صلاحية محددة.

• api:view — لعرض قائمة بمفاتيح الشركة، وبادئاتها، وآخر استخدام لها. لا يتم الكشف عن السر مرة أخرى بعد إنشائه، لأي شخص.
• api:manage — إنشاء مفاتيح الشركة وإلغائها وتعليقها وتقييدها.
• api:webhooks — إدارة نقاط نهاية webhook الخاصة بالشركة.

تدعم مفاتيح الشركة عنصرين إضافيين للتحكم: قائمة عناوين IP المسموح بها، والتي تمنع استخدام المفتاح من أي عنوان خارج القائمة، والتعليق، الذي يوقف عمل المفتاح مؤقتًا دون حذفه. يمكن لشركتك رفع التعليق الذي تفرضه، بينما لا يمكن رفع التعليق الذي تفرضه LeyApp إلا من قِبل LeyApp.

حدود المعدل

تخضع الطلبات المُفهرسة لحدود مُتدرجة (نافذة مزدوجة: زيادة دقيقة + حصة يومية) مع رؤوس X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset. عند استخدام المنفذ 429، يتم تطبيق إعادة المحاولة بعد المحاولة وإعادة المحاولة مع تأخير أسي مُتذبذب.

تبدأ المفاتيح الجديدة من المستوى المجاني. يتم منح مستويات الشركاء من قِبل فريق LeyApp - تواصل معنا عبر نموذج الدعم إذا كانت عملية التكامل الخاصة بك تتطلب مساحة أكبر. تستخدم الطلبات المجهولة حدودًا منفصلة وأقل لكل عنوان IP.

وضع الاختبار

تتصرف مفاتيح الاختبار (leyk_test_) تمامًا مثل المفاتيح الحية - نفس نقاط النهاية، نفس التحقق، نفس أشكال الاستجابة - ولكن لا يحدث شيء حقيقي: لا يتم تخزين أي نية حجز، ولا يتم إخطار أي محامٍ، ولا يمكن تأكيد أي شيء أو دفعه.

تظهر حركة المرور التجريبية في سجل طلبات لوحة التحكم (مُعلّمة)، ولكنها مُستثناة من الإحصائيات اليومية. استبدل المفتاح بمفتاح التشغيل الفعلي عند إطلاق الخدمة - لا حاجة لأي تغيير آخر.

نقاط النهاية

curl "https://leyapp.es/api/v1/lawyers/search?city=Barcelona&practice_area=immigration&language=en" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

curl "https://leyapp.es/api/v1/lawyers/<lawyerId>" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

curl "https://leyapp.es/api/v1/lawyers/<lawyerId>/availability" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

curl "https://leyapp.es/api/v1/lawyers/<lawyerId>/reviews" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

curl "https://leyapp.es/api/v1/practice-areas" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

curl "https://leyapp.es/api/v1/cities" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

{
  "lawyer_id": "<lawyer_id from search>",
  "date": "2026-09-01",
  "start_time": "09:00:00",
  "end_time": "10:00:00",
  "source": "api",
  "agent_name": "MyIntegration"
}

curl -X POST "https://leyapp.es/api/v1/bookings/initiate" \
  -H "Authorization: Bearer $LEYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lawyer_id":"<lawyer_id from search>","date":"2026-09-01","start_time":"09:00:00","end_time":"10:00:00","source":"api","agent_name":"MyIntegration"}'

curl "https://leyapp.es/api/v1/booking-intents/<intentId>" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

روابط الويب

اشترك في نقطة نهاية HTTPS (لوحة التحكم ← المطور ← Webhooks) لتلقي الأحداث المتعلقة بنوايا الحجز التي تم إنشاؤها باستخدام مفتاحك. تتبع عمليات التسليم مواصفات Webhooks القياسية ويتم إعادة محاولتها تلقائيًا.

• الأحداث: booking_intent.confirmed / booking_intent.expired (مرحلة النية)، بالإضافة إلى دورة حياة الحجز الكاملة للحجوزات التي تم إنشاؤها بواسطة واجهة برمجة التطبيقات - booking.approved، booking.cancelled، booking.completed.
• تحقق من كل عملية تسليم باستخدام سر التوقيع whsec_ الذي يظهر مرة واحدة عند إنشاء نقطة النهاية — تقوم مكتبات standardwebhooks الرسمية بذلك في استدعاء واحد. ارفض الطوابع الزمنية الأقدم من ±5 دقائق.
• يتم التسليم مرة واحدة على الأقل: يتم إزالة التكرارات بواسطة رأس webhook-id (وهو أيضًا معرّف الحمولة). تحتوي الحمولة على المعرّفات والحالات فقط - استرجع التفاصيل من واجهة برمجة التطبيقات إذا كنت بحاجة إليها.

# Delivery headers (Standard Webhooks — standardwebhooks.com):
#   webhook-id:        unique delivery id (dedup key — at-least-once delivery)
#   webhook-timestamp: unix seconds (reject if older than ±5 minutes)
#   webhook-signature: v1,<base64 HMAC-SHA256 of "{id}.{timestamp}.{body}">
#
# Payload: { "id": "...", "type": "booking_intent.confirmed",
#            "created_at": "...", "data": { "booking_intent_id": "...", "status": "..." } }
# Events: booking_intent.confirmed | booking_intent.expired
# Retries: 1m / 5m / 30m / 2h / 12h, then dead. Endpoint auto-disabled
# after 20 consecutive failures.

وكلاء MCP والذكاء الاصطناعي

هل تفضل التحدث بدلاً من البرمجة؟LeyApp يقوم بتضمين خادم MCP مع 15 أداة - البحث، والتوافر، والحجز، و(بموافقتك) حجوزاتك الخاصة - لـ Claude و ChatGPT و Cursor وأي عميل قادر على استخدام MCP.OAuth الموافقة بمستويات أذونات دقيقة؛ إلغاء الموافقة في أي وقت من لوحة التحكم → المطور.

Settings → Connectors → Add custom connector
Name: LeyApp
URL:  https://leyapp.es/api/mcp/mcp

Claude opens the LeyApp consent screen — sign in, pick a
permission level, and you're connected.

سجل التغييرات

واجهة برمجة التطبيقات v1 مخصصة للإضافة فقط: تُضاف الحقول، ولا يُعاد تسميتها أو تُحذف. ستُصدر التغييرات الجذرية كإصدار جديد مع فترة إيقاف مدتها 90 يومًا، يُعلن عنها هنا وعبر ملفات Deprecation/Sunset.