دليل الاستخدام

واجهة API للمطورين

اربط برنامجك بإجراءات صريحة للمصادر والمعالجة والنتائج والإدارة. يصف هذا الدليل واجهة API المتاحة ضمن حدود الإصدار الموثّقة. يبقى المستخدم والصلاحيات والتخزين والأرصدة مرتبطين بحساب Rapportly.

جهّز التكامل في ثلاث خطوات

1. 1
   اختر المستخدم والبيئة والصلاحيات

   افتح الحساب → التكاملات. استخدم مفتاح اختبار للمحاكي الخيالي ومفتاح إنتاج منفصل للإجراءات الحقيقية ببيانات خيالية. يمنح المسؤول الصلاحيات الضرورية فقط وميزانية مناسبة.

2. 2
   تدرّب على الاستلام والأخطاء

   ابدأ بالمحاكي، ثم استورد عقود API وراجع الأمثلة الاصطناعية. احتفظ بالأسرار على خادمك؛ التعديلات معطّلة افتراضيًا في المجموعة.

3. 3
   تابع مهمة كاملة

   احفظ المدخلات ومعرّف المهمة، وتحقق من البدء والحالة النهائية، واقرأ النتيجة ونزّل ملفًا متاحًا وراجع الاستهلاك. نفّذ هذه التجربة في بيئة معتمدة فقط.

أنشئ مفتاح API

العنوان الأساسي

https://api.rapportly.io/api/rapportly/v1

المفتاح يخص مستخدمًا

يفوّض المفتاح صلاحيات مستخدم واحد. يحدد المسؤول البيئة وسقف الصلاحيات والميزانية الشهرية والانتهاء. يفعّل العضو المفتاح المجهّز ويرى السر مرة واحدة. يتحقق كل طلب أيضًا من صلاحيات المستخدم والباقة والكائن الحالية. تستخدم إدارة المفاتيح جلسة مستخدم، وتستخدم إجراءات الإنتاج مفتاح API. خزّن الأسرار على الخادم وألغِ المفتاح المفقود من الحساب → التكاملات. لأحداث Zapier عقد مستقل.

GET https://api.rapportly.io/api/rapportly/v1/ping
Authorization: Bearer rply_<jouw_sleutel>

استخدم عقودًا وأمثلة محددة

تصف OpenAPI الإنتاجية عقود الشفرة وتعلّم المدخلات أو الردود الجزئية. يعرض الجرد المخططات المفتوحة. تبدأ مجموعة Postman بعنوان غير صالح ومفاتيح فارغة وتعديلات معطّلة. استورد للمراجعة وأرسل بيانات خيالية بقرار واعٍ في بيئة معتمدة. لم يُختبر الاستيراد بعد.

• نزّل مواصفات OpenAPI الإنتاجية
• نزّل مجموعة Postman الاصطناعية
• نزّل الخطوات من المصدر إلى التنزيل
• نزّل جرد المخططات والأجزاء المفتوحة

تدرّب أولًا بمهام خيالية

أنشئ مفتاح اختبار وجرّب المهام الجارية والنتائج والأخطاء والميزانية غير الكافية. يستخدم المحاكي أمثلة ثابتة ولا يستهلك أرصدة.

1. من الحساب → التكاملات أنشئ أو فعّل مفتاح Test بالصلاحيات التي تريد تجربتها.
2. اطلب GET /test/scenarios واختر إجراءً من الرد. تتبع القائمة صلاحياتك الحالية.
3. أرسل POST /test/opdrachten مع actie وscenario فقط: succes أو verwerking_mislukt أو creditbudget_bereikt أو toegang_geweigerd. لكل تدريب جديد Idempotency-Key مستقل.
4. احفظ opdracht_id. عند bezig اقرأ GET /test/opdrachten/{id} بعد نحو خمس ثوانٍ. افحص الحالة دائمًا: قد يحتوي HTTP200 على فشل معالجة أيضًا.

