واجهة التقارير

١. أنشئ مفتاحًا

مالك المكتب فقط ينشئ المفاتيح: «الربط والتكاملات» ← «واجهة التقارير» ← «مفتاح جديد». اختر اسمًا والصلاحيات ومدة الانتهاء. يظهر المفتاح (يبدأ بـ evak_) مرة واحدة، احفظه ككلمة مرور. يمكن إلغاؤه في أي وقت فيتوقف فورًا.

٢. أرسل المفتاح

في ترويسة Authorization، بإحدى طريقتين. لا تضع المفتاح في الرابط أبدًا.

curl -H "Authorization: Bearer evak_YOUR_KEY" \
  "https://app.evacore.io/api/v1/leads?limit=100"

# Basic auth. Any user name, the key as the password (what Power BI uses):
curl -u "api:evak_YOUR_KEY" "https://app.evacore.io/api/v1/deals?updated_since=2026-10-01T00:00:00Z"

# CSV for Excel / Power BI. Every matching row in one response:
curl -u "api:evak_YOUR_KEY" "https://app.evacore.io/api/v1/properties?format=csv&fields=title,city,price,status" -o properties.csv

٣. شكل الرد

JSON بترميز UTF-8 والنص العربي كما هو. الأوقات بتوقيت UTC بصيغة ISO 8601، والمبالغ بالريال نصوصًا بخانتين عشريتين ("1500000.00") حتى لا تفقد دقتها. الحقل الفارغ null.

{
  "object": "list",
  "resource": "leads",
  "data": [
    {
      "id": "0e7b6a52-3c55-4a8e-b0a4-7c4d1f2e9a31",
      "name": "محمد العتيبي",
      "phone": "+966501234567",
      "status": "جديد",
      "budget": "1500000.00",
      "created_at": "2026-10-01T09:15:01.902Z",
      "updated_at": "2026-10-03T12:40:22.118Z"
    }
  ],
  "has_more": true,
  "next_cursor": "WyIyMDI2LTEwLTAzVDEyOjQwOjIyLjExODQ1MVoiLCIwZTdi…",
  "next": "/api/v1/leads?limit=100&cursor=WyIyMDI2…"
}

الصفحة فيها 100 سجل افتراضيًا وحتى 1000 بـ limit. اختر الحقول بـ fields (مفصولة بفواصل؛ id يأتي دائمًا). format=csv يرجع كل السجلات في رد واحد بأسماء الحقول في السطر الأول.

٤. المزامنة التدريجية

1. السجلات مرتبة من الأقدم تغييرًا إلى الأحدث. اطلب الصفحة الأولى، ثم مرّر next_cursor في cursor حتى يصبح has_more = false.
2. احفظ آخر next_cursor. في المزامنة التالية أرسله فيصلك فقط ما أُنشئ أو تغيّر بعده، كل سجل يعود كاملًا، فحدّثه عندك بالـ id.
3. أو استخدم updated_since بوقت آخر مزامنة ناقص 5 دقائق (لتغطية العمليات التي تُحفظ متأخرة) وحدّث بالـ id.
4. السجلات المحذوفة لا تظهر في المزامنة التدريجية: أعد السحب الكامل دوريًا (أسبوعيًا مثلًا).

٥. الربط مع Power BI

1. Power BI Desktop ← Get data ← Web.
2. الصق رابط الجدول بصيغة CSV، مثل: https://app.evacore.io/api/v1/leads?format=csv
3. في نافذة الدخول اختر Basic: اسم المستخدم أي كلمة (مثل api)، وكلمة المرور هي المفتاح. اختر المستوى https://app.evacore.io ليُستخدم المفتاح لكل الجداول.
4. إن ظهر العربي برموز غريبة: في المعاينة اختر File origin = 65001: Unicode (UTF-8).
5. كرر «Web» لكل جدول تحتاجه (deals، properties، projects، units، reservations، activities، tasks، agents، teams) واربطها بالحقول *_id.
6. بعد النشر في Power BI Service: Settings ← Data source credentials ← Basic بالمفتاح نفسه، ثم فعّل Scheduled refresh.

Excel يعمل بالطريقة نفسها: Data ← From Web ← الرابط نفسه ← Basic.

الكتابة وإعادة المحاولة

استخدم POST /api/v1/leads أو POST /api/v1/properties للإنشاء، وPATCH على الرابط نفسه مع /{id} للتعديل. تتطلب العملية leads:write أو properties:write؛ صلاحية read لا تسمح بالكتابة. يمكن تعديل حالة العميل وإسناده لموظف المبيعات في المكتب نفسه، أو تعديل العقار وحالته. راجع وصف OpenAPI للحقول والقيم المسموحة.

أرسل JSON مع Idempotency-Key فريد لكل عملية (من 1 إلى 128 حرفاً مرئياً). إعادة الطلب نفسه بالمفتاح نفسه تعيد الاستجابة الأصلية دون تكرار التعديل. تغيير محتوى الطلب أو مساره يعيد 409. عند 503 أعد المحاولة بالمفتاح نفسه. تغيير حالة عقار مرتبط بوحدة مشروع يتم من مسار الحجوزات، والإسناد المشترك النشط يُحسم من المكتب أولاً.

يعرض المالك عدد الطلبات لكل مفتاح ولكل يوم خلال آخر 30 يوماً بتوقيت الرياض، من صفحة مفاتيح الواجهة. تُحسب محاولات القراءة والكتابة وإعادة الطلب والرفض مرة واحدة لكل طلب موثّق. يشترك الجميع في حد 120 في الدقيقة؛ CSV يستهلك 10 من الحد ويُحسب طلباً واحداً.

٦. الحدود والأخطاء

كل خطأ بالشكل: { "error": { "code": "…", "message": "…" } }. الكتابة تتطلب صلاحية مستقلة ومفتاح Idempotency-Key.

٧. الجداول وحقولها

المواصفة الكاملة بصيغة OpenAPI 3.1: https://app.evacore.io/api/v1/openapi.json