API عمومی و وب‌هوک‌ها
با API عمومی تسکیـ داده بخوانید و بنویسید و با وب‌هوک، رویدادها را به سرویس‌های بیرونی بفرستید.
وقتی یکپارچه‌سازی‌های آماده پاسخگو نیستند، می‌توانید خودتان تسکیـ را به سیستم‌های دیگر وصل کنید. دو مسیر وجود دارد: API برای وقتی که شما از تسکیـ داده می‌خواهید، و وب‌هوک برای وقتی که تسکیـ باید به سیستم شما خبر بدهد.
برای وصل کردن کار کد به وظیفه‌ها لازم نیست خودتان وب‌هوک بسازید: اتصال به GitHub و اتصال به GitLab رویدادها را خودشان دریافت می‌کنند و پول‌ریکوئست‌ها، کامیت‌ها و ایشوها را با شناسهٔ وظیفه لینک می‌کنند.
API عمومی
API تسکیـ نسخه‌بندی‌شده است (/api/v1) و پاسخ‌ها در یک ساختار یکسان برمی‌گردند. نمای کلی نقطه‌های پایانی در صفحه مستندات API است و مرجع کامل ماشین‌خوان در نشانی /api-docs/openapi.json (OpenAPI 3.1) در دسترس است.
- به تنظیمات › توکن‌های API بروید، برای توکن نام بگذارید، دسترسی‌هایش را انتخاب کنید (مثلاً task:write برای ساخت وظیفه) و مدت اعتبارش را تعیین کنید: ۳۰، ۹۰ یا ۳۶۵ روز.
- توکن را همان لحظه کپی کنید؛ فقط یک‌بار نمایش داده می‌شود.
- توکن را در سربرگ Authorization همه‌ی درخواست‌ها بفرستید: Authorization: Bearer <token>. توکن به‌جای شما عمل می‌کند و فقط کارهایی را انجام می‌دهد که خودتان در تسکیـ اجازه‌اش را دارید.
- نقطه پایانی موردنظر را در مرجع پیدا کنید. مثلاً POST /api/v1/tasks با raw_input (عنوان) و project_id یک وظیفه می‌سازد.
- پاسخ را بررسی کنید؛ خطاها با کد وضعیت و پیام مشخص برمی‌گردند.
محدودیت نرخ: تعداد درخواست در دقیقه به پلن بستگی دارد: رایگان ۱۰، حرفه‌ای ۳۰، اولتیمیت ۵۰، تجاری ۱۰۰ و تجاری پلاس ۵۰۰ درخواست در دقیقه. اگر از سقف عبور کنید پاسخ محدودیت نرخ می‌گیرید و باید کمی صبر کنید.
وب‌هوک‌ها
وب‌هوک برعکس API کار می‌کند: به‌جای اینکه شما مرتب از تسکیـ بپرسید «چیزی تغییر کرده؟»، تسکیـ به آدرس شما پیام می‌فرستد.
- در بخش یکپارچه‌سازی‌های فضای کاری، وب‌هوک تازه‌ای بسازید.
- آدرس مقصد (Endpoint) را وارد کنید؛ باید عمومی و در دسترس باشد.
- رویدادهایی را که می‌خواهید دریافت کنید انتخاب کنید.
- وب‌هوک را آزمایش کنید تا مطمئن شوید مقصد پاسخ درست می‌دهد.
- پس از فعال‌سازی، هر بار رویداد رخ دهد پیام ارسال می‌شود.
در اتوماسیون‌ها هم می‌توانید «آدرس وب‌هوک» بگذارید تا اجرای یک قاعده، سرویس بیرونی شما را صدا بزند. این ساده‌ترین راه برای اتصال بدون نوشتن کد سمت تسکیـ است.
امنیت و نگهداری
- حداقل دسترسی: برای هر ادغام یک توکن جدا با کمترین دسترسی لازم بسازید.
- چرخش توکن: توکن‌های قدیمی و بی‌استفاده را باطل کنید.
- HTTPS: آدرس وب‌هوک باید HTTPS باشد.
- پایداری مقصد: اگر مقصد پاسخ ندهد، ارسال ناموفق ثبت می‌شود؛ سلامت سرویس مقصد را پایش کنید.
نیازمند پلن: تعداد یکپارچه‌سازی‌های فعال به پلن بستگی دارد: رایگان ۱، حرفه‌ای ۵، اولتیمیت ۱۰ و تجاری ۲۰ مورد.
خطاها و رفع اشکال
بیشتر مشکل‌های ادغام به چند علت تکراری برمی‌گردند. پیش از هر چیز کد وضعیت پاسخ را ببینید؛ معمولاً خودش می‌گوید مشکل کجاست.
- ۴۰۱: توکن نامعتبر یا منقضی؛ توکن تازه بسازید.
- ۴۰۳: توکن معتبر است اما دسترسی لازم را ندارد.
- ۴۰۴: شناسه اشتباه یا منبعی که به آن دسترسی ندارید.
- ۴۲۲: داده ارسالی معتبر نیست؛ پیام خطا فیلد مشکل‌دار را می‌گوید.
- ۴۲۹: از سقف نرخ عبور کرده‌اید؛ فاصله بین درخواست‌ها را بیشتر کنید.
طراحی ادغام پایدار
ادغامی که فقط در حالت خوش‌بینانه کار می‌کند، در عمل مرتب می‌شکند. چند اصل ساده ادغام را پایدار نگه می‌دارد.
- برای درخواست‌های ناموفق تلاش مجدد با فاصله فزاینده بگذارید.
- پاسخ‌ها را ذخیره کنید تا در صورت قطعی موقت، داده از دست نرود.
- به تغییرهای احتمالی ساختار پاسخ مقاوم باشید؛ فیلدهای ناشناخته را نادیده بگیرید نه اینکه خطا بدهید.
- برای وب‌هوک، پردازش را از دریافت جدا کنید و سریع پاسخ بدهید.
- لاگ نگه دارید تا موقع بروز مشکل بدانید کدام درخواست ناموفق بوده است.
توکن‌های شخصی API در تنظیمات › توکن‌های API ساخته می‌شوند؛ توکن ابزارهای هوش مصنوعی در دسترسی برنامه‌نویسی و توکن‌ها توضیح داده شده است. برای اتصال بدون کد اتصال به Zapier را ببینید.