Comment envoyer une requête POST avec curl : guide complet

Environ vingt milliards d'installations de curl sont actuellement en fonctionnement quelque part dans le monde. Ce chiffre provient du créateur de l'outil, Daniel Stenberg, qui en assure la maintenance quasiment à lui seul. curl est intégré aux routeurs, aux voitures, aux satellites, aux téléviseurs connectés, aux serveurs Linux qui hébergent la majeure partie du web public, et à tous les principaux environnements d'exécution LLM. Parmi tous les verbes HTTP utilisés par ces installations, la requête POST est la plus fréquente. C'est en effectuant une requête POST avec curl que la plupart des développeurs testent, déboguent ou s'intègrent à une API pour la première fois.

Le rapport 2025 de Postman sur l'état des API indique un taux d'adoption de REST de 93 %. 82 % des organisations fonctionnent désormais au moins partiellement selon une approche API-first. La requête POST est le verbe à utiliser pour créer, soumettre ou transmettre des données à un serveur. Les charges de travail liées à l'IA ont encore accéléré cette tendance. Le trafic API attribué à l'utilisation de l'IA a augmenté de 73 % en 2024 (Postman, 2024), et la documentation de tous les fournisseurs de services de gestion de bibliothèques (LLM) commence désormais par un extrait de requête POST curl comme premier appel standard.

Ce guide détaille toutes les formes que peut prendre une requête POST avec curl, de la requête minimale sur une ligne à un appel fonctionnel à une API de paiement crypto. Objectif : un document exploitable et prêt à l’emploi. Que vous envoyiez des données à un serveur pour la première fois ou que vous reconstruisiez un gestionnaire de webhook à 2 h du matin, les exemples ci-dessous couvrent l’essentiel.

Le tableau ci-dessous présente un résumé des options de ligne de commande curl les plus fréquemment utilisées pour l'envoi de requêtes POST. Chaque option est expliquée en détail dans les sections suivantes.

Comprendre la requête curl POST et la méthode HTTP

Une requête POST avec curl est une requête HTTP POST, envoyée depuis la ligne de commande. L'outil curl décrit lui-même son rôle comme le « transfert de données » via plus d'une vingtaine de protocoles, dont HTTP n'est qu'un parmi d'autres. POST signifie : voici des données, traitez-les. La charge utile est placée dans le corps de la requête, jamais dans l'URL. C'est pourquoi POST gère la création de ressources, la soumission de formulaires et toute opération nécessitant des informations d'identification. GET stocke les données dans la chaîne de requête, visibles par tous les proxys et dans l'historique de navigation. Ce n'est pas le cas de POST.

La plupart des tutoriels omettent un détail pourtant important : l’option `-d` active automatiquement la méthode POST pour curl. L’option explicite `-X POST`, qui spécifie une méthode de requête personnalisée, est facultative. De nombreux exemples l’incluent néanmoins, car sa présence à côté de la requête permet de comprendre immédiatement l’intention.

Les méthodes PUT et POST sont souvent confondues, d'où l'importance de clarifier les choses. PUT remplace une ressource à un emplacement connu. POST, quant à elle, en crée une nouvelle ou envoie des données à traiter à un point de terminaison générique.

Syntaxe de base de la commande curl POST et utilisation pratique de l'option -d

La requête POST minimale avec curl tient sur une seule ligne :

```

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

```

Voilà. Requête POST, corps encodé en URL, sans complications. L'option `-d` remplit trois fonctions : elle insère les données dans le corps de la requête, bascule la méthode de requête en POST et ajoute `Content-Type: application/x-www-form-urlencoded` comme en-tête par défaut. Je préfère généralement coller la version légèrement plus détaillée, car l'intention POST est plus lisible lors d'une revue de code.

```

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

```

Mêmes données transmises. Mêmes arguments de requête. Choisissez la méthode que votre équipe préfère pour l'analyse. L'option `-d` est essentielle pour envoyer des données à un serveur depuis la ligne de commande ; elle gère 90 % des requêtes qu'un développeur backend soumet à curl : appels shell, tests de webhook, cibles Makefile, étapes GitHub Actions.

