كيفية إرسال طلب POST باستخدام curl: مرجع كامل

يُشغّل برنامج curl حاليًا ما يقارب عشرين مليار نسخة في أماكن متفرقة حول العالم. هذا الرقم مُقدّم من مُنشئ الأداة، دانيال ستينبرغ، الذي يُشرف على صيانتها بمفرده تقريبًا. يُثبّت curl في أجهزة التوجيه، والسيارات، والأقمار الصناعية، وأجهزة التلفاز الذكية، وخوادم لينكس التي تدعم معظم مواقع الويب العامة، وفي جميع بيئات تشغيل برامج إدارة التعلم الرئيسية. من بين جميع أوامر HTTP التي تُرسلها هذه النسخ، يُعدّ POST الأكثر استخدامًا. يستخدم معظم المطورين أمر curl POST لاختبار أو تصحيح أو دمج واجهة برمجة التطبيقات (API) لأول مرة.

يشير تقرير حالة واجهات برمجة التطبيقات لعام 2025 الصادر عن بوستمان إلى أن نسبة اعتماد REST بلغت 93%. وتعمل 82% من المؤسسات حاليًا، جزئيًا على الأقل، وفق منهجية واجهات برمجة التطبيقات. يُعدّ طلب POST هو الإجراء الأساسي لإنشاء البيانات أو إرسالها أو نقلها إلى الخادم. وقد ساهمت تطبيقات الذكاء الاصطناعي في تسريع هذا التوجه. إذ نما حجم حركة بيانات واجهات برمجة التطبيقات الناتجة عن استخدام الذكاء الاصطناعي بنسبة 73% في عام 2024 (بوستمان، 2024)، وتبدأ جميع وثائق مزودي خدمات إدارة التعلم الآن بمقتطف من تعليمات curl POST كأول طلب أساسي.

يشرح هذا المرجع جميع أشكال طلبات POST باستخدام curl، بدءًا من أبسطها المكونة من سطر واحد وصولًا إلى استدعاء عملي لواجهة برمجة تطبيقات دفع العملات الرقمية. الهدف: توفير مرجع يمكنك نسخه ولصقه، وليس مجرد قراءته. سواء كنت ترسل بيانات إلى خادم لأول مرة أو تعيد بناء معالج webhook في الساعة الثانية صباحًا، فإن الأنماط الموضحة أدناه تغطي احتياجاتك الفعلية.

الجدول أدناه هو النسخة المختصرة. دليل مختصر يوضح خيارات سطر الأوامر curl الأكثر استخدامًا عند إرسال طلبات POST، مع شرح مفصل لكل خيار في الأقسام التالية.

فهم طلب POST باستخدام curl وطريقة HTTP

طلب POST في curl هو طلب HTTP POST، يُرسل باستخدام طريقة POST من سطر الأوامر. تُعرّف أداة curl نفسها وظيفتها بأنها "نقل البيانات" عبر أكثر من عشرين بروتوكولًا، منها HTTP واحد فقط. يعني POST: إليك بعض البيانات، قم بمعالجتها. تُوضع البيانات في نص الطلب، وليس في عنوان URL. هذه الخاصية هي سبب استخدام POST لإنشاء الموارد، وإرسال النماذج، وأي شيء يحمل بيانات اعتماد. أما GET فيُخزّن البيانات في سلسلة الاستعلام، ما يجعلها مرئية لجميع الخوادم الوكيلة وسجل المتصفح. بينما لا يفعل POST ذلك.

تتجاهل معظم الشروحات تفصيلاً صغيراً ولكنه مفيد. مرر الخيار `-d` وسيقوم curl بالتبديل تلقائياً إلى POST. أما الخيار `-X POST` الصريح، الذي يحدد طريقة طلب مخصصة، فهو اختياري. مع ذلك، لا تزال العديد من الأمثلة تتضمنه لأن قراءة `-X POST` بجوار البيانات المرسلة تجعل الغرض واضحاً بنظرة سريعة.

كثيراً ما يُخلط بين PUT و POST، لذا من المهم توضيح الفرق بينهما. يستبدل PUT مورداً في موقع معروف، بينما يُنشئ POST مورداً جديداً أو يرسل بيانات لمعالجتها في نقطة نهاية عامة.

