نحوه ارسال درخواست POST با curl: مرجع کامل

تقریباً بیست میلیارد نصب curl در حال حاضر در جایی از جهان اجرا می‌شود. این عدد از سازنده این ابزار، دنیل استنبرگ، می‌آید که تقریباً به تنهایی آن را نگهداری می‌کند. curl در داخل روترها، ماشین‌ها، ماهواره‌ها، تلویزیون‌های هوشمند، سرورهای لینوکس که بیشتر وب عمومی را در خود جای داده‌اند و هر زمان اجرای اصلی LLM وجود دارد. از بین تمام افعال HTTP که این نصب‌ها به کار می‌برند، POST بار سنگین را بر دوش می‌کشد. POST در curl روشی است که اکثر توسعه‌دهندگان برای اولین بار با آن آزمایش، اشکال‌زدایی یا با API ادغام می‌شوند.

گزارش وضعیت API در سال ۲۰۲۵ پستمن، میزان پذیرش REST را ۹۳٪ اعلام می‌کند. ۸۲٪ سازمان‌ها اکنون حداقل تا حدی با API-first کار می‌کنند. POST فعلی است که هر زمان که داده‌ها را ایجاد، ارسال یا به سرور منتقل می‌کنید، به آن مراجعه می‌کنید. حجم کار هوش مصنوعی این روند را بیشتر تسریع کرد. ترافیک API منتسب به استفاده از هوش مصنوعی در سال ۲۰۲۴، ۷۳٪ افزایش یافت (پستمن، ۲۰۲۴)، و اکنون مستندات هر ارائه‌دهنده LLM با یک قطعه کد POST به عنوان "اولین فراخوانی" متعارف باز می‌شود.

این مرجع، تمام شکل‌هایی که یک درخواست POST با استفاده از curl می‌تواند به خود بگیرد را بررسی می‌کند، از حداقل یک خط تا یک فراخوانی کاری علیه یک API پرداخت رمزنگاری واقعی. هدف: چیزی که بتوانید از آن پیست کنید، نه فقط بخوانید. ارسال داده‌ها به سرور برای اولین بار یا بازسازی یک کنترل‌کننده وب‌هوک در ساعت ۲ بامداد، الگوهای زیر آنچه را که واقعاً نیاز دارید پوشش می‌دهند.

جدول زیر نسخه خلاصه شده است. برگه تقلب با توضیحات و اهداف، گزینه‌های خط فرمان curl که اغلب هنگام ارسال درخواست‌های POST استفاده می‌شوند را پوشش می‌دهد. هر کدام در بخش‌های بعدی توضیح داده شده‌اند.

درک درخواست POST در curl و متد HTTP

یک درخواست curl POST، یک درخواست HTTP POST است که با متد POST ارسال و از خط فرمان اجرا می‌شود. خود ابزار curl وظیفه خود را "انتقال داده" در بیش از دوجین پروتکل توصیف می‌کند که HTTP تنها یکی از آنهاست. POST به این معنی است: اینجا مقداری داده وجود دارد، کاری با آن انجام دهید. Payload در بدنه درخواست قرار می‌گیرد، نه در URL. به همین دلیل است که POST ایجاد منابع، ارسال فرم و هر چیزی که حاوی اعتبارنامه باشد را مدیریت می‌کند. GET داده‌ها را در رشته پرس‌وجو قرار می‌دهد که برای هر پروکسی و تاریخچه هر مرورگری قابل مشاهده است. POST این کار را نمی‌کند.

بیشتر آموزش‌ها از یک نکته‌ی کوچک اما مفید صرف نظر می‌کنند. `-d` و curl auto-switches را به POST ارسال کنید. `-X POST` که مشخص‌کننده‌ی یک روش درخواست سفارشی برای استفاده است، اختیاری است. بسیاری از مثال‌ها هنوز آن را شامل می‌شوند، زیرا خواندن `-X POST` در کنار یک payload، هدف را در یک نگاه آشکار می‌کند.

PUT و POST اغلب آنقدر با هم اشتباه گرفته می‌شوند که ارزش دارد به طور مشخص به آنها بپردازیم. PUT یک منبع را در یک مکان شناخته شده جایگزین می‌کند. POST یک منبع جدید ایجاد می‌کند یا داده‌ها را برای پردازش در یک نقطه پایانی عمومی ارسال می‌کند.

سینتکس پایه‌ای curl POST و پرچم -d در عمل

حداقل مقدار POST در curl یک خط است:

```

curl -d "username=arya&age=16" https://api.example.com/users

```

