درخواست فرستادی و کد ۲۰۰ گرفتی. پیامک رفت؟ شاید. خیلی از سرویس‌های ایرانی در حالت خطا هم کد ۲۰۰ برمی‌گردانند و وضعیت واقعی را جایی داخل بدنه‌ی جواب می‌نویسند. اعتبار تمام‌شده، متنی که با الگوی تاییدشده نمی‌خواند، شماره‌ی نامعتبر؛ همه با ۲۰۰ برمی‌گردند.
اتصال n8n به سرویس‌های ایرانی سخت نیست، ولی در آموزش‌های خارجی نیامده و همین چند جزئیات کوچک است که یک ورک‌فلوی سالم‌نما را به یک ورک‌فلوی واقعا سالم تبدیل می‌کند. در ادامه به پرسش‌هایی جواب می‌دهیم که هنگام وصل کردن پیامک، ربات پیام‌رسان و درگاه پرداخت پیش می‌آیند.
«برای سرویس من گره‌ی آماده نیست. حالا چه؟»
n8n برای سرویس‌های ایرانی گره‌ی اختصاصی ندارد و احتمالا نخواهد داشت. مهم هم نیست. گره‌ی عمومی HTTP Request هر چیزی را که یک API دارد پوشش می‌دهد. مهارتی که لازم داری خواندن مستندات است، و برای هر سرویس تازه فقط سه چیز را باید پیدا کنی:
- احراز هویت کجاست: در نشانی درخواست، در سربرگ، یا در بدنه؟
- موفقیت چه شکلی است: کد HTTP کافی است، یا بدنه هم یک فیلد وضعیت دارد؟
- سقف تعداد درخواست چقدر است و وقتی به آن بخوری چه کدی برمی‌گردد؟
پرسش دوم از همه مهم‌تر است، به همان دلیلی که در شروع این نوشته آمد.
«کل مستندات را باید بخوانم؟»
نه. یک مثال را دنبال کن. سرویسی که در آن وصل می‌شویم فرضی است. مستنداتش دو نمونه جواب نشان می‌دهد. در حالت موفق، بدنه یک فیلد status با مقدار ۲۰۰ دارد، یک فیلد data با شناسه‌ی رکورد، و پیام ok. در حالت ناموفق، status برابر ۴۱۸ است، data خالی است و پیام می‌گوید اعتبار کافی نیست. کد HTTP در هر دو حالت ۲۰۰ بوده است.
- احراز هویت: در مستندات دنبال نمونه‌ی curl بگرد. سریع‌ترین راه است، چون همیشه کل درخواست را یک‌جا نشان می‌دهد. در این مثال کلید در سربرگ بود، پس اعتبارنامه از نوع سربرگ ساخته می‌شود، نه از نوع پارامتر نشانی.
- شکل موفقیت: چون کد HTTP در هر دو نمونه یکی است، شرط موفقیت باید روی فیلد status داخل بدنه باشد. یک شرط دوم هم لازم است: اینکه data خالی نباشد، چون ممکن است وضعیت درست باشد و داده نیامده باشد.
- سقف درخواست: معمولا زیر عنوان rate limit یا در جدول کدهای خطاست. اگر پیدا نکردی، فرض کن سخت‌گیر است و از همان اول درخواست‌ها را با گره‌ی Split In Batches و کمی تاخیر بفرست. برداشتنش بعدا آسان است؛ اضافه کردنش بعد از بسته شدن حساب سخت.
- شاخه‌ی خطا: متن فیلد پیام را به ورک‌فلوی هشدارت بفرست، وگرنه فقط می‌دانی «نشد»، نه «چرا نشد».
سه پرسش، حدود ده دقیقه، و کل مستندات خوانده نشد. اگر پرسش دوم را نپرسیده بودی، ورک‌فلوی تو با اعتبار تمام‌شده هم موفق گزارش می‌شد. ورک‌فلوی خطا هم فعال نمی‌شد، چون از دید n8n چیزی نشکسته بود.
«پیامک را چطور بفرستم که بی‌صدا شکست نخورد؟»
با گره‌ی HTTP Request و متد POST. دو مسیر معمول داری: ارسال ساده برای پیام عمومی، و ارسال الگویی برای کد تایید. ارسال الگویی سریع‌تر تحویل می‌شود و برای کد یک‌بارمصرف همان را به کار ببر.
کلید را در Credential نگه دار، نه داخل خود گره. کلیدی که در گره نوشته شود، در فایل صادرشده‌ی ورک‌فلو هم می‌آید، و آن فایل را روزی برای همکار یا پشتیبان یا در یک تیکت می‌فرستی. بعد از ارسال، یک گره‌ی IF بگذار که بدنه‌ی جواب را بررسی کند؛ نام فیلدها را از مستندات همان سرویس بردار. شاخه‌ی نادرست به هشدار وصل شود.
چهار چیزی که در عمل به آن برمی‌خوری:
- اعتبار تمام شده. کد ۲۰۰، پیامی نرفته. فقط از بدنه معلوم می‌شود.
- متن با الگو نمی‌خواند. روی خط خدماتی، متن باید دقیقا همان الگوی ثبت‌شده باشد؛ یک کاراکتر اضافه یعنی رد شدن.
- شماره‌ی نامعتبر. برای همین شماره‌ها باید پیش از ارسال یک‌شکل شوند؛ ارقام فارسی به لاتین، پیش‌شماره‌ها یکسان.
- سقف درخواست. ارسال دسته‌ای با تاخیر.
تلاش دوباره روی گره‌ی پیامک با تلاش دوباره روی گره‌ای که فقط چیزی را می‌خواند یکی نیست. اگر سرویس کند باشد و سه بار مهلت تمام شود ولی پیام‌ها رفته باشند، سه پیامک رفته و سه بار پول داده‌ای. پیش از ارسال یک کلید یکتا ثبت کن تا تکرار جلوی خودش را بگیرد.
«وب‌هوک ربات را ساختم. کسی جز پیام‌رسان می‌تواند صدایش بزند؟»
بله، هر کسی که نشانی‌اش را بداند. اگر ورک‌فلوی پشت آن پیامک می‌فرستد، هر درخواستی که به آن برسد از حساب تو خرج می‌کند. «نشانی را به کسی نداده‌ام» دفاع نیست؛ نشانی در لاگ سرویس طرف مقابل، در تاریخچه‌ی مرورگر و در هر جایی که ثبتش کرده‌ای هست.
مراحل ساخت ساده است: ربات می‌سازی و توکن می‌گیری، یک گره‌ی Webhook با متد POST درست می‌کنی و نشانی‌اش را به‌عنوان وب‌هوک ربات ثبت می‌کنی، ساختار پیام ورودی را می‌خوانی و یک جواب ساده برمی‌گردانی. سه لایه‌ی حفاظت را هم اضافه کن:
- مسیر وب‌هوک را حدس‌ناپذیر بگذار؛ یک رشته‌ی تصادفی بلند. این اولین لایه است، نه تنها لایه.
- اگر سرویس امضا یا توکن در درخواست پشتیبانی می‌کند، آن را بررسی کن.
- اگر نمی‌کند، دست‌کم فیلدهای ضروری را بررسی کن و درخواست بدشکل را دور بریز. وقتی ورک‌فلوی پشت وب‌هوک هزینه دارد، این بررسی محتوایی اختیاری نیست.
«درگاه پرداخت را هم با n8n بزنم؟»
برای فهمیدن جریان، بله. برای پیاده‌سازی واقعی، نه. جریان پرداخت سه قدم دارد: درخواست پرداخت، فرستادن کاربر به درگاه، و تایید نهایی بعد از بازگشت. قدم سوم را هرگز جا نینداز. برگشتن کاربر به سایت تو به معنای پرداخت موفق نیست تا وقتی خودت از درگاه تایید نگرفته‌ای. مبلغی که درگاه تایید می‌کند هم باید دقیقا با مبلغی که انتظار داشتی برابر باشد. و سفارش با کلید یکتا ثبت شود، چون کاربر می‌تواند صفحه‌ی بازگشت را دو بار باز کند.
ولی قلب پرداخت را با n8n نساز. «مبلغ را تایید کن و سفارش را ثبت کن» باید یا هر دو انجام شود یا هیچ‌کدام. ورک‌فلو می‌تواند درست میان این دو قدم بمیرد؛ آن‌وقت پول گرفته شده و سفارشی ثبت نشده، و مسئولیتش با توست، نه با ابزار.
مرز درست این است: پرداخت و ثبت سفارش در کد اپلیکیشن، با تراکنش پایگاه داده. بعد از تایید موفق، n8n کارهای جانبی را انجام می‌دهد: پیامک تشکر، ثبت در شیت، خبر به تیم. این‌ها اگر بشکنند فاجعه نیست. اگر کسی گفت کل فروشگاهش را با n8n ساخته، بپرس پرداخت نیمه‌تمام را چطور مدیریت می‌کند.
«مطمئن نیستم خطای سرویس چه شکلی است»
پس آن را با دست خودت بساز، پیش از اینکه شرط بنویسی. یک درخواست موفق بزن و شکل دقیق جوابش را نگه دار. بعد عمدا یک درخواست ناموفق بزن: کلید را یک کاراکتر خراب کن، یک پارامتر اجباری را حذف کن، یا مقداری بیرون از محدوده بفرست، مثل شماره‌ای پنج‌رقمی. شرط IF را از مقایسه‌ی همین دو نمونه بنویس، نه از حدس یا از کپی مستندات.
بعضی سرویس‌ها در حالت آزمایشی خطا برنمی‌گردانند. این خودش یافته است. آن‌وقت محتاط باش و شرطت را طوری بنویس که فقط شکل دقیق موفقیت را قبول کند و هر چیز دیگری را خطا حساب کند. این از حدس زدن شکل خطا امن‌تر است.
یک سرویس را از صفر وصل کن
سرویسی انتخاب کن که تا حالا با آن کار نکرده‌ای؛ هدف یاد گرفتن روش است، نه آن سرویس خاص.
- فقط سه پرسش را از مستندات جواب بده و جواب‌ها را بنویس.
- یک Credential بساز؛ کلید داخل گره نباشد.
- یک جواب موفق و یک جواب ناموفق واقعی بگیر و هر دو را نگه دار.
- شرط موفقیت را از مقایسه‌ی آن دو بنویس.
- ورک‌فلو را به هشدار وصل کن و مطمئن شو متن واقعی خطای سرویس در هشدار دیده می‌شود.
- فایل ورک‌فلو را صادر کن و داخلش دنبال کلید بگرد. اگر پیدا شد، جایش اشتباه است.
آنچه کهنه می‌شود و آنچه نه
جزئیات APIها عوض می‌شوند؛ نام فیلدها، نشانی‌ها، حتی شکل الگوها. چیزی که از این نوشته باید بماند روش است: سه پرسش، بررسی بدنه به‌جای کد HTTP، کلید در اعتبارنامه، احتیاط با تلاش دوباره روی کاری که پول خرج می‌کند، و مرز روشن برای پرداخت. اگر می‌خواهی اتصال n8n به سرویس‌های ایرانی را کنار هشدار خرابی، کلید یکتا و پشتیبان‌گیری روی یک پروژه‌ی کامل تمرین کنی، جزئیات این دوره را ببین.
