Jak wysłać żądanie POST za pomocą curl: pełna dokumentacja

Na świecie działa obecnie około dwudziestu miliardów instalacji curl. Ta liczba pochodzi od twórcy narzędzia, Daniela Stenberga, który zarządza nim niemal w pojedynkę. curl jest zainstalowany w routerach, samochodach, satelitach, telewizorach smart TV, serwerach Linux obsługujących większość publicznej sieci WWW oraz w każdym głównym środowisku uruchomieniowym LLM. Ze wszystkich poleceń HTTP, które te instalacje obsługują, POST wykonuje większość zadań. POST curl to metoda, za pomocą której większość programistów po raz pierwszy testuje, debuguje lub integruje się z API.

Raport Postmana „2025 State of the API” podaje, że REST jest wdrażany na poziomie 93%. 82% organizacji działa obecnie przynajmniej częściowo w oparciu o API. POST to czasownik, po który sięga się za każdym razem, gdy tworzy się, przesyła lub transmituje dane na serwer. Obciążenia AI dodatkowo przyspieszyły ten trend. Ruch w API przypisywany wykorzystaniu AI wzrósł o 73% w 2024 roku (Postman, 2024), a dokumentacja każdego dostawcy LLM rozpoczyna się teraz fragmentem kodu curl POST jako kanonicznym „pierwszym wezwaniem”.

W tym dokumencie omówiono każdy kształt, jaki może przybrać żądanie POST z użyciem curl, od minimum jednej linijki kodu po działające wywołanie do prawdziwego interfejsu API płatności kryptowalutowych. Cel: coś, co można wkleić, a nie tylko odczytać. Niezależnie od tego, czy wysyłasz dane na serwer po raz pierwszy, czy przebudowujesz obsługę webhooka o 2 w nocy – poniższe schematy obejmują to, czego faktycznie potrzebujesz.

Poniższa tabela to skrócona wersja. Ściągawka z flagami i celami, obejmująca opcje wiersza poleceń curl używane najczęściej podczas wysyłania żądań POST. Każda z nich jest omówiona w kolejnych sekcjach.

Zrozumienie żądania POST i metody HTTP w programie curl

Żądanie POST w curl to żądanie HTTP POST, wysyłane metodą POST z wiersza poleceń. Narzędzie curl opisuje swoje zadanie jako „przesyłanie danych” przez ponad dwadzieścia protokołów, z których HTTP jest tylko jednym. POST oznacza: oto jakieś dane, zrób z nimi coś. Dane znajdują się w treści żądania, nigdy w adresie URL. Ta właściwość sprawia, że POST obsługuje tworzenie zasobów, przesyłanie formularzy i wszystko, co zawiera dane uwierzytelniające. GET umieszcza dane w ciągu zapytania, widocznym dla każdego serwera proxy i historii każdej przeglądarki. POST tego nie robi.

Większość samouczków pomija drobny, ale przydatny szczegół. Przekazywanie `-d` i automatycznych przełączników curl do POST. Jawne `-X POST`, które określa niestandardową metodę żądania, jest opcjonalne. Wiele przykładów nadal je zawiera, ponieważ odczytanie `-X POST` obok ładunku sprawia, że intencja jest oczywista na pierwszy rzut oka.

PUT i POST są na tyle często mylone, że warto je dokładniej wyjaśnić. PUT zastępuje zasób w znanej lokalizacji. POST tworzy nowy zasób lub wysyła dane do przetworzenia w ogólnym punkcie końcowym.

Podstawowa składnia polecenia POST curl i flaga -d w praktyce

Minimalna długość polecenia POST wynosi jedną linię:

```

curl -d "nazwa użytkownika=arya&wiek=16" https://api.example.com/users

```

To wszystko. Żądanie POST, treść zakodowana w formacie urlencoded, bezproblemowo. `-d` spełnia potrójne zadanie: umieszcza ładunek w treści żądania, zmienia metodę żądania na POST i dodaje `Content-Type: application/x-www-form-urlencoded` jako domyślny nagłówek. Zazwyczaj i tak wklejam nieco bardziej rozwlekły formularz, ponieważ intencja POST lepiej się czyta podczas przeglądu kodu:

```

curl -X POST -d "nazwa użytkownika=arya&wiek=16" https://api.example.com/users

```

