اتصال به Zapier

اتصال Zapier در تسکیـ دو جهت دارد. در جهت اول، Zapها با فراخوانی نشانی‌هایی که تسکیـ برای فضای کاری شما می‌سازد، وظیفه می‌سازند، روی وظیفه دیدگاه می‌گذارند و وضعیت آن را تغییر می‌دهند. در جهت دوم، تسکیـ رویدادهای وظیفه‌ای را که انتخاب می‌کنید به نشانی Catch Hook یک Zap می‌فرستد تا آن Zap شروع شود. برای هیچ‌کدام لازم نیست حساب Zapier را به تسکیـ وصل کنید یا اپی در Zapier نصب کنید؛ همه‌چیز با مرحلهٔ آمادهٔ Webhooks by Zapier انجام می‌شود.

پیش از شروع

• فقط مالک یا مدیر فضای کاری می‌تواند نشانی‌ها را بسازد، رمز را ببیند یا عوض کند و Catch Hook اضافه کند. این کارها در برگهٔ «فضای کاری» صفحهٔ Zapier در «مرکز اپ‌ها» انجام می‌شود.
• در Zapier از اپ داخلی Webhooks by Zapier استفاده می‌کنید: مرحلهٔ POST برای فرستادن به تسکیـ و تریگر Catch Hook برای دریافت از تسکیـ.
• هر کاری که Zap در تسکیـ انجام می‌دهد به نام یک عضو انجام می‌شود. پیش از شروع تصمیم بگیرید Zapها به نام چه کسی کار کنند.

Zapها ← تسکیـ: ساخت نشانی‌ها و رمز

1. در تنظیمات، «مرکز اپ‌ها» را باز کنید، Zapier را انتخاب کنید و به برگهٔ «فضای کاری» بروید.
2. در بخش «Zapها ← تسکی» روی «ساخت نشانی‌ها» بزنید.
3. چهار نشانی ساخته می‌شود: «ساخت وظیفه»، «افزودن دیدگاه»، «تغییر وضعیت» و «آزمایش اتصال». هر نشانی شکل https://…/webhooks/zapier/{token}/tasks دارد و انتهای آن برای سه نشانی دیگر comments، status و ping است. بخش {token} مخصوص فضای کاری شماست؛ نشانی‌ها را با دکمهٔ کپی بردارید.
4. در ردیف رمز، روی «نمایش» بزنید و رمز را کپی کنید. هر بار نمایش رمز در گزارش ممیزی فضای کاری ثبت می‌شود.
5. «پروژهٔ پیش‌فرض وظایف جدید» را انتخاب کنید تا Zapی که پروژه نمی‌فرستد بداند وظیفه را کجا بسازد. اگر «هیچ» را نگه دارید، Zap باید project_id بفرستد.
6. در «Zapها به نام» عضوی را انتخاب کنید که وظیفه‌ها و دیدگاه‌ها با نام او ساخته شوند. Zap فقط کارهایی را می‌تواند بکند که همین عضو در تسکیـ مجاز است.

ساخت Zap برای فرستادن به تسکیـ

1. در Zapier، پس از تریگر دلخواه، یک مرحلهٔ Webhooks by Zapier با رویداد POST اضافه کنید.
2. در فیلد URL یکی از نشانی‌های تسکیـ را بچسبانید؛ مثلاً نشانی «ساخت وظیفه».
3. نوع بدنه را JSON یا form انتخاب کنید؛ تسکیـ هر دو را می‌پذیرد.
4. در بخش Data فیلدهای موردنیاز را از مراحل قبلی Zap نگاشت کنید.
5. در بخش Headers هدر X-Taskie-Secret را با مقدار رمز اضافه کنید.
6. برای اطمینان از درستی نشانی و رمز، اول نشانی «آزمایش اتصال» را امتحان کنید؛ پاسخ آن نام فضای کاری و عضوی را که Zapها به نام او کار می‌کنند برمی‌گرداند.

فیلدهای هر نشانی

• ساخت وظیفه (…/tasks): title (الزامی)، description، project_id، due_date (تاریخ میلادی مثل 2026-11-01)، priority (عدد ۱ تا ۵)، assignee_email (ایمیل یکی از اعضای همان پروژه) و idempotency_key. عنوان دقیقاً همان‌طور که فرستاده شود ثبت می‌شود.
• افزودن دیدگاه (…/comments): task (شناسه یا کلید وظیفه مثل TASK-12) و body (متن دیدگاه).
• تغییر وضعیت (…/status): task و status. وضعیت با نام آن در پروژه پیدا می‌شود و بزرگی و کوچکی حروف مهم نیست. یکی از واژه‌های سطح وضعیت، یعنی backlog، inprogress، done یا closed، هم اولین وضعیت از همان نوع را در پروژه انتخاب می‌کند؛ واژه‌های رایج todo (برای backlog)، in progress یا doing (برای inprogress) و completed (برای done) هم همین کار را می‌کنند.
• آزمایش اتصال (…/ping): فیلدی لازم ندارد.