POST https://api.rapportly.io/api/rapportly/v1/test/opdrachten
Authorization: Bearer rply_test_<jouw_testsleutel>
Idempotency-Key: test-rapport-0001
Content-Type: application/json

{
  "actie": "rapport.start",
  "scenario": "succes"
}

يتطلب المثال وجود rapport.start في قائمتك. بعد مشكلة اتصال كرر البيانات وIdempotency-Key نفسيهما.

• نزّل دليل المحاكي
• نزّل مجموعة Postman التدريبية
• نزّل OpenAPI للمحاكي

اجلب ما تحتاجه فقط

ابحث في مجلدات العملاء والمحادثات والتقارير المتاحة. يعرض /acties الإجراءات والصلاحيات، و/gebruik الميزانية والحجوزات، و/verzoeken السجل التقني. المعالجة الجارية لا تملك نتيجة بعد. روابط التقارير صالحة لمدة 15 دقيقة؛ أعد قراءة التقرير للحصول على رابط جديد.

تحديث إدارة العملاء

يمكن لبرنامجك تعديل قوالب المكتب وحفظ عمليات البحث الشخصية وتسجيل زيارة وإنشاء مسار متابعة. استخدم صلاحيات الإدارة المناسبة وأكّد كل تغيير. اقرأ النسخة الحالية أولاً واحتفظ بمعرّف الطلب نفسه إذا فُقد الرد. يجب ألا تؤدي إعادة طلب قديم إلى التراجع عن تغيير أحدث. يتحقق اختبار الإنتاج من عمليات البحث والزيارات ومسارات المتابعة، بما يشمل التنظيف وإلغاء المفاتيح. اقتصرت معالجة قوالب المكتب فيه على القراءة؛ واختُبرت الكتابة محلياً وفي CI. يصف الدليل القابل للتنزيل المسارات الأربعة وحدود الأدلة لكل منها.

مقارنة نسختين محفوظتين

قارن رقمي إصدار موجودين لحقل نص التقرير المحفوظ نفسه أو لحقل المحادثة المحفوظ نفسه، دون معالجة جديدة بالذكاء الاصطناعي. اختُبر هذا العقد محلياً وفي CI؛ ولا يثبت اختبار CRM في الإنتاج سلوك المقارنة في الإنتاج. لا يُستكمل السجل المفقود بالنص الحالي. تُختصر الفروق الطويلة إلى 8000 حرف كحد أقصى لكل جانب، مع إشارة واضحة إلى الاختصار. لا تشمل المقارنة PowerPoint أو حسابات عروض الأسعار أو الرسائل المرفقة أو التنسيق. تظل صلاحيات القراءة وشروط الخصوصية الحالية سارية.

اطلب تقدير تكلفة مسبقًا

يعرض POST /generatieplan الخطوات والأرصدة المتوقعة لتقرير أو عرض سعر أو محادثة. استخدم gebruik:lezen. يتبع الحساب وإعدادات الفريق الموقع نفسه.

لا يبدأ التقدير معالجة ولا يخصم أرصدة. ليس سعرًا أقصى مضمونًا. اعرض جوانب عدم اليقين مثل تكلفة قراءة ملفات غير معروفة بعد. يتحقق البدء مجددًا من الصلاحيات والأرصدة.

نزّل دليل التقدير والأمثلة

ابدأ المعالجة من برنامجك

تربط واجهة API الملفات والمستندات والرفع والصوت والتفريغ ومجلدات العملاء والأنماط والمخرجات وسير العمل وExcel والرسائل الموجهة. لكل مسار مدخلاته وصلاحياته وتأكيده وفحص نسخته. تبقى المعالجة واحتساب الأرصدة الحاليان ساريين. تؤكد استجابة البدء الاستلام؛ اقرأ الحالة بعد ذلك. يوضح الجرد العقود المفتوحة.

أنشئ ملفًا أولًا