Te same bajty w sieci. Te same argumenty żądania. Użyj tego, co Twój zespół uzna za łatwiejsze do przeskanowania. Flaga `-d` to podstawowy element używany do wysyłania danych do serwera z wiersza poleceń i obsługuje dziewięćdziesiąt procent zadań, z którymi programista back-end kiedykolwiek musi się zmierzyć w curl: wywołania powłoki, testy webhooków, cele Makefile, kroki GitHub Actions.

Trzech bliskich kuzynów `-d`. `--data-binary` zachowuje bajty w stanie nienaruszonym; standardowy `-d` usuwa nowe linie i zniekształca dane binarne. `--data-urlencode` koduje procentowo: `--data-urlencode "name=I am Daniel"` pojawia się jako `name=I%20am%20Daniel`. `--data-raw` to wyjście awaryjne, gdy wartość zaczyna się od `@`, a curl nie powinien odczytywać pliku. Wiele flag `-d` łączy się za pomocą `&`. W porządku dla formularzy. Nigdy dla JSON.

Ostatni haczyk: cytowanie. Pojedyncze cudzysłowy wokół ładunku uniemożliwiają powłoce interpretację `$` lub ukośników odwrotnych. Zapomnij o nich, a spędzisz 2 noce na pytaniu, dlaczego połowa danych POST zniknęła.

Te szczegóły mają znaczenie, ponieważ sam curl jest jednym z najmocniej testowanych klientów HTTP na świecie. Retrospektywa Stenberga z grudnia 2025 roku wykazała osiem wydań w tym roku. Dziewięć luk w zabezpieczeniach (CVE), wszystkie ocenione nisko lub średnio. 2179 aktywnych przypadków testowych, o 232 więcej niż dwanaście miesięcy wcześniej. Wersja 8.11.1 z grudnia 2024 roku załatała lukę CVE-2024-11053 (wyciek danych uwierzytelniających netrc-and-redirect). Aktualna wersja stabilna na koniec kwietnia 2026 roku to curl 8.20.0. Każdy, kto utknie w wersji poniżej 7.82.0, nadal nie ma flagi `--json` i wraca do starszego schematu z trzema flagami.

Wysyłanie danych JSON za pomocą curl przy użyciu --json lub -H

JSON jest językiem urzędowym interfejsów API REST w 2026 roku. Istnieją dwa sposoby na przesłanie go za pomocą curl. Wybór zależy wyłącznie od wersji curl zainstalowanej na komputerze.

Klasyczny wzór trzech flag, działający wszędzie od CentOS 6:

```

curl -X POST \

-H "Typ zawartości: aplikacja/json" \

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

https://api.example.com/orders

```

Nowoczesny zapis skrócony, dostępny od wersji curl 7.82.0 (marzec 2022):

```

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

```

Flaga `--json` robi trzy rzeczy. Ustawia `Content-Type: application/json`. Ustawia `Accept: application/json`. Wysyła treść. Kompozytuje również: przekazując `--json` więcej niż raz, ładunki łączą się. Przydatne podczas przesyłania fragmentów JSON do punktu końcowego przesyłania strumieniowego.

W przypadku ładunków JSON przechowywanych w pliku, należy poprzedzić ścieżkę do pliku znakiem `@`. Publikowanie danych z pliku staje się standardem, gdy obiekt JSON jest zbyt duży, aby wkleić go bezpośrednio, gdy znajduje się w systemie kontroli wersji lub gdy generuje go inny skrypt:

```

curl -X POST -H "Typ zawartości: application/json" -d @order.json https://api.example.com/orders

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

```

Drugi wzorzec odczytuje dane z pliku o nazwie `order.json` i wysyła je ze wszystkimi odpowiednimi nagłówkami. W przypadku dużej lub potencjalnie binarnej zawartości JSON, `--data-binary @file.json` jest bezpieczniejszą opcją. Nie usuwa on znaków nowej linii, nie interpretuje znaków specjalnych i wysyła surowe dane binarne do punktu końcowego, który oczekuje bajtów, a nie pól formularza. Trzeci wzorzec odczytuje dane ze standardowego wejścia (stdin) za pomocą `-d @-`. Przydatne podczas przesyłania danych z innego polecenia bezpośrednio do polecenia POST curl.

Poniższa tabela mapuje cztery popularne kształty JSON na pojedynczy punkt końcowy:

To ma większe znaczenie niż kiedyś. Każdy główny dostawca LLM — OpenAI, Anthropic, Mistral, Google — otwiera swoje dokumenty API z przykładem POST curl, używając dokładnie tego kształtu. Ruch generowany przez sztuczną inteligencję zwiększył całkowitą liczbę wywołań API o 73% w 2024 roku (Postman). curl jest obecnie kanonicznym punktem odniesienia dla pytania „jak wywołać ten punkt końcowy”.