همین. درخواست POST، بدنه form-urlencoded، بدون هیچ دردسری. `-d` سه وظیفه انجام می‌دهد: بار داده را در بدنه درخواست قرار می‌دهد، متد درخواست را به POST تبدیل می‌کند و `Content-Type: application/x-www-form-urlencoded` را به عنوان هدر پیش‌فرض اضافه می‌کند. من معمولاً فرم کمی طولانی‌تر را در هر صورت پیست می‌کنم، زیرا هدف POST در بررسی کد بهتر خوانده می‌شود:

```

curl -X POST -d "username=arya&age=16" https://api.example.com/users

```

بایت‌های مشابه روی سیم. آرگومان‌های درخواست مشابه. از هر کدام که تیم شما اسکن آن را آسان‌تر می‌داند استفاده کنید. علامت `-d` نیروی محرکه‌ای است که برای ارسال داده‌ها به سرور از خط فرمان استفاده می‌شود و نود درصد از کارهایی را که یک توسعه‌دهنده backend در curl انجام می‌دهد، مدیریت می‌کند: فراخوانی‌های shell، آزمایش‌های webhook، اهداف Makefile، مراحل اقدامات GitHub.

سه پسرعموی نزدیک `-d`. `--data-binary` بایت‌های شما را دست‌نخورده نگه می‌دارد؛ `-d` معمولی، خطوط جدید را حذف می‌کند و یک payload باینری را خراب می‌کند. `--data-urlencode` percent-encodes برای شما: `--data-urlencode "name=I am Daniel"` به صورت `name=I%20am%20Daniel` می‌رسد. `--data-raw` دریچه فرار است وقتی که یک مقدار با `@` شروع می‌شود و curl نباید یک فایل را بخواند. چندین پرچم `-d` با `&` به هم متصل می‌شوند. برای فرم‌ها مناسب است. هرگز برای JSON.

یک نکته‌ی آخر: نقل قول کردن. نقل قول‌های تکی در اطراف payload، پوسته را از تفسیر `$` یا \ها باز می‌دارد. اگر آنها را فراموش کنید، ساعت دو بامداد را صرف این می‌کنید که بپرسید چرا نیمی از داده‌های POST شما از دست رفته است.

این جزئیات مهم هستند زیرا خود curl یکی از کلاینت‌های HTTP است که بیشترین آزمایش را روی آن انجام داده‌ایم. گزارش گذشته‌نگر استنبرگ در دسامبر ۲۰۲۵، هشت نسخه در آن سال را فهرست کرد. نه CVE، که همگی دارای رتبه پایین یا متوسط بودند. ۲۱۷۹ مورد آزمایش فعال، ۲۳۲ مورد بیش از دوازده ماه قبل. نسخه ۸.۱۱.۱، دسامبر ۲۰۲۴، CVE-2024-11053 (یک نشت اعتبارنامه netrc-and-redirect) را وصله کرد. نسخه پایدار فعلی تا اواخر آوریل ۲۰۲۶، curl 8.20.0 است. هر کسی که پایین‌تر از ۷.۸۲.۰ گیر کرده باشد، هنوز هیچ پرچم `--json` ندارد و به الگوی قدیمی‌تر سه پرچمی برمی‌گردد.

ارسال داده‌های JSON با curl با استفاده از --json یا -H

JSON زبان میانجی APIهای REST در سال ۲۰۲۶ است. دو راه برای ارسال آن با curl وجود دارد. اینکه کدام یک استفاده شود کاملاً به نسخه curl موجود در دستگاه بستگی دارد.

الگوی کلاسیک سه پرچم، از CentOS 6 به بعد در همه جا کار می‌کند:

```

curl -X پست \

-H "نوع محتوا: application/json" \

‎-d '{"title":"Tea","quantity":2}' \‎

https://api.example.com/orders

```

خلاصه‌نویسی مدرن، از نسخه ۷.۸۲.۰ (مارس ۲۰۲۲) به بعد در دسترس است:

```

curl --json '{"title":"Tea","quantity":2}' https://api.example.com/orders

```

پرچم `--json` سه کار انجام می‌دهد. `Content-Type: application/json` را تنظیم می‌کند. `Accept: application/json` را تنظیم می‌کند. بدنه را ارسال می‌کند. همچنین ترکیب می‌کند: اگر `--json` را بیش از یک بار ارسال کنید، فایل‌های اجرایی به هم متصل می‌شوند. هنگام اتصال قطعات JSON به یک نقطه پایانی استریمینگ مفید است.

