برای استفاده از HTTP Request در n8n کافی است در نود، آدرس API و متد را مشخص کنید، نوع احراز هویت را از Credentials انتخاب کنید، هدرهایی مثل Content-Type را اضافه کنید و بدنه JSON را یا با فیلد JSON/RAW یا به شکل آبجکت با عبارت ={{ … }} بسازید. بعد از اجرا، با فعال کردن Full Response وضعیت، هدرها و بدنه پاسخ را ببینید و در صورت نیاز، فلو را براساس آن ادامه دهید.

پیش نیاز و درک سریع نود HTTP Request

HTTP Request نود عمومی n8n برای فراخوانی هر API است؛ از REST تا سرویس‌های داخلی. این نود همه متدهای رایج (GET/POST/PUT/PATCH/DELETE) را پشتیبانی می‌کند، با Credentials امن احراز هویت می‌کند و می‌تواند پاسخ را به شکل JSON ساده‌شده یا پاسخ کامل برگرداند. به طور خلاصه:

  • URL، Method و Authentication را تنظیم کنید.
  • Headers، Query Params و Body را بر اساس مستندات API بسازید.
  • از Expressions یعنی ={{ … }} برای مقادیر پویا استفاده کنید.
  • Full Response را برای مشاهده statusCode و headers روشن کنید.

اجرای سریع یک GET برای تست اتصال

  1. یک ورکفلو جدید بسازید و یک نود HTTP Request اضافه کنید.
  2. Method را روی GET و URL را روی آدرس API آزمایشی قرار دهید (مثلا مسیر وضعیت سرویس شما).
  3. در قسمت Options، گزینه Simplify را خاموش کنید تا پاسخ کامل ببینید.
  4. Execute Node را بزنید و فیلدهای statusCode، headers و body را بررسی کنید.

بررسی نتیجه و خطایابی اولیه

اگر statusCode در بازه 200–299 بود، اتصال درست است. کدهای 401/403 یعنی مشکل احراز هویت، 404 یعنی URL یا پارامتر مسیر اشتباه و 429 یعنی نرخ درخواست‌ها زیاد است. برای بازیابی‌های کنترل‌شده و گزارش‌پذیر، از الگوی مدیریت خطا و Retry On Fail در n8n استفاده کنید.

ارسال بدنه JSON؛ امن‌تر با آبجکت Expression

بهترین روش برای ساخت بدنه JSON، استفاده از Expression و ساخت آبجکت جاوااسکریپتی است؛ نه کنار هم گذاشتن رشته‌ها. این کار مشکل کوتیشن و کاراکترهای خط جدید را حذف می‌کند.

  1. در نود HTTP Request، Method را روی POST بگذارید.
  2. Header Content-Type: application/json را اضافه کنید.
  3. گزینه JSON/RAW Parameters را فعال کنید.
  4. در فیلد Body، روی آیکون Expression کلیک کنید و یک آبجکت بسازید.

نمونه عملی (ثبت متادیتای Yoast در وردپرس از طریق REST API) که در ورکفلو مقالات کدیتی استفاده شد:

={{ {
  meta: {
    yoast_title: $json.title,
    yoast_description: $json.excerpt
  },
  featured_media: $json.featuredMediaId
} }}

این روش به دلیل آبجکت بودن، مستقل از کوتیشن در عنوان یا وجود خط جدید در متن، JSON معتبر تولید می‌کند. روش نادرست با رشته‌سازی ممکن است با یک کوتیشن اضافی JSON را خراب کند:

="{
  \"meta\": {
    \"yoast_title\": \"" + $json.title + "\",
    \"yoast_description\": \"" + $json.excerpt + "\"
  },
  \"featured_media\": " + $json.featuredMediaId + "
}"

اگر مقدار $json.title شامل ” یا \n باشد، این رشته به راحتی نامعتبر می‌شود. با آبجکت Expression این ریسک از بین می‌رود و n8n JSON معتبر می‌سازد.

هدرها و احراز هویت (API Key، Basic، Bearer، OAuth2)

برای اکثر APIها به حداقل یک هدر و یک روش احراز هویت نیاز دارید:

  • Content-Type: برای JSON مقدار application/json.
  • Accept: در صورت نیاز application/json یا نوع دیگر.
  • Authorization: برای توکن‌ها به شکل Bearer <token> یا فرمت اختصاصی API.

از Credentialهای n8n استفاده کنید تا توکن را در متن فلو ننویسید:

  1. در بخش Credentials یک Credential متناسب بسازید (API Key/Header Auth، Basic Auth یا OAuth2).
  2. در نود HTTP Request، Authentication را روی همان Credential بگذارید.
  3. در صورت نیاز به هدرهای سفارشی دیگر، آن‌ها را در بخش Headers اضافه کنید.

اگر ناچارید هدر را پویا بسازید، از Expression استفاده کنید:

={{ "Bearer " + $json.access_token }}

در OAuth2، Credential را یک بار پیکربندی کنید؛ نود به طور خودکار توکن را تازه‌سازی می‌کند و شما فقط Credential را انتخاب می‌کنید.

Query و Path Params؛ آدرس‌های پویا

برای پارامترهای مسیر، URL را پویا کنید:

={{ "https://api.example.com/users/" + $json.userId + "/posts" }}

برای Query Params، یا آن‌ها را در بخش Query Parameters اضافه کنید یا URL را پویا بسازید. نمونه ترکیبی:

={{ 
  "https://api.example.com/search?q=" 
  + encodeURIComponent($json.query) 
  + "&page=" + $json.page 
}}

صفحه بندی (Pagination) با حلقه

بیشتر APIها داده‌های حجیم را صفحه‌بندی می‌کنند. الگوی عمومی در n8n:

  1. یک نود Set بسازید و مقدار page را از 1 شروع کنید.
  2. HTTP Request را طوری تنظیم کنید که page را از ورودی بگیرد.
  3. با IF بررسی کنید آیا پاسخ خالی شده یا به آخر رسیده‌اید (مثلا طول آرایه کمتر از اندازه صفحه است).
  4. اگر ادامه دارد، با یک نود Set مقدار page++ کنید و به ابتدای حلقه برگردید (از Loop یا Split In Batches کمک بگیرید).

برای انتخاب طرح صفحه بندی مناسب و خطاهای رایج، مطلب آموزش طراحی Pagination در API مفید است.

مدیریت خطا، Retry و سقف نرخ (Rate Limit)

خطاها اجتناب‌ناپذیرند. چند اصل عملی:

  • گزینه Continue On Fail را فقط وقتی روشن کنید که خطا را در مراحل بعدی مدیریت می‌کنید.
  • برای زمان‌بندی Retry (مثلا Backoff نمایی) از ترکیب IF + Wait + شمارنده استفاده کنید یا از الگوی Retry On Fail و Error Trigger در n8n بهره ببرید.
  • برای 429 یا هدر Retry-After، زمان انتظار را از پاسخ بخوانید و سپس Retry کنید. اگر API سهمیه دارد، می‌توانید فشار را با Trigger زمان‌بندی شده کاهش دهید؛ آموزش زمان بندی ورکفلو با Schedule Trigger و Cron راهگشاست.
  • آشنایی با مفاهیم Rate Limiting به شما کمک می‌کند بدون نقض سیاست API کار کنید؛ به عنوان مقدمه، مطلب آموزش Rate Limiting در Laravel را ببینید.

ارسال فایل با Send Binary Data

اگر API آپلود فایل دارد:

  1. جایی در فلو فایل را بسازید یا بخوانید تا یک property باینری (مثلا data) داشته باشید.
  2. در HTTP Request، گزینه Send Binary Data را فعال کنید و نام property را تنظیم کنید.
  3. نوع ارسال را مطابق مستندات API (معمولا multipart/form-data) تنظیم کنید و سایر فیلدهای فرم را در Body Parameters اضافه کنید.

چک لیست سریع اجرای موفق

  • URL و Method دقیقا مطابق مستندات API هستند.
  • Credentials ایمن و انتخاب‌شده در نود وجود دارد.
  • Headers کلیدی: Content-Type و Authorization درستند.
  • Body به صورت آبجکت Expression ساخته شده است، نه رشته‌سازی.
  • Full Response برای مشاهده statusCode و headers در تست فعال است.
  • الگوی Pagination و Retry برای پایداری جریان پیاده‌سازی شده است.

اشتباهات رایج و رفع آن‌ها

  • Content-Type اشتباه: اگر JSON می‌فرستید و پاسخ 415 می‌گیرید، هدر application/json را اضافه کنید.
  • رشته‌سازی JSON: با وجود کوتیشن یا خط جدید در ورودی می‌شکند؛ از آبجکت Expression استفاده کنید.
  • توکن در متن: به جای قرار دادن توکن در Expression، از Credentials n8n بهره ببرید.
  • نادیده گرفتن 4xx/5xx: Full Response را روشن و مسیر خطا را جداگانه مدیریت کنید.
  • نادیده گرفتن نرخ: برای 429 از Wait و Retry-After استفاده کنید و زمان‌بندی اجرا را کنترل کنید.

الگوی پیشنهادی برای بیشتر APIها

  1. Trigger مناسب (مانند Schedule Trigger برای اجرای دوره‌ای).
  2. Set برای آماده‌سازی پارامترها و شمارنده صفحه.
  3. HTTP Request با URL پویا، Credentials و هدرها.
  4. IF برای تشخیص موفقیت/خطا یا پایان صفحه بندی.
  5. Loop برای ادامه صفحات یا تلاش مجدد کنترل‌شده.
  6. نودهای تبدیل داده و مقصد (DB، فایل، سرویس دیگر).

سوالات متداول

تفاوت JSON/RAW Parameters با Body Parameters در n8n چیست؟

در JSON/RAW بدنه را یکجا می‌سازید (ایده‌آل برای JSON پیچیده و Expression آبجکت). در Body Parameters هر کلید/مقدار را جداگانه تعریف می‌کنید و n8n بدنه را می‌سازد.

چگونه statusCode را در تصمیم‌گیری فلو استفاده کنم؟

گزینه Simplify را خاموش کنید تا پاسخ کامل برگردد؛ سپس با یک نود IF مقدار statusCode را بررسی و شاخه مناسب را اجرا کنید.

گام بعدی

اگر اتصال پایدار شد، الگوی صفحه بندی و Retry را اضافه کنید، اجرای دوره‌ای را با Schedule Trigger تنظیم کنید و گزارش‌گیری خطا را مستقل بسازید. این سه قدم، بیشتر سناریوهای یکپارچه سازی مبتنی بر API در n8n را تولیدمحور و قابل اعتماد می‌کند.