Typ zawartości, nagłówki i założenia curl

Większość odpowiedzi „415 Nieobsługiwany typ mediów” sprowadza się do braku jednego nagłówka. Z parametrem `-d`, curl dyskretnie zaznacza Twoje żądanie `Content-Type: application/x-www-form-urlencoded`. Wyślij treść JSON bez `-H "Content-Type: application/json"` lub `--json`, a otrzymasz 415. Bez ostrzeżenia, tylko odrzucenie.

Wraz z treścią przesyłane są również inne metadane: Content-Length, nagłówek Authorization, X-Request-Id do śledzenia. Poprawne przygotowanie tych metadanych to połowa sukcesu każdej integracji API. Sam obiekt JSON to ta łatwiejsza połowa.

`-H` dodaje niestandardowe nagłówki. Powtarzaj w razie potrzeby. Nazwy nagłówków nie uwzględniają wielkości liter; wartości nie. Najszybszy sposób debugowania błędnie skonfigurowanego polecenia POST: uruchom go raz z `-v`, przeczytaj wiersz żądania i porównaj z dokumentacją API. W ośmiu przypadkach na dziesięć błąd pojawia się w ciągu kilku sekund.

Jeszcze dwie uwagi. Długość treści jest automatycznie ustawiana przez curl na podstawie rozmiaru treści; rzadko się ją nadpisuje. `Accept: application/json` to polecenie, które nakazuje serwerowi odpowiedzieć w formacie JSON, a nie HTML. Dodaj w tym celu kolejny `-H` lub użyj `--json`, które ustawia jednocześnie Content-Type i Accept.

Przesyłanie danych formularza i plików za pomocą polecenia curl POST -F

W przypadku danych formularza w stylu HTML z plikami, właściwą flagą jest `-F`. Generuje ona żądanie `multipart/form-data`. Inny typ zawartości niż ten zakodowany w formularzu (URL), domyślnie `-d`. Inny model mentalny. Samouczki jednoakapitowe mieszają te dwa pojęcia na tyle często, że powoduje to poważne błędy.

`-F` raz na pole. Zwykłe pole formularza:

```

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

```

Przesyłanie pliku:

```

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

```

Prefiks `@` nakazuje programowi curl odczytać plik z dysku i uwzględnić jego zawartość w treści żądania. Program curl automatycznie wykrywa typ MIME na podstawie nazwy pliku; w razie potrzeby należy go jawnie zastąpić:

```

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

```

Wiele flag `-F` pakuje wiele pól lub plików do jednego żądania:

```

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

```

W przypadku surowej zawartości pliku bez opakowania multipart, co jest częstą potrzebą podczas przesyłania pliku JSON lub binarnego blobu do punktu końcowego przesyłania strumieniowego, należy użyć `--data-binary @file.bin`. Spowoduje to wysłanie bajtów pliku jako treści żądania w całości, z dowolnym typem zawartości ustawionym jawnie.

Uwierzytelnianie w curl POST: podstawowe, nośnikowe, klucze API

Trzy kształty uwierzytelniania obejmują niemal każdy interfejs API REST w 2026 r. Uwierzytelnianie podstawowe (nazwa użytkownika i hasło, zakodowane w formacie Base64 w nagłówku):

```

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

```

Tokeny nośnika, używane przez większość nowoczesnych interfejsów API, w tym wszystkie poświadczenia wydane przez OAuth, korzystają z niestandardowego nagłówka Authorization:

```

curl -H "Autoryzacja: Nośnik $TOKEN" --json '{"q":"hello"}' https://api.example.com/query

```

Klucze API zazwyczaj znajdują się w nagłówku specyficznym dla danej usługi:

```

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

```

Poświadczenia ze zmiennej środowiskowej lub menedżera sekretów, nigdy nie wpisywane inline. Dlaczego? Raport GitGuardian State of Secrets Sprawl z 2025 roku wykazał, że w 2024 roku do publicznego GitHuba wyciekło 23,8 miliona nowych sekretów. To wzrost o 25% w porównaniu z 2023 rokiem. Ponad 90% z nich pozostało ważnych pięć dni po ujawnieniu. Poświadczenia inline w skryptach curl są głównym źródłem tych wycieków. Sekcja dotycząca bezpieczeństwa poniżej omawia przepływ pracy.

Przykład POST w świecie rzeczywistym: API płatności Plisio