برای فایل‌های JSON که در یک فایل ذخیره شده‌اند، مسیر فایل را با پیشوند `@` شروع کنید. ارسال داده‌ها از یک فایل زمانی به الگوی استاندارد تبدیل می‌شود که شیء JSON برای چسباندن درون‌خطی خیلی بزرگ باشد، یا زمانی که در کنترل نسخه وجود داشته باشد، یا زمانی که اسکریپت دیگری آن را تولید کند:

```

curl -X POST -H "نوع-محتوا: application/json" -d @order.json https://api.example.com/orders

curl --json @order.json https://api.example.com/orders

```

الگوی دوم داده‌ها را از فایلی به نام `order.json` می‌خواند و آن را با تمام هدرهای مناسب ارسال می‌کند. برای محتوای JSON بزرگ یا احتمالاً باینری، `--data-binary @file.json` گزینه امن‌تری است. این الگو خطوط جدید را حذف نمی‌کند، کاراکترهای خاص را تفسیر نمی‌کند و داده‌های باینری خام را به نقطه پایانی ارسال می‌کند که به جای فیلدهای فرم، انتظار بایت دارد. الگوی سوم داده‌ها را از طریق `-d @-` از stdin می‌خواند. هنگام ارسال خروجی از دستور دیگر مستقیماً به یک curl POST مفید است.

جدول زیر چهار شکل رایج JSON را در برابر یک نقطه پایانی واحد ترسیم می‌کند:

این موضوع بیش از گذشته اهمیت دارد. هر ارائه‌دهنده‌ی اصلی LLM - OpenAI، Anthropic، Mistral، Google - اسناد API خود را با یک مثال curl POST که دقیقاً از این شکل استفاده می‌کند، باز می‌کند. ترافیک مبتنی بر هوش مصنوعی در سال 2024، 73 درصد به حجم کلی فراخوانی API اضافه کرد (Postman). curl اکنون مرجع متعارف برای "چگونه این نقطه‌ی پایانی را فراخوانی کنم" است.

نوع محتوا، هدرها و آنچه curl فرض می‌کند

اکثر پاسخ‌های «۴۱۵ نوع رسانه پشتیبانی نشده» به یک هدر ناقص ختم می‌شوند. با `-d`، curl بی‌سروصدا درخواست شما را با `Content-Type: application/x-www-form-urlencoded` مهر می‌کند. یک بدنه JSON بدون `-H "Content-Type: application/json"` یا `--json` ارسال کنید، و ۴۱۵ دریافت خواهید کرد. هیچ هشداری وجود ندارد، فقط رد می‌شود.

فراداده‌های دیگری نیز همراه با بدنه وجود دارند: طول محتوا (Content-Length)، سربرگ مجوز (Authorization header)، شناسه درخواست (X-Request-Id) برای ردیابی. درست تنظیم کردن این فراداده‌ها نیمی از هر ادغام API است. خود شیء JSON نیمه آسان آن است.

`-H` هدرهای سفارشی اضافه می‌کند. در صورت نیاز تکرار کنید. نام‌های هدر به حروف کوچک و بزرگ حساس نیستند؛ مقادیر اینطور نیستند. سریع‌ترین راه برای اشکال‌زدایی یک POST با پیکربندی نادرست: یک بار آن را با `-v` اجرا کنید، خط درخواست را بخوانید، با اسناد API مقایسه کنید. از هر ده بار، هشت بار در عرض چند ثانیه باگ ظاهر می‌شود.

دو نکته دیگر. طول محتوا (Content-Length) به طور خودکار توسط curl از اندازه بدنه تنظیم می‌شود؛ شما به ندرت آن را لغو می‌کنید. `Accept: application/json` چیزی است که به سرور می‌گوید به جای HTML، در قالب JSON پاسخ دهد. برای آن یک `-H` دیگر اضافه کنید، یا از `--json` استفاده کنید که Content-Type و Accept را با هم تنظیم می‌کند.

آپلود داده‌ها و فایل‌ها از طریق curl با استفاده از POST -F

برای داده‌های فرم به سبک HTML با فایل‌ها، علامت درست `-F` است. این علامت یک درخواست `multipart/form-data` تولید می‌کند. نوع محتوای متفاوت از نوع محتوای form-urlencoded `-d` که به طور پیش‌فرض `-d` است. مدل ذهنی متفاوت. آموزش‌های تک پاراگرافی آنقدر این دو را با هم ترکیب می‌کنند که باعث ایجاد باگ‌های واقعی می‌شود.

`-F` یک بار در هر فیلد. فیلد ساده:

```

curl -F "name=Arya" https://api.example.com/submit

```

آپلود فایل:

```

curl -F "file=@/path/to/image.png" https://api.example.com/upload

```

پیشوند `@` به curl می‌گوید که فایل را از دیسک بخواند و محتویات آن را در بدنه درخواست قرار دهد. curl به طور خودکار نوع MIME را از نام فایل تشخیص می‌دهد؛ در صورت نیاز آن را به صراحت بازنویسی می‌کند:

```

curl -F "[email protected];type=image/png" https://api.example.com/upload

```

چندین پرچم `-F` چندین فیلد یا فایل را در یک درخواست قرار می‌دهند:

```

curl -F "title=Holiday" -F "[email protected]" -F "[email protected]" https://api.example.com/album

```

برای محتوای فایل خام بدون پوشش چندبخشی، که یک نیاز رایج هنگام ارسال یک فایل JSON یا یک قطعه کد باینری به یک نقطه پایانی استریمینگ است، به جای آن از `--data-binary @file.bin` استفاده کنید. این کار بایت‌های فایل را به عنوان کلمه به کلمه به عنوان بدنه درخواست، با هر نوع محتوایی که به صراحت تعیین کرده‌اید، ارسال می‌کند.

احراز هویت در curl POST: کلیدهای پایه، حامل، API

سه شکل احراز هویت تقریباً تمام APIهای REST را در سال ۲۰۲۶ پوشش می‌دهند. احراز هویت پایه (نام کاربری به همراه رمز عبور، کدگذاری شده با base64 در یک هدر):

```

curl -u "myuser:mypass" -X POST -d "..." https://api.example.com/login

```

توکن‌های حامل، که توسط اکثر APIهای مدرن از جمله هر اعتبارنامه‌ی صادر شده توسط OAuth استفاده می‌شوند، بر روی یک هدر مجوز سفارشی سوار می‌شوند:

```

curl -H "مجوز: دارنده $TOKEN" --json '{"q":"hello"}' https://api.example.com/query

```

کلیدهای API معمولاً در یک هدر مخصوص سرویس قرار دارند:

```

curl -H "X-API-Key: $PLISIO_KEY" --json @invoice.json https://api.plisio.net/api/v1/invoices/new

```

اعتبارنامه از یک متغیر محیطی یا یک مدیر مخفی، هرگز به صورت درون‌خطی تایپ نشده است. چرا؟ گزارش وضعیت اسرار ۲۰۲۵ GitGuardian، تعداد ۲۳.۸ میلیون راز جدید را که در طول سال ۲۰۲۴ به GitHub عمومی فاش شده است، شمارش کرد. این رقم نسبت به سال ۲۰۲۳، ۲۵ درصد افزایش داشته است. بیش از ۹۰ درصد از آنها پنج روز پس از افشا، معتبر باقی مانده‌اند. اعتبارنامه‌های درون‌خطی در اسکریپت‌های curl منبع اصلی این افشاگری‌ها هستند. بخش امنیت در زیر، گردش کار را پوشش می‌دهد.

مثال واقعی curl POST: API پرداخت Plisio

مستندات مرجع بدون مثال واقعی، صرفاً تئوری هستند. دستور curl POST زیر، یک فاکتور پرداخت با ارزهای دیجیتال را از طریق REST API شرکت Plisio صادر می‌کند. Plisio کارمزد ثابت ۰.۵٪ دریافت می‌کند؛ در حالی که پردازنده‌های کارت معمولاً ۲ تا ۴٪ کارمزد دریافت می‌کنند. Plisio از بیش از سی ارز دیجیتال پشتیبانی می‌کند و برای نوزده پلتفرم تجارت الکترونیک، یکپارچه‌سازی ارائه می‌دهد.

چرا APIهای کریپتو به عنوان اهداف تمرینی عمل می‌کنند؟ استیبل کوین‌ها در طول سال ۲۰۲۵ تقریباً ۲۸ تریلیون دلار حجم اقتصادی واقعی را جابجا کردند. چینالیسیس رشد را از سال ۲۰۲۳ با نرخ رشد مرکب سالانه ۱۳۳ درصد ثابت نگه داشت. بازار درگاه پرداخت کریپتو در سال ۲۰۲۵ نزدیک به ۲ میلیارد دلار بود و در مسیر ۲.۳۹ میلیارد دلار در سال ۲۰۲۶ قرار دارد (طبق گفته شرکت تحقیقات تجاری). بیت‌پی، کوین‌بیس کامرس، پلیسیو: هر کدام را که انتخاب کنید. اولین گام ادغام با هر درگاه مدرن تقریباً همیشه یک curl POST است.