صيغة طلب POST الأساسية في curl وعلامة -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` الأداة الأساسية لإرسال البيانات إلى الخادم من سطر الأوامر، وهو يُغطي 90% مما يُرسله مطوّر الواجهة الخلفية إلى curl: استدعاءات سطر الأوامر، واختبارات webhook، وأهداف Makefile، وخطوات GitHub Actions.

ثلاثة خيارات مشابهة لـ `-d`. يحافظ الخيار `--data-binary` على سلامة البيانات الثنائية؛ بينما يقوم الخيار `-d` العادي بإزالة أسطر جديدة، مما قد يُشوّه البيانات الثنائية. يقوم الخيار `--data-urlencode` بتشفير البيانات بنسبة مئوية: فمثلاً، يُحوّل الخيار `--data-urlencode "name=I am Daniel"` إلى `name=I%20am%20Daniel`. أما الخيار `--data-raw` فهو الحل البديل عندما تبدأ القيمة بـ `@` ولا يُفترض أن يقرأ curl ملفًا. يمكن ربط عدة خيارات `-d` باستخدام `&`. هذا مناسب للنماذج، لكنه غير مناسب لملفات JSON.

ملاحظة أخيرة: الاقتباس. علامات الاقتباس المفردة حول البيانات تمنع النظام من تفسير رمز الدولار ($) أو الشرطات المائلة العكسية. إذا نسيتها، فستقضي الساعة الثانية صباحًا تتساءل عن سبب فقدان نصف بيانات طلب POST.

تُعدّ هذه التفاصيل مهمة لأن curl نفسه يُعتبر من أكثر عملاء HTTP اختبارًا على مستوى العالم. أحصى تقرير ستينبرغ لشهر ديسمبر 2025 ثمانية إصدارات في ذلك العام، وتسع ثغرات أمنية (CVEs)، جميعها مصنفة ضمن فئتي الخطورة المنخفضة والمتوسطة. وبلغ عدد حالات الاختبار النشطة 2179 حالة، أي بزيادة 232 حالة عن الاثني عشر شهرًا السابقة. عالج الإصدار 8.11.1، الصادر في ديسمبر 2024، الثغرة الأمنية CVE-2024-11053 (تسريب بيانات اعتماد netrc-and-redirect). الإصدار المستقر الحالي حتى أواخر أبريل 2026 هو curl 8.20.0. أما من يستخدمون إصدارات أقدم من 7.82.0، فلا يزالون يفتقرون إلى خيار `--json`، ويعودون إلى نمط الخيارات الثلاثة القديم.

إرسال بيانات JSON باستخدام curl باستخدام --json أو -H

يُعدّ JSON اللغة المشتركة لواجهات برمجة تطبيقات REST في عام 2026. هناك طريقتان لإرسال طلب POST باستخدام curl، ويعتمد اختيار الطريقة المناسبة كليًا على إصدار curl المُثبّت على الجهاز.

نمط الرايات الثلاث الكلاسيكي، يعمل في كل مكان بدءًا من CentOS 6 فصاعدًا:

```

curl -X POST

-H "Content-Type: application/json" \

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

https://api.example.com/orders

```

الاختزال الحديث، متوفر منذ إصدار curl 7.82.0 (مارس 2022):

```

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

```

يؤدي الخيار `--json` ثلاث وظائف: تحديد نوع المحتوى (Content-Type) إلى تطبيق JSON، وتحديد نوع البيانات المقبولة (Accept) إلى تطبيق JSON، وإرسال محتوى الطلب. كما أنه يُدمج البيانات: فإذا تم تمرير الخيار `--json` أكثر من مرة، يتم دمج البيانات المرسلة. وهذا مفيد عند تمرير أجزاء JSON إلى نقطة نهاية البث المباشر.

بالنسبة لبيانات JSON المخزنة في ملف، أضف الرمز `@` قبل مسار الملف. يصبح إرسال البيانات من ملف هو النمط القياسي عندما يكون حجم كائن JSON كبيرًا جدًا بحيث لا يمكن لصقه مباشرةً، أو عندما يكون موجودًا في نظام التحكم في الإصدارات، أو عندما يقوم برنامج نصي آخر بإنشائه.

```

curl -X POST -H "Content-Type: 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` أكثر أمانًا. فهو لا يُزيل أسطرًا جديدة، ولا يُفسّر الأحرف الخاصة، ويرسل بيانات ثنائية خام إلى نقطة نهاية تتوقع بايتات بدلًا من حقول النموذج. يقرأ النمط الثالث البيانات من الإدخال القياسي (stdin) عبر `-d @-`. وهو مفيد عند توجيه مخرجات أمر آخر مباشرةً إلى طلب POST باستخدام curl.