Dokumenty referencyjne bez rzeczywistego przykładu to teoria. Poniższy kod POST curl generuje fakturę za płatność kryptowalutą za pośrednictwem interfejsu API REST firmy Plisio. Plisio pobiera stałą opłatę w wysokości 0,5%; firmy obsługujące płatności kartami zazwyczaj pobierają 2-4%. Plisio obsługuje ponad trzydzieści kryptowalut i oferuje integracje z dziewiętnastoma platformami e-commerce.

Dlaczego API kryptowalutowe działają jako cele praktyczne? W 2025 roku obroty stablecoinów wyniosły około 28 bilionów dolarów w realnym wolumenie ekonomicznym. Chainalysis oszacował wzrost na 133% CAGR od 2023 roku. Rynek bramek płatności kryptowalutowych oscylował wokół 2 miliardów dolarów w 2025 roku, zmierzając do 2,39 miliarda dolarów w 2026 roku (według The Business Research Company). BitPay, Coinbase Commerce, Plisio: wybierz dowolny. Pierwszym krokiem integracji z dowolną nowoczesną bramką jest prawie zawsze polecenie curl POST.

Minimalna instrukcja utworzenia nowej faktury:

```

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

-H "Typ zawartości: aplikacja/json" \

-H "Autoryzacja: Nośnik $PLISIO_API_KEY" \

-d '{

"source_currency": "USD",

"source_amount": 49.99,

"order_number": "INV-1042",

"currency": "BTC",

"email": "[email protected]",

"order_name": "Annual subscription"

}'

```

Pomyślne wywołanie zwraca kod HTTP 201. Treść odpowiedzi to obiekt JSON: wygenerowany identyfikator faktury, `invoice_url`, na który klient dokonuje płatności, adres portfela docelowego i znacznik czasu wygaśnięcia. Przepuść to przez `jq`, aby pobrać potrzebne pole:

```

... | jq '.data.invoice_url'

```

Oto cały schemat. Zamień punkt końcowy, zamień ładunek, a kształt zostanie przeniesiony bezpośrednio do płatności BitPay, kasy Coinbase Commerce lub intencji płatności Stripe. Flagi się nie zmieniają; zmienia się tylko JSON.

Debugowanie żądania POST curl: -v, --trace, błędy

Nieudany test POST to zagadka dla debuggera. Ponawianie prób bezmyślnie to najgorszy pomysł. Cztery opcje w wierszu poleceń pokrywają większość potrzeb.

`-v` drukuje wiersz żądania, każdy nagłówek żądania i status odpowiedzi. To pierwsza flaga, po którą sięgasz. `--trace-ascii -` to większy problem: zrzuca całą konwersację, w tym treść wiadomości POST, na standardowe wyjście. Użyj `curl -i`, aby wstawić nagłówki odpowiedzi nad treścią. Z kolei `-w "%{http_code}\n"` zapisuje tylko kod statusu HTTP, co jest przydatne podczas sprawdzania ciągłości działania (CI) w API.

O kodach statusu, które najczęściej widzisz. 400: serwer przeanalizował Twoje żądanie, ale odrzucił ładunek. 401: brakujący lub nieprawidłowy nagłówek uwierzytelniania. 415: błędny typ zawartości. 500: serwer uległ awarii po wprowadzeniu danych. Każdy z nich wyklucza określoną warstwę, co stanowi połowę wartości uruchomienia `-v` przy pierwszym błędzie.

Bezpieczeństwo POST w curl: klucze API, sekrety i wycieki

Wszystkie odniesienia pomijają tę sekcję. Wspomina o niej każda analiza incydentów. Grudzień 2024: naruszenie bezpieczeństwa Departamentu Skarbu USA zostało powiązane z wyciekiem klucza API BeyondTrust. Dokładnie takie dane uwierzytelniające znajdują się w nagłówkach `-H "Authorization: Bearer..." w skryptach produkcyjnych.

Obrona jest mało efektowna. Odczyt tokenów ze zmiennych środowiskowych. Przechowywanie ich w menedżerze sekretów, takim jak AWS Secrets Manager, HashiCorp Vault lub interfejs wiersza poleceń 1Password. Utrzymywanie hooka pre-commit z uruchomionym `gitleaks` lub `trufflehog`. Rotacja tokenów, które kiedykolwiek istniały w historii powłoki. Nic z tego nie jest ekscytujące. Wszystko działa. Stosowanie tego w każdym żądaniu POST curl to najważniejszy nawyk, jaki może wyrobić sobie programista back-end w 2026 roku.

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.