حداقل فراخوانی برای ایجاد فاکتور جدید:

```

curl -X POST https://api.plisio.net/api/v1/invoices/new \

-H "نوع محتوا: application/json" \

-H "مجوز: دارنده $PLISIO_API_KEY" \

‎-d '{

"source_currency": "USD",

"source_amount": 49.99,

"order_number": "INV-1042",

"currency": "BTC",

"email": "[email protected]",

"order_name": "Annual subscription"

}'‎

```

یک فراخوانی موفق، HTTP 201 را برمی‌گرداند. بدنه پاسخ یک شیء JSON است: یک شناسه فاکتور تولید شده، یک `invoice_url` که مشتری در آن پرداخت می‌کند، یک آدرس کیف پول مقصد، یک مهر زمان انقضا. آن را از طریق `jq` لوله‌کشی کنید تا هر فیلدی را که در مرحله بعد نیاز دارید، استخراج کنید:

```

... | jq '.data.invoice_url'

```

کل الگو همین است. نقطه پایانی را عوض کنید، بار داده را عوض کنید، و شکل مستقیماً به یک پرداخت BitPay، یک پرداخت Coinbase Commerce یا یک قصد پرداخت Stripe منتقل می‌شود. پرچم‌ها تغییر نمی‌کنند؛ فقط JSON تغییر می‌کند.

اشکال‌زدایی یک درخواست POST در curl: -v، --trace، errors

یک POST ناموفق، یک معمای اشکال‌زدایی است. تلاش مجدد کورکورانه بدترین حرکت است. چهار گزینه در خط فرمان، بیشتر آنچه را که نیاز دارید پوشش می‌دهند.

`-v` خط درخواست، هر هدر درخواست و وضعیت پاسخ را چاپ می‌کند. این اولین پرچمی است که به دنبال آن می‌گردید. `--trace-ascii -` چکش بزرگتر است: کل مکالمه، شامل بدنه یک POST، را به خروجی استاندارد منتقل می‌کند. از `curl -i` برای قرار دادن هدرهای پاسخ در بالای بدنه استفاده کنید. و `-w "%{http_code}\n"` فقط کد وضعیت HTTP را می‌نویسد، که هنگام اسکریپت‌نویسی بررسی‌های CI در برابر یک API مفید است.

درباره کدهای وضعیتی که اغلب مشاهده خواهید کرد. ۴۰۰: سرور درخواست شما را تجزیه کرد اما بار داده را رد کرد. ۴۰۱: هدر احراز هویت وجود ندارد یا نامعتبر است. ۴۱۵: نوع محتوا اشتباه است. ۵۰۰: سرور با ورودی شما از کار افتاد. هر کدام یک لایه خاص را رد می‌کنند، که نصف مقدار اجرای `-v` در اولین شکست است.

امنیت POST در curl: کلیدهای API، اسرار و نشت‌ها

هر مرجعی از این بخش صرف نظر می‌کند. هر حادثه‌ای پس از کالبدشکافی به آن اشاره می‌کند. دسامبر ۲۰۲۴: نقض امنیتی وزارت خزانه‌داری ایالات متحده که به یک کلید API فاش‌شده‌ی BeyondTrust برمی‌گردد. دقیقاً همان نوع اعتبارنامه‌ای که در هدرهای `-H "Authorization: Bearer ..."` در اسکریپت‌های عملیاتی وجود دارد.

این روش دفاعی چندان جذاب نیست. توکن‌ها را از متغیرهای محیطی بخوانید. آنها را در یک مدیر مخفی مانند AWS Secrets Manager، HashiCorp Vault یا 1Password CLI ذخیره کنید. یک قلاب پیش از کامیت را در حال اجرا با `gitleaks` یا `trufflehog` نگه دارید. هر توکنی را که تا به حال در تاریخچه پوسته وجود داشته است، بچرخانید. هیچ یک از این کارها هیجان‌انگیز نیست. همه اینها کار می‌کند. اعمال آن در هر درخواست POST curl که ارسال می‌کنید، مهم‌ترین عادتی است که یک توسعه‌دهنده backend می‌تواند در سال 2026 ایجاد کند.

Simon Chartan

A journalist with a strong technical background and a passion for decentralized finance. With degrees in MBA and Master of Engineering in Data Science, the author combines analytical expertise with a clear, engaging writing style. At Plisio, they cover topics such as cryptocurrency, blockchain, DeFi, and digital finance—helping readers make sense of a rapidly evolving fintech landscape.