نمونهٔ بدنهٔ JSON برای ساخت وظیفه: {"title": "Follow up with Acme", "due_date": "2026-11-01", "idempotency_key": "<id of the trigger record>"}. همین نمونه به‌صورت یک دستور curl در بخش «نمونهٔ درخواست» صفحهٔ Zapier هم آمده است.

جلوگیری از تکرار: اگر Zapier مرحله‌ای را دوباره اجرا کند، ممکن است همان درخواست دو بار برسد. در idempotency_key شناسهٔ رکوردی را بفرستید که Zap را شروع کرده است. اگر همان کلید دوباره برسد، تسکیـ کار تازه‌ای انجام نمی‌دهد و همان نتیجهٔ اول را همراه با "duplicate": true برمی‌گرداند.

پاسخ‌های تسکیـ

• ساخت وظیفه با کد 201 و بقیه با 200 پاسخ می‌دهند. بدنهٔ پاسخ شامل task_id، task_key، task_title و task_url است؛ افزودن دیدگاه comment_id و تغییر وضعیت نام وضعیت تازه را هم برمی‌گرداند. این مقدارها را در مراحل بعدی Zap به کار ببرید.
• اگر هدر X-Taskie-Secret نباشد یا نادرست باشد، پاسخ 401 است.
• اگر نشانی فعال نباشد، مثلاً چون اتصال قطع شده است، پاسخ 404 است.
• خطاهای داده با 422 و یک بدنهٔ JSON شامل message و errors برمی‌گردند؛ مثلاً وقتی نه project_id فرستاده شده و نه پروژهٔ پیش‌فرض تعیین شده، یا وظیفه‌ای با آن شناسه در این فضای کاری نیست.
• اگر عضوی که Zapها به نام او کار می‌کنند اجازهٔ آن کار را نداشته باشد، پاسخ 403 است.

امنیت نشانی‌ها و رمز

• هرکس نشانی و رمز را با هم داشته باشد می‌تواند به نام عضو انتخاب‌شده در فضای کاری کار کند؛ پس آن‌ها را مثل گذرواژه نگه دارید. هر کاری فقط داخل همین فضای کاری انجام می‌شود.
• رمز را هرگز در بدنهٔ درخواست نگذارید؛ فقط در هدر X-Taskie-Secret.
• با «رمز تازه» رمز جدیدی ساخته می‌شود. رمز قبلی تا ۲۴ ساعت کار می‌کند تا فرصت به‌روز کردن Zapها را داشته باشید.
• اگر عضو انتخاب‌شده دیگر به فضای کاری دسترسی نداشته باشد، درخواست‌ها رد می‌شوند تا مدیر عضو دیگری را انتخاب کند.

تسکیـ ← Zapها: شروع Zap با رویدادهای تسکیـ

1. در Zapier یک Zap تازه با تریگر Webhooks by Zapier و رویداد Catch Hook بسازید و نشانی آن را که با https://hooks.zapier.com/hooks/catch/ شروع می‌شود کپی کنید.
2. در تسکیـ، در بخش «تسکی ← Zapها» روی «افزودن Catch Hook» بزنید.
3. نشانی را در «نشانی Catch Hook» بچسبانید و اگر بخواهید یک «نام» مثل «وظایف جدید به Google Sheets» بنویسید.
4. رویدادها و پروژه‌ها را انتخاب کنید؛ برای هوک تازه فقط «وظیفهٔ جدید» از پیش انتخاب شده است.
5. روی «افزودن» بزنید. تسکیـ رمز امضای همین هوک را فقط یک بار نشان می‌دهد؛ همان لحظه کپی‌اش کنید.
6. برای اینکه Zapier نمونه‌ای از داده‌ها داشته باشد، از فهرست هوک‌ها «فرستادن پیام آزمایشی» را بزنید. تا رویدادی رخ ندهد یا پیام آزمایشی نفرستید، چیزی به هوک فرستاده نمی‌شود.