يوضح الجدول أدناه العلاقة بين الأشكال الأربعة الشائعة لملفات JSON ونقطة نهاية واحدة:

أصبح هذا الأمر أكثر أهمية من ذي قبل. فجميع مزودي خدمات التعلم القائم على التعلم الآلي الرئيسيين - مثل OpenAI وAnthropic وMistral وGoogle - يفتتحون وثائق واجهة برمجة التطبيقات الخاصة بهم بمثال لطلب POST باستخدام curl، وذلك باستخدام هذا الشكل تحديدًا. وقد ساهمت حركة المرور المدفوعة بالذكاء الاصطناعي بنسبة 73% في إجمالي حجم استدعاءات واجهة برمجة التطبيقات في عام 2024 (بحسب Postman). وأصبح curl الآن المرجع الأساسي للإجابة عن سؤال "كيف أستدعي هذه النقطة النهائية؟".

نوع المحتوى، والعناوين، وما يفترضه curl

معظم ردود "415 نوع الوسائط غير مدعوم" تعود إلى نقص في أحد ترويسات الطلب. عند استخدام الخيار `-d`، يضيف curl تلقائيًا ترويسة `Content-Type: application/x-www-form-urlencoded` إلى طلبك. أما عند إرسال بيانات JSON بدون الخيار `-H "Content-Type: application/json"` أو `--json`، فستتلقى الرد 415. لا يوجد أي تحذير، فقط رفض.

تتضمن البيانات الوصفية الأخرى أيضًا محتوى الطلب: طول المحتوى، وعنوان المصادقة، ومعرّف الطلب (X-Request-Id) للتتبع. يُعدّ ضبط هذه البيانات الوصفية نصف عملية دمج واجهة برمجة التطبيقات (API). أما كائن JSON نفسه فهو النصف الأسهل.

يُضيف الخيار `-H` رؤوسًا مخصصة. كرر العملية حسب الحاجة. أسماء الرؤوس غير حساسة لحالة الأحرف، بينما القيم حساسة. أسرع طريقة لتصحيح خطأ في تهيئة طلب POST: شغّله مع الخيار `-v` مرة واحدة، واقرأ سطر الطلب، وقارنه بوثائق واجهة برمجة التطبيقات. في ثماني حالات من أصل عشر، يظهر الخطأ في غضون ثوانٍ.

ملاحظتان إضافيتان. يتم ضبط خاصية Content-Length تلقائيًا بواسطة curl بناءً على حجم نص الطلب؛ ونادرًا ما يتم تعديلها. أما `Accept: application/json` فهو ما يُخبر الخادم بالرد بتنسيق JSON بدلًا من HTML. أضف `-H` لهذا الغرض، أو استخدم `--json` الذي يضبط Content-Type وAccept معًا.

بيانات النموذج وتحميل الملفات باستخدام curl POST -F

بالنسبة لبيانات النماذج بتنسيق HTML التي تحتوي على ملفات، فإن الخيار الصحيح هو `-F`. ينتج هذا الخيار طلبًا من نوع `multipart/form-data`. يختلف نوع المحتوى عن النوع الافتراضي المُشفّر باستخدام `-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

```

بالنسبة لمحتويات الملفات الخام بدون غلاف multipart، وهو أمر شائع عند إرسال ملف JSON أو بيانات ثنائية إلى نقطة نهاية البث، استخدم `--data-binary @file.bin` بدلاً من ذلك. يرسل هذا بايتات الملف كنص الطلب حرفيًا، مع أي نوع محتوى تحدده صراحةً.

المصادقة في طلب POST باستخدام curl: المصادقة الأساسية، والمصادقة باستخدام حامل المصادقة، ومفاتيح واجهة برمجة التطبيقات (API).

ثلاثة أشكال للمصادقة تغطي جميع واجهات برمجة تطبيقات REST تقريبًا في عام 2026. المصادقة الأساسية (اسم المستخدم بالإضافة إلى كلمة المرور، مشفرة بصيغة base64 في رأس الطلب):

```

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

```