Trois options proches de `-d`. `--data-binary` préserve l'intégrité des octets ; `-d` classique supprime les sauts de ligne et déforme les données binaires. `--data-urlencode` effectue un encodage en pourcentage : `--data-urlencode "name=I am Daniel"` devient `name=I%20am%20Daniel`. `--data-raw` est la solution de repli lorsqu'une valeur commence par `@` et que curl ne doit pas lire de fichier. Plusieurs options `-d` sont combinées avec `&`. Convient aux formulaires. À proscrire pour le JSON.

Un dernier piège : les guillemets. Les guillemets simples autour de la requête POST empêchent l’interpréteur de commandes d’interpréter les caractères `$` ou les barres obliques inverses. Si vous les oubliez, vous risquez de passer la nuit à vous demander pourquoi la moitié de vos données POST sont manquantes.

Ces détails sont importants car curl est l'un des clients HTTP les plus testés au monde. La rétrospective de Stenberg de décembre 2025 a recensé huit versions cette année-là. Neuf vulnérabilités (CVE), toutes classées comme faibles ou moyennes. 2 179 cas de test actifs, soit 232 de plus qu'un an auparavant. La version 8.11.1, sortie en décembre 2024, a corrigé la CVE-2024-11053 (une fuite d'identifiants via netrc et redirection). La version stable actuelle, fin avril 2026, est curl 8.20.0. Les utilisateurs d'une version antérieure à 7.82.0 ne disposent toujours pas de l'option `--json` et utilisent l'ancien système à trois options.

Envoi de données JSON avec curl en utilisant --json ou -H

JSON est le langage universel des API REST en 2026. Il existe deux façons de l'envoyer via POST avec curl. Le choix de la méthode dépend entièrement de la version de curl installée sur la machine.

Modèle classique à trois drapeaux, compatible avec toutes les plateformes à partir de CentOS 6 :

```

curl -X POST \

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

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

https://api.example.com/orders

```

Forme abrégée moderne, disponible depuis curl 7.82.0 (mars 2022) :

```

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

```

L'option `--json` effectue trois actions : elle définit `Content-Type: application/json`, `Accept: application/json` et envoie le corps de la requête. Elle permet également la composition : si vous utilisez `--json` plusieurs fois, les données sont concaténées. Ceci est particulièrement utile pour transmettre des fragments JSON à un point de terminaison de flux.

Pour les données JSON stockées dans un fichier, préfixez le chemin d'accès par `@`. L'envoi de données depuis un fichier devient la norme lorsque l'objet JSON est trop volumineux pour être collé directement, lorsqu'il est versionné ou lorsqu'il est généré par un autre script.

```

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

```

Le deuxième modèle lit les données d'un fichier nommé `order.json` et les envoie avec tous les en-têtes nécessaires. Pour les contenus JSON volumineux ou potentiellement binaires, l'option `--data-binary @file.json` est plus sûre. Elle ne supprime pas les sauts de ligne, n'interprète pas les caractères spéciaux et envoie des données binaires brutes à un point de terminaison qui attend des octets plutôt que des champs de formulaire. Un troisième modèle lit les données depuis l'entrée standard via `-d @-`. Pratique pour rediriger la sortie d'une autre commande directement vers une requête POST curl.

Le tableau ci-dessous associe les quatre formes JSON courantes à un point de terminaison unique :

Cela a plus d'importance qu'auparavant. Tous les principaux fournisseurs de modèles de langage naturel (OpenAI, Anthropic, Mistral, Google) intègrent dans leur documentation API un exemple de requête POST avec curl utilisant exactement cette syntaxe. Le trafic généré par l'IA a représenté 73 % du volume total d'appels API en 2024 (Postman). curl est désormais la référence incontournable pour la question « comment appeler ce point de terminaison ».

En-têtes Content-Type et hypothèses de curl

La plupart des réponses « 415 Type de média non pris en charge » sont dues à l'absence d'un en-tête. Avec l'option `-d`, curl ajoute discrètement l'en-tête `Content-Type: application/x-www-form-urlencoded` à votre requête. Si vous envoyez un corps JSON sans l'option `-H "Content-Type: application/json"` ou `--json`, vous recevrez une réponse 415. Aucun avertissement, juste le rejet.

D'autres métadonnées sont également incluses dans le corps de la requête : Content-Length, l'en-tête Authorization et X-Request-Id pour le traçage. La bonne configuration de ces métadonnées représente la moitié du succès de toute intégration d'API. L'objet JSON lui-même est la partie la plus simple.

L'option `-H` ajoute des en-têtes personnalisés. Répétez l'opération si nécessaire. Les noms d'en-tête ne sont pas sensibles à la casse ; les valeurs, si. Pour déboguer rapidement une requête POST mal configurée : exécutez-la une fois avec l'option `-v`, examinez la ligne de requête et comparez-la avec la documentation de l'API. Dans huit cas sur dix, le problème apparaît en quelques secondes.

Deux remarques supplémentaires. L'en-tête Content-Length est automatiquement défini par curl à partir de la taille du corps de la requête ; vous le modifiez rarement. L'option `Accept: application/json` indique au serveur de répondre au format JSON plutôt qu'en HTML. Ajoutez une autre option `-H` pour cela, ou utilisez `--json`, qui définit simultanément les en-têtes Content-Type et Accept.

Données de formulaire et téléchargements de fichiers avec curl POST -F

Pour les données de formulaire HTML avec fichiers, l'option appropriée est `-F`. Elle génère une requête `multipart/form-data`. Le type de contenu diffère de celui du formulaire encodé en URL (utilisé par défaut avec `-d`). Le modèle de pensée est différent. Les tutoriels très courts confondent souvent les deux, ce qui engendre de véritables bogues.

`-F` une fois par champ. Champ en format brut :

```

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

```

Téléchargement de fichier :

```

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

```

Le préfixe `@` indique à curl de lire le fichier sur le disque et d'inclure son contenu dans le corps de la requête. curl détecte automatiquement le type MIME à partir du nom du fichier ; vous pouvez le spécifier explicitement si nécessaire.

```

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

```

Plusieurs options `-F` permettent de regrouper plusieurs champs ou fichiers dans une seule requête :

```

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

```

Pour transmettre le contenu brut d'un fichier sans l'encapsulation multipart (une situation fréquente lors de l'envoi d'un fichier JSON ou d'un objet binaire à un point de terminaison de flux), utilisez plutôt `--data-binary @file.bin`. Cela envoie les octets du fichier tels quels dans le corps de la requête, avec le type de contenu que vous avez explicitement défini.

Authentification via curl POST : authentification basique, authentification par authentification unique (bearer), clés API

Trois types d'authentification couvrent la quasi-totalité des API REST en 2026. Authentification de base (nom d'utilisateur et mot de passe, encodés en base64 dans un en-tête) :

```

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

```

Les jetons porteurs, utilisés par la plupart des API modernes, y compris toutes les informations d'identification émises par OAuth, sont associés à un en-tête d'autorisation personnalisé :

```

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

```

Les clés API se trouvent généralement dans un en-tête spécifique au service :

```

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

```

Les identifiants provenant d'une variable d'environnement ou d'un gestionnaire de secrets ne doivent jamais être saisis directement dans le code. Pourquoi ? Selon l'étude « State of Secrets Sprawl » de GitGuardian (2025), 23,8 millions de nouveaux secrets ont fuité sur GitHub en 2024, soit une augmentation de 25 % par rapport à 2023. Plus de 90 % d'entre eux sont restés valides cinq jours après leur divulgation. Les identifiants intégrés directement dans les scripts curl constituent une source majeure de ces fuites. La section « Sécurité » ci-dessous décrit le processus.

Exemple concret de requête POST avec curl : API de paiement Plisio

Les documents de référence sans exemple concret restent théoriques. La requête POST curl ci-dessous génère une facture de paiement en cryptomonnaie via l'API REST de Plisio. Plisio prélève une commission fixe de 0,5 %, contre généralement entre 2 et 4 % pour les processeurs de cartes. Plisio prend en charge plus de trente cryptomonnaies et propose des intégrations pour dix-neuf plateformes e-commerce.

Pourquoi les API crypto sont-elles efficaces comme cibles d'entraînement ? Les stablecoins ont généré un volume économique réel d'environ 28 000 milliards de dollars en 2025. Chainalysis a estimé cette croissance à un TCAC de 133 % depuis 2023. Le marché des passerelles de paiement crypto avoisinait les 2 milliards de dollars en 2025 et devrait atteindre 2,39 milliards de dollars en 2026 (selon The Business Research Company). BitPay, Coinbase Commerce, Plisio : à vous de choisir. La première étape d'intégration avec une passerelle moderne consiste presque toujours en une requête POST via curl.

L'appel minimal pour créer une nouvelle facture :

```

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

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

-H "Autorisation : Porteur $PLISIO_API_KEY" \

-d '{

"source_currency": "USD",

"source_amount": 49.99,

"order_number": "INV-1042",

"currency": "BTC",

"email": "[email protected]",

"order_name": "Annual subscription"

}'

```

Un appel réussi renvoie un code HTTP 201. Le corps de la réponse est un objet JSON : un identifiant de facture généré, une URL de paiement (`invoice_url`), une adresse de portefeuille de destination et une date d'expiration. Utilisez ensuite `jq` pour extraire le champ souhaité.

```

... | jq '.data.invoice_url'

```

Voilà le principe. Il suffit de modifier le point de terminaison et la charge utile pour que la structure reste identique pour une transaction BitPay, un paiement Coinbase Commerce ou une intention de paiement Stripe. Les indicateurs restent les mêmes ; seul le JSON est modifié.

Débogage d'une requête POST curl : -v, --trace, erreurs

Un échec de requête POST est un véritable casse-tête à déboguer. Réessayer à l'aveuglette est la pire des solutions. Quatre options en ligne de commande couvrent la plupart de vos besoins.

L'option `-v` affiche la ligne de requête, tous les en-têtes de requête et le statut de la réponse. C'est l'option à privilégier en premier. `--trace-ascii -` est plus puissante : elle affiche l'intégralité de la conversation, y compris le corps d'une requête POST, sur la sortie standard. Utilisez `curl -i` pour afficher les en-têtes de réponse au-dessus du corps. Enfin, `-w "%{http_code}\n"` affiche uniquement le code de statut HTTP, ce qui est utile pour les tests d'intégration continue (CI) d'une API.

Voici les codes d'état les plus fréquents : 400 : le serveur a analysé votre requête mais a rejeté la charge utile. 401 : en-tête d'authentification manquant ou invalide. 415 : type de contenu incorrect. 500 : le serveur a rencontré une erreur lors de la saisie. Chaque code d'état permet d'exclure une couche spécifique, ce qui représente la moitié de l'intérêt d'exécuter l'option `-v` dès le premier échec.

Sécurité des requêtes POST avec curl : clés API, secrets et fuites

Toutes les références passent cette section sous silence. Toutes les analyses post-incident la mentionnent. Décembre 2024 : la faille de sécurité au sein du Trésor américain est attribuée à une fuite de clé API BeyondTrust. Exactement le type d’identifiant que l’on retrouve dans les en-têtes `-H "Authorization: Bearer..."` des scripts de production.

La défense est peu glamour. Lisez les jetons depuis les variables d'environnement. Stockez-les dans un gestionnaire de secrets comme AWS Secrets Manager, HashiCorp Vault ou l'interface de ligne de commande 1Password. Exécutez un hook pre-commit avec `gitleaks` ou `trufflehog`. Remplacez systématiquement tous les jetons ayant existé dans l'historique du shell. Rien de bien passionnant, certes, mais tout est efficace. Appliquer cette méthode à chaque requête POST curl que vous envoyez est l'habitude la plus importante qu'un développeur backend puisse prendre en 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.