أنشئ UUID واحفظه. أرسل PUT /dossiers/{id} مع naam فقط، بحد أقصى 200 محرف. يعني 201 الإنشاء و200 تكرارًا مطابقًا. يخص الملف مستخدم المفتاح ومؤسسته ولا يستهلك أرصدة. تعيد المدخلات المختلفة 409، والملفات غير المتاحة أو المحذوفة 404. يقرأ GET /dossiers/{id} الحقلين naam وklant_id بصلاحية القراءة.

PUT https://api.rapportly.io/api/rapportly/v1/dossiers/00000000-0000-4000-8000-000000000002
Authorization: Bearer rply_<jouw_sleutel>
Content-Type: application/json

{ "naam": "Voorbeeldproject" }

تقرير أو عرض سعر أو عرض تقديمي

ابدأ بـ dossierId وnotities. الحقل tier اختياري: basis أو standaard أو max. دون ملف نمط يُستخدم تنسيق محايد. يمكنك إضافة قيم متاحة لـ stijlprofielId وklantId وbronOpnameIds وtaal. يجب أن يناسب النمط نوع المستند. تستخدم عروض السعر إعدادات الشركة وترقيمًا آمنًا؛ لا ترسلها API إلى العميل.

POST https://api.rapportly.io/api/rapportly/v1/rapporten
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-rapport-2026-0001
Content-Type: application/json

{
  "dossierId": "00000000-0000-4000-8000-000000000002",
  "notities": "Team Atlas besprak de training. Noor plant de volgende bijeenkomst op donderdag.",
  "tier": "standaard"
}

احفظ versie_id وتابع GET /rapporten/{versie_id}، أيضًا لعروض السعر والعروض التقديمية. عند klaar يحتوي resultaat على الملفات المتاحة: export_url لـ PDF وexport_url_docx لـ Word وexport_url_pptx لـ PowerPoint. الروابط صالحة 15 دقيقة. عند mislukt افحص المعالجة والاستهلاك قبل بدء مهمة جديدة تلقائيًا بمفتاح آخر.

نزّل الخطوات من المصدر إلى التنزيل

ارفع أمثلة أنماطك

أرسل من ملف إلى ثلاثة ملفات كمجموعة كاملة. يستخدم Rapportly فحوص الملفات والأنماط نفسها الموجودة في الموقع. التخزين والأرصدة تخص المستخدم المرتبط.

1. أرسل الملفات والاسم ونوع المستند والنطاق الشخصي أو الجماعي والتأكيد الصريح ومعرّفًا ثابتًا. يتطلب نمط الفريق مسؤولًا أو قائد فريق.
2. احفظ معرّف الاستلام واقرأ الحالة. يعني مستلَم أن المجموعة الكاملة محفوظة؛ قد تليها مراجعة المعاينة والموافقة.
3. بعد الانقطاع كرر الطلب نفسه تمامًا دون إنشاء نمط ثانٍ. يمكن تكرار الرفع غير المكتمل لمدة ثلاثين يومًا، ثم يُنظف بصورة مضبوطة.

نزّل دليل أمثلة الأنماط وmultipart ومعالجة الأخطاء

اربط التقويم أو صندوق البريد

يمنح المستخدم موافقته بنفسه لدى Google أو Microsoft. يتابع برنامجك الطلب ويمكنه إيقاف الاتصال بقرار صريح. كلمات مرور المزوّد ورموزه لا تظهر في الرد.

استخدم verbindingen:beheren للاتصالات وagenda:lezen للمواعيد. يتطلب الإرسال أيضًا صلاحية إرسال وطلبًا صريحًا.

احفظ رقم الطلب والمعرّف والأساس الحالي. كرر الطلب المفقود بدقة؛ يجب ألا يزيل طلب فصل قديم اتصالًا أحدث.

