API راهی است که یک نرم‌افزار «بپرسد» (مثلاً رزروهای فردا چیست؟) یا «دستور بدهد» (این تاریخ را ببند)؛ وب‌هوک برعکس است: نرم‌افزار خودش وقتی اتفاقی افتاد خبر می‌دهد (رزرو ثبت شد). ابزارهای بدون‌کد مثل Zapier، Make و n8n این دو را به هم وصل می‌کنند تا «وقتی الف شد، ب را انجام بده» را بدون برنامه‌نویسی بسازید. ارزششان برای میزبانی که ماهی ده رزرو دارد معمولاً کمتر از هزینه‌ی راه‌اندازی و نگهداری‌شان است؛ برای مجموعه‌ای با ده‌ها رزرو در ماه و چند نفر تیم، می‌تواند ساعت‌ها کار تکراری را حذف کند.
فرق API و وب‌هوک در یک مثال
فرض کنید می‌خواهید وقتی رزرو جدید ثبت شد، پیامی به گروه تیم برود. با API باید هر چند دقیقه یک اسکریپت بپرسد «رزرو جدیدی هست؟» (polling)؛ بیشتر پرسیدن‌ها بی‌نتیجه است و بین رزرو و پیام تأخیر می‌افتد. با وب‌هوک، نرم‌افزار رزرو همان لحظه یک درخواست HTTP به نشانی‌ای که شما داده‌اید می‌فرستد و بقیه کار با ابزار گیرنده است.
نکته‌ی عملی: هر نرم‌افزاری API یا وب‌هوک ندارد. برای نمونه Hostaway وب‌هوک رویدادهایی مثل ایجاد و ویرایش رزرو دارد و در مستندش هشدار می‌دهد که رویدادها ممکن است نامرتب برسند. Airbnb هم طبق منابع تجاری که خواندم API را فقط در اختیار شرکای تأییدشده (کانال‌منیجرها و PMSها) می‌گذارد و میزبان تکی مستقیم به آن دسترسی ندارد؛ منبع رسمی خودِ Airbnb را پیدا نکردم، پس قبل از برنامه‌ریزی روی آن، از فروشنده‌ی نرم‌افزارتان بپرسید. برای تفاوت اتصال iCal و API به مقاله‌ی چنل منیجر و همگام‌سازی نگاه کنید.
پنج سناریوی نمونه با ورودی و خروجی
سناریو | رویداد (ورودی) | کار خودکار (خروجی) | ارزش |
|---|---|---|---|
اعلان به تیم | رزرو ثبت یا لغو شد | پیام در گروه پیام‌رسان | زیاد، کم‌ریسک |
ثبت در صفحه‌گسترده | رزرو جدید | یک ردیف در Google Sheets برای گزارش | متوسط |
کد قفل | پرداخت تأیید شد | ساخت کد زمان‌دار و ارسال به مهمان | زیاد، ولی پرریسک |
یادآوری مانده‌حساب | ۳ روز تا ورود و مانده > ۰ | پیام یادآوری به مهمان | متوسط |
وظیفه‌ی تحویل | چک‌اوت ثبت شد | کارت وظیفه در Trello برای تیم | متوسط |
سناریوی کد قفل را با احتیاط بسازید: اگر رویداد پرداخت دوبار برسد یا نامرتب برسد، ممکن است دو کد ساخته شود یا کد قبل از تأیید نهایی برود. قواعد مدیریت کد در مقاله‌ی ورود غیرحضوری و قفل هوشمند آمده است. اعلان و ثبت در صفحه‌گسترده برعکس، اگر اشتباه شوند ضرری ندارند و برای شروع بهترند.
امنیت: کلید API و وب‌هوک
کلید API مثل رمز عبور است: هر که داشته باشد با اختیارات صاحبش عمل می‌کند. چند قاعده:
کلید را در پیام‌رسان، ایمیل و ویدئوی آموزشی نفرستید؛ برای هر اتصال یک کلید جدا بسازید تا بتوانید فقط همان را باطل کنید.
در صورت امکان کلید فقط‌خواندنی یا محدود به همان کار بگیرید. کلیدی که اجازه‌ی حذف رزرو دارد برای ارسال اعلان لازم نیست.
کلید فردی که از تیم رفته را همان روز عوض کنید.
برای وب‌هوک، راهنمای Stripe سه قاعده‌ی عمومی دارد که برای هر وب‌هوکی صدق می‌کند. اول، امضا را بررسی کنید: فرستنده بدنه‌ی درخواست را با یک راز مشترک با HMAC-SHA256 امضا می‌کند و بدون بررسی آن، هر کسی می‌تواند درخواست جعلی بفرستد و مثلاً «پرداخت موفق» را شبیه‌سازی کند. دوم، زمان امضا را کنترل کنید تا درخواست قدیمیِ ضبط‌شده دوباره ارسال (replay) نشود؛ کتابخانه‌های Stripe پیش‌فرض ۵ دقیقه دارند. سوم، رویدادها ممکن است تکراری یا نامرتب برسند؛ شناسه‌ی رویدادهای پردازش‌شده را نگه دارید تا یک پرداخت دوبار اثر نکند، و پاسخ ۲xx را زود بدهید و کار سنگین را بعداً انجام دهید.
اگر از Zapier یا Make استفاده می‌کنید، بسیاری از این‌ها را خودِ ابزار برایتان انجام می‌دهد؛ اما اگر نشانی وب‌هوک را خودتان ساخته‌اید (مثلاً در n8n)، نشانی را حدس‌ناپذیر نگه دارید و امضا یا یک توکن محرمانه در سربرگ را الزامی کنید. فهرست OWASP API Security Top 10 (۲۰۲۳) هم یادآوری خوبی است که مشکل بزرگ APIها بیشتر «دسترسی بیش از حد به داده‌ی دیگران» و «احراز هویت ضعیف» است، نه هک پیچیده.
در ایران چه چیزی عملاً در دسترس است؟
منبع رسمی‌ای برای اینکه Zapier یا Make برای کاربران ایرانی در دسترس هستند یا نه پیدا نکردم؛ تحریم‌های آمریکا ارائه‌ی خدمات به ایران را محدود می‌کند و بسیاری از سرویس‌های ابری آمریکایی به همین دلیل مسدودند یا حساب ایرانی را می‌بندند، ولی وضعیت دقیق هر سرویس را خودتان با ساخت حساب آزمایشی بسنجید و به حساب آن تکیه‌ی تجاری نکنید. جایگزین عملی، ابزار متن‌باز n8n است که می‌توانید روی سرور خودتان نصب کنید (مستندات n8n نسخه‌ی Community را رایگان معرفی می‌کند؛ شرایط مجوز را در سایت رسمی‌اش بخوانید). تلگرام، اسلک و گوگل‌شیت هم از ایران ممکن است فیلتر یا محدود باشند؛ دسترسی پایدار آن‌ها را برای تیم بسنجید، چون اتوماسیونی که به سرویس ناپایدار وصل است، بی‌صدا خراب می‌شود.
کی صفحه‌گسترده و کار دستی کافی است؟
محاسبه‌ی ساده: اگر کاری ماهی ۲۰ بار و هر بار ۲ دقیقه طول می‌کشد، حدود ۴۰ دقیقه در ماه است؛ ساخت و نگهداری یک اتصال معمولاً بیش از آن وقت می‌برد (فرض کنید). اتصال وقتی می‌ارزد که کار تکراری، پرتعداد و قاعده‌مند باشد و خرابی آن جبران‌پذیر. پیش از هر اتوماسیون چک کنید: کار را یک بار دستی و درست انجام داده‌اید؟ اگر اتصال قطع شود چه کسی متوجه می‌شود؟ نسخه‌ی دستی جایگزین دارید؟ معیار کلی‌تر تصمیم در نقشه‌ی ابزارهای اتوماسیون اقامتگاه آمده است.
شاه‌کلید و اتصال ابزارها
در کد شاه‌کلید API عمومی، کلید API، وب‌هوک یا اتصال Zapier پیدا نشد؛ یعنی اتصال خودکار به ابزار بیرونی ندارد. آنچه هست خروجی اکسل است (مثل خروجی گزارش درآمد، گزارش بدهی‌ها) و امکان ورود هزینه‌ها از فایل اکسل، که می‌توانند ورودی یک صفحه‌گسترده‌ی تحلیلی شما باشند. اگر اتصال خودکار برایتان حیاتی است، این را هنگام انتخاب نرم‌افزار در نظر بگیرید و معیارهایش را در راهنمای انتخاب نرم‌افزار مدیریت اقامتگاه ببینید.
سؤال‌های پرتکرار
برای شروع کدام اتصال را بسازم؟
اعلان رزرو جدید و لغو به گروه تیم؛ اگر اشتباه کند فقط یک پیام اضافه یا گم می‌شود.
اگر اتصال بی‌صدا قطع شود چه؟
یک بررسی هفتگی بگذارید: تعداد رزروهای هفته در نرم‌افزار را با تعداد ردیف‌های صفحه‌گسترده یا پیام‌ها مقایسه کنید. اگر نخواند، اتصال را متوقف و دستی ادامه دهید.
وب‌هوک را بدون امضا هم می‌شود استفاده کرد؟
برای اعلان‌های بی‌اهمیت بله، ولی هر وب‌هوکی که پول، دسترسی یا قفل را تحت‌تأثیر می‌گذارد باید امضا یا توکن محرمانه داشته باشد.
مطالب مرتبط
اتوماسیون اقامتگاه؛ ابزارها و مرز انسان — نقشه‌ی ابزارهای فناوری برای میزبان (PMS، کانال‌منیجر، پیام خودکار، قیمت‌گذاری، قفل و حسگر)، معیار تصمیم برای…
اتصال نرم‌افزار اقامتگاه به حسابداری — چه داده‌ای از نرم‌افزار رزرو به حسابداری می‌رود، نقشه‌ی حساب‌ها چطور ساخته می‌شود، چرا ودیعه درآمد نیست، و نسخه‌ی…
دستیار هوش مصنوعی مهمان اقامتگاه — دستیار هوش مصنوعی فقط وقتی به مهمان درست جواب می‌دهد که از راهنمای مکتوب خودتان بخواند. اینجا سازوکار RAG، ریسک پاسخ…
نظرها