راهنما

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 تاریخچهٔ فنی را نشان می‌دهد. پردازش در جریان هنوز نتیجه ندارد. پیوند گزارش‌ها ۱۵ دقیقه معتبر است؛ برای پیوند تازه گزارش را دوباره بخوانید.

به‌روزرسانی مدیریت مشتریان

نرم‌افزار شما می‌تواند الگوهای دفتر را تغییر دهد، جستجوهای شخصی را ذخیره کند، یک بازدید را ثبت کند و یک فرایند پیگیری بسازد. از مجوزهای مدیریتی مناسب استفاده کنید و هر تغییر را تأیید کنید. ابتدا نسخه فعلی را بخوانید و اگر پاسخ از دست رفت، همان شناسه درخواست را نگه دارید. تکرار درخواست قدیمی نباید تغییر جدیدتری را برگرداند. آزمون محیط عملیاتی، جستجوها، بازدیدها و فرایندهای پیگیری را از جمله پاک‌سازی و لغو کلیدها بررسی می‌کند. الگوهای دفتر در این آزمون فقط خوانده شده‌اند؛ نوشتن به‌صورت محلی و در CI آزمایش شده است. راهنمای قابل دانلود چهار مسیر و حدود شواهد مربوط به آن‌ها را توضیح می‌دهد.

مقایسه دو نسخه ذخیره‌شده

دو شماره‌نسخهٔ موجود از یک فیلد متن گزارش ذخیره‌شده یا یک فیلد گفت‌وگوی ذخیره‌شده را بدون پردازش جدید هوش مصنوعی مقایسه کنید. این قرارداد به‌صورت محلی و در CI آزمایش شده است؛ آزمون CRM در محیط عملیاتی، رفتار مقایسه را در محیط عملیاتی اثبات نمی‌کند. سابقه مفقود با متن فعلی تکمیل نمی‌شود. تفاوت‌های طولانی با اعلام واضح کوتاه شدن، به حداکثر 8000 نویسه در هر طرف محدود می‌شوند. این مقایسه شامل PowerPoint، محاسبات پیشنهاد قیمت، نامه همراه یا قالب‌بندی نیست. مجوزهای فعلی خواندن و شرایط حریم خصوصی همچنان برقرارند.

پیشاپیش برآورد هزینه بخواهید

POST /generatieplan مراحل و اعتبار مورد انتظار برای گزارش، پیشنهاد قیمت یا گفتگو را نشان می‌دهد. از gebruik:lezen استفاده کنید. محاسبه و تنظیمات تیم مانند وب‌سایت است.

برآورد پردازش را شروع نمی‌کند و اعتبار کم نمی‌کند. قیمت حداکثری تضمین‌شده نیست. عدم‌قطعیت‌ها، مانند هزینهٔ خواندن فایل که هنوز مشخص نیست، را نشان دهید. شروع دوباره مجوزها و اعتبار را بررسی می‌کند.

راهنمای برآورد و نمونه‌ها را بگیرید

پردازش را از نرم‌افزار خود شروع کنید

API، پرونده‌ها، اسناد، بارگذاری، صدا، رونویسی، پوشه‌های مشتری، سبک‌ها، خروجی‌ها، گردش کار، Excel و پیام‌های هدفمند را متصل می‌کند. هر مسیر ورودی، مجوز، تأیید و بررسی نسخهٔ خود را دارد. پردازش و حسابداری اعتبار موجود همچنان معتبر است. پاسخ آغاز فقط دریافت را تأیید می‌کند؛ سپس وضعیت را بخوانید. فهرست، قراردادهای باز را مشخص می‌کند.

ابتدا پرونده بسازید

یک UUID بسازید و نگه دارید. PUT /dossiers/{id} را فقط با naam، حداکثر ۲۰۰ نویسه، بفرستید. 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. پیوندها ۱۵ دقیقه معتبرند. در 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 و جزئیات تحویل را بخوانید. خطاهای موقت حداکثر هشت بار تکرار می‌شوند؛ می‌توانید دور اضافه درخواست کنید. پذیرفته‌شده فقط یعنی سرور شما پیام را گرفته است. پردازش بعدی را همان‌جا بررسی کنید.

• راهنمای webhook، محدودیت و بازیابی را بگیرید
• نمونهٔ Node.js بررسی امضا را بگیرید

شبیه‌ساز اعلان واقعی نمی‌فرستد. گیرنده را با دادهٔ ساختگی و اتصال تولید جداگانه امتحان کنید. نمونه اعلان را بررسی می‌کند؛ سرور شما مسئول ذخیره و کارهای بعدی است.

کد خطا چه معنایی دارد؟

از کلید و داده‌های مشتری محافظت کنید

• کلید را فقط روی سرور استفاده کنید، نه در کد عمومی مرورگر.
• برای هر اتصال کلید جداگانه به‌کار ببرید و کلیدهای قدیمی را لغو کنید.
• کلیدها، نتایج یا پیوندهای موقت را در گزارش‌ها یا گفتگوهای عمومی نگذارید.
• داده‌های دریافت‌شدهٔ مشتری را طبق قواعد دسترسی سیستم خود نگه دارید.