تعتمد رموز حامل البطاقة، المستخدمة في معظم واجهات برمجة التطبيقات الحديثة بما في ذلك كل بيانات اعتماد صادرة عن OAuth، على رأس Authorization مخصص:

```

curl -H "Authorization: Bearer $TOKEN" --json '{"q":"hello"}' https://api.example.com/query

```

توجد مفاتيح واجهة برمجة التطبيقات عادةً في رأس خاص بالخدمة:

```

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

```

بيانات الاعتماد من متغير بيئي أو مدير أسرار، لا تُكتب مباشرةً في سطر الأوامر. لماذا؟ أحصى تقرير GitGuardian لعام 2025 حول انتشار الأسرار 23.8 مليون سر جديد تم تسريبه إلى منصة GitHub العامة خلال عام 2024، بزيادة قدرها 25% عن عام 2023. وظل أكثر من 90% منها صالحًا لمدة خمسة أيام بعد تسريبه. تُعد بيانات الاعتماد المضمنة في نصوص curl مصدرًا رئيسيًا لهذه التسريبات. يتناول قسم الأمان أدناه آلية العمل.

مثال عملي لطلب POST باستخدام curl: واجهة برمجة تطبيقات الدفع Plisio

الوثائق المرجعية بدون مثال عملي تبقى مجرد نظريات. يُنشئ طلب POST الموضح أدناه فاتورة دفع بالعملات الرقمية عبر واجهة برمجة تطبيقات REST الخاصة بـ Plisio. تتقاضى Plisio رسومًا ثابتة قدرها 0.5%، بينما تتقاضى شركات معالجة البطاقات عادةً ما بين 2% و4%. تدعم Plisio أكثر من ثلاثين عملة رقمية، وتوفر تكاملات مع تسعة عشر منصة للتجارة الإلكترونية.

لماذا تُعدّ واجهات برمجة تطبيقات العملات الرقمية أهدافًا تدريبية فعّالة؟ بلغ حجم التداول الفعلي للعملات المستقرة حوالي 28 تريليون دولار أمريكي خلال عام 2025. وقدّرت شركة Chainalysis نموّها بمعدل نمو سنوي مركب قدره 133% منذ عام 2023. وبلغ حجم سوق بوابات دفع العملات الرقمية ما يقارب ملياري دولار أمريكي في عام 2025، ومن المتوقع أن يصل إلى 2.39 مليار دولار أمريكي في عام 2026 (وفقًا لشركة The Business Research Company). اختر أيًا من BitPay أو Coinbase Commerce أو Plisio. الخطوة الأولى للتكامل مع أي بوابة حديثة هي غالبًا استخدام طلب POST عبر curl.

الحد الأدنى من الخطوات لإنشاء فاتورة جديدة:

```

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

-H "Content-Type: 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 يتضمن: مُعرّف الفاتورة المُنشأة، وعنوان 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).

فيما يلي رموز الحالة التي ستراها غالبًا: 400: قام الخادم بتحليل طلبك لكنه رفض البيانات. 401: رأس المصادقة مفقود أو غير صالح. 415: نوع المحتوى خاطئ. 500: تعطل الخادم عند إدخالك للبيانات. كل رمز من هذه الرموز يستبعد طبقة معينة، وهو ما يعادل نصف قيمة تشغيل الخيار `-v` عند أول فشل.

أمان طلبات POST في curl: مفاتيح API، والأسرار، والتسريبات

تتجاهل جميع المراجع هذا القسم. ويذكره كل تحليل للحادثة بعد وقوعها. ديسمبر 2024: تم تتبع اختراق وزارة الخزانة الأمريكية إلى مفتاح API مسرب من BeyondTrust. وهو تحديدًا نوع بيانات الاعتماد الموجودة داخل ترويسات `-H "Authorization: Bearer ..."` في نصوص الإنتاج.

الدفاع بسيط وغير مُبهر. اقرأ الرموز المميزة من متغيرات البيئة. خزّنها في مدير أسرار مثل AWS Secrets Manager أو HashiCorp Vault أو واجهة سطر الأوامر 1Password. شغّل خطافًا قبل الالتزام باستخدام `gitleaks` أو `trufflehog`. غيّر أي رمز مميز موجود في سجل الأوامر. لا شيء من هذا مثير. لكنه فعال. تطبيقه على كل طلب POST ترسله عبر curl هو أهم عادة يمكن لمطور الواجهة الخلفية اكتسابها في عام 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.