n8n

گرهٔ اجتماعی Quire برای n8n یک گرهٔ کنش برای REST API و یک گرهٔ راه‌انداز دارد که هنگام رخ دادن رویدادی در Quire، گردش‌کار را آغاز می‌کند. این گره هیچ وابستگی زمان‌اجرایی ندارد؛ بنابراین چیزی جز خودش به نمونهٔ n8n شما اضافه نمی‌کند.

نصب

در n8n، Settings را باز کنید، سپس به Community nodes بروید، Install را بزنید و @quire/n8n-node را وارد کنید. در n8n خودمیزبان، می‌توانید به‌جای آن در پوشهٔ کاربر n8n فرمان npm install @quire/n8n-node را اجرا و n8n را دوباره راه‌اندازی کنید.

اتصال

یک اعتبارنامه بسازید. دو نوع در دسترس است:

• Quire API Key: Base URL نشانی سازمان شما بدون اسلش پایانی است، مانند https://acme.quirelms.com. API Key کلیدی است که مدیر در /admin/integrations/api-keys ساخته و با qk_live_ آغاز می‌شود. فقط دامنه‌هایی را به آن بدهید که گردش‌کار لازم دارد.
• Quire OAuth2: برای گردش‌کارهایی که باید از طرف شخص مشخصی عمل کنند. یک کلاینت OAuth در /admin/integrations/oauth-clients با نشانی تغییرمسیر n8n ثبت کنید (n8n آن را در اعتبارنامه نشان می‌دهد)، سپس شناسهٔ کلاینت، راز و دامنه‌ها را وارد کنید.

کنش‌ها

گرهٔ Quire کاربران، دوره‌ها، ثبت‌نام‌ها، گروه‌ها، تکمیل‌ها، نمره‌ها، گواهی‌ها، تکلیف‌های ارسالی، تلاش‌های آزمون، برنامه‌ها، سفارش‌ها، ایمیل و سازمان‌ها را پوشش می‌دهد. برای هرکدام، هر جا API پشتیبانی کند عملیات فهرست‌کردن، دریافت، ایجاد، به‌روزرسانی و حذف وجود دارد؛ همچنین upsert بر پایهٔ شناسهٔ بیرونی در دسترس است و برای همگام‌سازی همین را می‌خواهید: یک گردش‌کار را دوبار اجرا کنید تا چیزی تکراری نشود.

عملیات از سند OpenAPI کوایر تولید شده‌اند، پس با فیلدهای مرجع API دقیقاً مطابقت دارند. هر عملیات را می‌توان به‌عنوان ابزاری برای عامل هوش مصنوعی n8n هم به کار برد؛ توضیح آن از مرجع API گرفته می‌شود.

فهرست‌ها به‌طور پیش‌فرض همهٔ صفحه‌ها را برمی‌گردانند. برای سازمان‌های بزرگ، Return All را خاموش کنید و سقف تعیین کنید.

راه‌انداز

گرهٔ Quire Trigger را اضافه کنید، اعتبارنامه را انتخاب و Events را برگزینید: رویدادی با نام مشخص مانند enrolment.created، یک حوزهٔ کامل مانند course.* یا همهٔ رویدادها. با فعال کردن گردش‌کار، گره اشتراک وب‌هوکی را در Quire برای نشانی n8n ایجاد می‌کند؛ با غیرفعال کردنش، اشتراک برداشته می‌شود.

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

نمونه: ایمیل خوشامدگویی پس از ثبت‌نام

1. Quire Trigger با رویداد enrolment.created.
2. گرهٔ Quire، منبع Users، عملیات Get، با شناسهٔ کاربر {{$json.data.user_id}}.
3. گرهٔ Quire، منبع Courses، عملیات Get، با شناسهٔ دوره {{$json.data.course_id}}.
4. گرهٔ ایمیل یا گفت‌وگو، با استفاده از نام شخص و عنوان دوره.

عیب‌یابی

• در همهٔ درخواست‌ها 401 می‌گیرید: نشانی پایه و کلید متعلق به دو سازمان متفاوت‌اند یا کلید لغو شده است.
• در یک عملیات 403 می‌گیرید: کلید دامنهٔ لازم را ندارد. آن را در /admin/integrations/api-keys اضافه کنید.
• راه‌انداز اجرا نمی‌شود: نشانی وب‌هوک n8n باید از طریق HTTPS برای Quire دسترس‌پذیر باشد. گزارش تحویل اشتراک را در /admin/webhooks بررسی کنید.