يمكن لـ API اختيار صندوق البريد الافتراضي بصلاحيات الإدارة والإرسال. اقرأ الاختيار والاتصال الحاليين أولًا. لا يغير تكرار قديم اختيارًا أحدث؛ تحتفظ مهام الإرسال القائمة بمرسلها.

نزّل خطوات الموافقة والمواعيد والفصل والاسترداد

نتائج محادثة من نص

أرسل نصًا مفرغًا لا يقل عن مئة محرف. تابع النتيجة عبر gesprek_id. الحقول الاختيارية: titel وtier وklantId وtaal.

POST https://api.rapportly.io/api/rapportly/v1/gesprekken
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-gesprek-2026-0001
Content-Type: application/json

{
  "transcript": "Team Atlas bespreekt uitsluitend een fictieve oefening. Het team plant een training en verzamelt algemene voorbeeldvragen zonder klantgegevens.",
  "titel": "Kennismaking"
}

قراءة النسخ اللغوية الموجودة

اقرأ النتائج اللغوية الموجودة. اختُبرت مسارات سير العمل الموصوفة للبدء والإيقاف المؤقت والاستئناف والاستعادة محلياً وفي CI؛ ولا يتحقق اختبار CRM في الإنتاج من هذه المعالجة اللغوية. استخدمها فقط في بيئة مُصرّح بها لهذا الغرض. يظل المستخدم الأصلي والمفتاح والمصدر والتكاليف مرتبطين بالطلب. تظل حالة المصدر الحالية والصلاحيات والميزانية والتسوية المالية المتحقق منها مطلوبة؛ ولا يمنح المصدر المنتهي الصلاحية أو المحذوف صلاحية بدء جديد. تظل المعالجة المجمعة مع تفعيل لغة ثانية مغلقة، بما في ذلك الإعدادات الموروثة. ويظل الاستكمال المدفوع لنتيجة ترجمة واحدة مفقودة مستبعداً.

GET https://api.rapportly.io/api/rapportly/v1/gesprekken/00000000-0000-4000-8000-000000000001/taalvarianten
Authorization: Bearer rply_<jouw_sleutel>

تلقَّ إشعارًا عند اكتمال المعالجة

يمكن لـ Rapportly إرسال مراجع تقنية إلى خادمك. استرجع بعدها المحتوى بصلاحيات القراءة المناسبة دون السؤال المستمر عن التقدم.

1. أنشئ مستقبِل HTTPS وسجّله عبر POST /webhooks بصلاحية webhooks:beheren. استخدم مفتاح الإنتاج نفسه للمهام المعنية.
2. تحقق من التوقيع على بايتات الرسالة الأصلية واحفظ كل معرّف حدث مرة واحدة. أكّد الاستلام بعد التخزين الآمن مع المهمة التالية. يجب ألا ينشئ التكرار مهمة ثانية.
3. اقرأ GET /webhook-afleveringen وتفاصيل التسليم. تُعاد محاولة الأخطاء المؤقتة ثماني مرات كحد أقصى؛ يمكنك طلب جولة إضافية. تعني مقبول أن خادمك استلم الرسالة فقط. افحص المعالجة اللاحقة في نظامك.

• نزّل دليل webhooks والحدود والاسترداد
• نزّل مثال Node.js للتحقق من التوقيع

لا يرسل المحاكي إشعارات حقيقية. جرّب المستقبِل ببيانات خيالية واتصال إنتاج منفصل. يتحقق المثال من الإشعار؛ يتولى خادمك التخزين والإجراءات اللاحقة.

ماذا يعني رمز الخطأ؟

احمِ المفتاح وبيانات العملاء

• استخدم المفتاح على خادمك فقط، وليس في شفرة متصفح عامة.
• استخدم مفتاحًا مستقلًا لكل تكامل وألغِ المفاتيح القديمة.
• لا تضع المفاتيح أو النتائج أو الروابط المؤقتة في سجلات أو محادثات عامة.
• خزّن بيانات العملاء المسترجعة وفق قواعد الوصول في نظامك.