رویدادهای قابل انتخاب: «وظیفهٔ جدید»، «تغییر وضعیت»، «تکمیل وظیفه»، «افزودن مسئول»، «برداشتن مسئول»، «دیدگاه جدید»، «تغییر اولویت»، «تغییر موعد»، «افزودن برچسب» و «وظیفهٔ عقب‌افتاده». هر رویداد به‌صورت JSON ساده و یک‌سطحی فرستاده می‌شود تا در Zapier به‌راحتی نگاشت شود. فیلدها عبارت‌اند از event، event_label، occurred_at، task_id، task_key، task_title، task_url، task_status، task_status_level، task_priority، task_due_date، task_assignee، task_labels، project_id، project_name و changes. پیام آزمایشی علاوه بر این‌ها "is_sample": true دارد.

امضای درخواست‌ها: هر درخواست به هوک هدر X-Taskie-Signature به شکل t={unix time},v1={signature} دارد. مقدار v1 همان HMAC-SHA256 رشتهٔ {t}.{body} با رمز امضای هوک است، به‌صورت hex. هدر X-Taskie-Event هم نام رویداد را می‌گوید. گیرنده‌ای که بخواهد مطمئن شود درخواست از تسکیـ آمده، می‌تواند امضا را بررسی کند.

• اگر Zap خاموش یا حذف شود، Zapier هوک را دیگر نمی‌پذیرد. تسکیـ فرستادن به آن هوک را متوقف می‌کند و دلیلش را کنار آن نشان می‌دهد. اگر بعداً پیام آزمایشی تحویل شود، هوک دوباره فعال می‌شود.
• زیر هر هوک زمان «آخرین تحویل» یا دلیل مشکل دیده می‌شود. با «ویرایش» نام، رویدادها و پروژه‌ها را تغییر دهید و با «حذف» هوک را بردارید.

پیگیری و قطع اتصال

وظیفه‌ها و دیدگاه‌هایی که Zapها می‌سازند مثل همیشه در پروژه دیده می‌شوند و در فعالیت وظیفه برچسب Zapier دارند. روی کارت اتصال Zapier در برگهٔ «فضای کاری»، بخش «مدیریت» فراخوانی‌های اخیر را در «رویدادهای اخیر» نشان می‌دهد. با «قطع اتصال» نشانی‌های ورودی از کار می‌افتند و تسکیـ دیگر به Catch Hookها چیزی نمی‌فرستد؛ برای توقف کامل، Zapهای مربوط را در Zapier هم خاموش کنید.

اگر Zapier را با روش قدیمی وصل کرده‌اید

در نسخهٔ قبلی، مدیر یک Account ID و یک Webhook Secret وارد می‌کرد و Zap با هدرهای X-Zapier-Account-ID و X-Taskie-Zapier-Secret به نشانی /webhooks/zapier درخواست می‌فرستاد. Zapهایی که این‌طور ساخته شده‌اند همچنان مثل قبل کار می‌کنند، اما آن روش فقط اجرای Zap را به وظیفه‌های نام‌برده لینک می‌کند و دیگر برای ساختن اتصال تازه در دسترس نیست. برای ساختن وظیفه، دیدگاه یا تغییر وضعیت، Zapهای خود را به نشانی‌های تازه منتقل کنید. تا وقتی چنین اتصالی باشد، صفحهٔ Zapier در مرکز اپ‌ها یادآوری نشان می‌دهد؛ وقتی همهٔ Zapها منتقل شدند، اتصال قدیمی را از کارت خودش در همان صفحه قطع کنید.

اشتباه‌های رایج

• فرستادن رمز با نام هدر قدیمی یا داخل بدنه؛ هدر درست X-Taskie-Secret است.
• تعیین نکردن پروژهٔ پیش‌فرض و نفرستادن project_id؛ در این حالت ساخت وظیفه با خطای 422 رد می‌شود.
• فرستادن ایمیل کسی که عضو آن پروژه نیست در assignee_email؛ تسکیـ مسئول را فقط از میان اعضای همان پروژه می‌پذیرد.
• نفرستادن idempotency_key در Zapهایی که ممکن است دوباره اجرا شوند؛ بدون آن، هر تکرار یک وظیفهٔ تازه می‌سازد.
• فراموش کردن کپی رمز امضای Catch Hook؛ این رمز فقط یک بار نشان داده می‌شود. اگر لازمش دارید، هوک را حذف کنید و دوباره اضافه کنید.

گام بعدی: برای اتصال برنامه‌های خودتان به تسکیـ بدون Zapier، راهنمای API عمومی و وب‌هوک‌ها را ببینید. برای اعلام خبر وظایف در کانال‌های تیم، اتصال به Slack و اتصال به Discord را مرور کنید.