Як надіслати POST-запит за допомогою curl: повний довідник

Наразі у світі десь працює приблизно двадцять мільярдів інсталяцій curl. Цю цифру вказав творець інструменту, Даніель Стенберг, який майже самостійно його підтримує. Curl встановлюється в маршрутизаторах, автомобілях, супутниках, смарт-телевізорах, серверах Linux, які підтримують більшу частину публічної мережі, та в кожному основному середовищі виконання LLM. З усіх HTTP-дієслів, які ці інсталяції використовують, POST виконує найважчу роботу. За допомогою POST curl більшість розробників вперше тестують, налагоджують або інтегруються з API.

У звіті Postman про стан API за 2025 рік зазначається, що рівень впровадження REST становить 93%. 82% організацій зараз працюють принаймні частково з використанням API. POST – це дієслово, до якого ви звертаєтесь щоразу, коли створюєте, надсилаєте або передаєте дані на сервер. Робоче навантаження штучного інтелекту ще більше прискорило цю тенденцію. Трафік API, пов'язаний з використанням штучного інтелекту, зріс на 73% у 2024 році (Postman, 2024), і документація кожного постачальника LLM тепер відкривається з фрагмента POST у форматі curl як канонічним «першим викликом».

У цьому посібнику описано всі форми, яких може набути POST-запит за допомогою curl, від мінімального рядка до робочого виклику справжнього API криптовалютних платежів. Мета: щось, з чого можна вставляти, а не лише читати. Незалежно від того, чи надсилаєте дані на сервер вперше, чи перебудовуєте обробник вебхука о 2-й годині ночі, наведені нижче шаблони охоплюють те, що вам насправді потрібно.

Наведена нижче таблиця є скороченою версією. Шпаргалка з прапорцями та призначенням, що охоплює параметри командного рядка curl, що найчастіше використовуються під час надсилання POST-запитів. Кожен з них детально описано в наступних розділах.

Розуміння POST-запиту та методу HTTP curl

POST-запит curl — це HTTP-запит POST, що надсилається за допомогою методу POST та запускається з командного рядка. Сам інструмент curl описує свою роботу як «передача даних» через понад два десятки протоколів, одним з яких є HTTP. POST означає: ось деякі дані, зробіть щось з ними. Корисне навантаження розміщується в тілі запиту, а не в URL-адресі. Саме тому POST обробляє створення ресурсів, надсилання форм та все, що містить облікові дані. GET зберігає дані в рядку запиту, видимому для кожного проксі-сервера та кожної історії браузера. POST цього не робить.

У більшості посібників пропускається невелика, але корисна деталь. Передайте `-d` та curl автоматично перемикається на POST. Явний `-X POST`, який вказує на користувацький метод запиту для використання, є необов'язковим. Багато прикладів все ще містять його, оскільки прочитання `-X POST` поруч із корисним навантаженням робить намір очевидним з першого погляду.

PUT та POST плутають досить часто, тому варто уточнити. PUT замінює ресурс у відомому місці. POST створює новий або надсилає дані для обробки в загальній кінцевій точці.

Базовий синтаксис curl POST та прапорець -d на практиці

Мінімальний POST-запит на curl — це один рядок:

```

curl -d "ім'я_користувача=arya&вік=16" https://api.example.com/users

```

Ось і все. POST-запит, тіло запиту, закодоване у формі urlencoded, без зайвого клопоту. `-d` виконує потрійну функцію: він додає корисне навантаження в тіло запиту, перетворює метод запиту на POST та додає `Content-Type: application/x-www-form-urlencoded` як заголовок за замовчуванням. Зазвичай я вставляю трохи більш детальну форму, оскільки POST-намір краще читається під час перегляду коду:

```

curl -X POST -d "ім'я_користувача=arya&вік=16" https://api.example.com/users

```

Ті самі байти на дроті. Ті самі аргументи запиту. Використовуйте той, який ваша команда вважає легшим для сканування. Прапорець `-d` — це робоча конячка, яка використовується для надсилання даних на сервер з командного рядка, і він обробляє дев'яносто відсотків того, що розробник бекенду коли-небудь кидає в curl: виклики оболонки, тести вебхуків, цілі Makefile, кроки дій GitHub.

Три близьких родичі `-d`. `--data-binary` зберігає ваші байти цілими; звичайний `-d` видаляє символи нового рядка та спотворює бінарне навантаження. `--data-urlencode` percent-encodes для вас: `--data-urlencode "name=I am Daniel"` надходить як `name=I%20am%20Daniel`. `--data-raw` — це рятувальний вихід, коли значення починається з `@`, а curl не повинен читати файл. Кілька прапорців `-d` об'єднуються за допомогою `&`. Підходить для форм. Ніколи не для JSON.

І останнє: цитування. Одинарні лапки навколо корисного навантаження не дозволяють оболонці інтерпретувати `$` або зворотні скісну риску. Забудьте про них, і ви витратите 2 години ночі, запитуючи, чому половина ваших POST-даних відсутня.

Ці деталі важливі, оскільки сам curl є одним із найбільш тестованих HTTP-клієнтів на планеті. Ретроспектива Стенберга за грудень 2025 року нарахувала вісім релізів того року. Дев'ять CVE, всі з низьким або середнім рейтингом. 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 API у 2026 році. Два способи його POST за допомогою curl. Який з них використовувати, повністю залежить від версії curl, що встановлена на машині.

Класичний шаблон із трьома прапорцями, працює всюди, починаючи з CentOS 6:

```

curl -X POST \

-H "Тип вмісту: 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: 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` є безпечнішим варіантом. Він не видаляє символи нового рядка, не інтерпретує спеціальні символи та надсилає необроблені бінарні дані до кінцевої точки, яка очікує байти, а не поля форми. Третій шаблон зчитує дані зі stdin через `-d @-`. Зручно, коли вивід з іншої команди передається безпосередньо в curl POST.

У таблиці нижче показано чотири поширені форми JSON для однієї кінцевої точки:

Це мало більше значення, ніж раніше. Кожен великий постачальник LLM — OpenAI, Anthropic, Mistral, Google — відкриває свою API-документацію за допомогою прикладу POST curl, використовуючи саме таку форму. Трафік, керований штучним інтелектом, додав 73% до загального обсягу викликів API у 2024 році (Postman). curl тепер є канонічним посиланням на «як мені викликати цю кінцеву точку».

Тип вмісту, заголовки та те, що передбачає curl

Більшість відповідей "415 Непідтримуваний тип медіа" зводяться до одного відсутнього заголовка. За допомогою `-d` curl непомітно позначає ваш запит `Content-Type: application/x-www-form-urlencoded`. Надішліть тіло JSON без `-H "Content-Type: application/json"` або `--json`, і ви отримаєте назад 415. Без попередження, лише відхилення.

Інші метадані також передаються разом з тілом: Content-Length, заголовок Authorization, X-Request-Id для трасування. Правильне отримання цих метаданих – це половина будь-якої інтеграції API. Сам об'єкт JSON – це найпростіша половина.

`-H` додає власні заголовки. Повторюйте за потреби. Назви заголовків не враховують регістр; значення не враховують. Найшвидший спосіб налагодження неправильно налаштованого POST: запустіть його з `-v` один раз, прочитайте рядок запиту, порівняйте з документацією API. У восьми випадках з десяти помилка виникає за лічені секунди.

Ще два зауваження. 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 "ім'я=Арья" https://api.example.com/submit

```

Завантаження файлу:

```

curl -F "файл=@/шлях/до/зображення.png" https://api.example.com/upload

```

Префікс `@` вказує curl на необхідність зчитування файлу з диска та включення його вмісту до тіла запиту. curl автоматично визначає MIME-тип з імені файлу; за потреби його можна явно перевизначити:

```

curl -F "файл=@фото.png;тип=зображення/png" https://api.example.com/upload

```

Кілька прапорців `-F` об'єднують кілька полів або файлів в один запит:

```

curl -F "title=Відпустка" -F "[email protected]" -F "[email protected]" https://api.example.com/album

```

Для необробленого вмісту файлу без багаточастинної обгортки, що є поширеною потребою під час надсилання JSON-файлу або бінарного блобу до потокової кінцевої точки, використовуйте `--data-binary @file.bin`. Це надсилає байти файлу як тіло запиту дослівно, з будь-яким типом вмісту, який ви явно встановите.

Автентифікація в curl POST: базова, на носія, ключі API

Три форми автентифікації охоплюють майже кожен REST API у 2026 році. Базова автентифікація (ім'я користувача плюс пароль, закодовані в base64 у заголовку):

```

curl -u "мій_користувач:мій_пароль" -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-Ключ: $PLISIO_KEY" --json @invoice.json https://api.plisio.net/api/v1/invoices/new

```

Облікові дані зі змінної середовища або менеджера секретів, які ніколи не вводяться вбудовано. Чому? У звіті GitGuardian «State of Secrets Sprawl 2025» було зафіксовано 23,8 мільйона нових секретів, що витікали до публічного GitHub протягом 2024 року. Це на 25% більше, ніж у 2023 році. Понад 90% з них залишалися дійсними через п'ять днів після розкриття. Вбудовані облікові дані в скриптах curl є основним джерелом цих витоків. У розділі «Безпека» нижче описано робочий процес.

Приклад реального curl POST: API платежів Plisio

Довідкова документація без реального прикладу є теорією. Наведений нижче пост створює рахунок-фактуру на оплату криптовалютою через REST API Plisio. Plisio стягує фіксовану комісію в розмірі 0,5%; оператори обробки карток зазвичай стягують 2-4%. Plisio підтримує понад тридцять криптовалют та постачає інтеграції для дев'ятнадцяти платформ електронної комерції.

Чому крипто API працюють як цілі для практики. Стейблкоїни перемістили приблизно 28 трильйонів доларів у реальному економічному обсязі протягом 2025 року. Chainalysis прогнозує зростання на рівні 133% CAGR з 2023 року. Ринок крипто-платіжних шлюзів коливався близько 2 мільярдів доларів у 2025 році, і знаходиться на шляху до 2,39 мільярда доларів у 2026 році (за даними The Business Research Company). BitPay, Coinbase Commerce, Plisio: оберіть будь-який. Першим кроком інтеграції з будь-яким сучасним шлюзом майже завжди є 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.

Щодо кодів стану, які ви бачитимете найчастіше. 400: сервер проаналізував ваш запит, але відхилив корисне навантаження. 401: відсутній або недійсний заголовок авторизації. 415: неправильний тип вмісту. 500: сервер зламався на вашому введенні. Кожен з них виключає певний шар, що дорівнює половині значення запуску `-v` під час першої невдачі.

Безпека curl POST: ключі API, секрети та витоки

Кожен посил пропускає цей розділ. Кожен інцидент після розбору згадує його. Грудень 2024: витік даних Міністерства фінансів США пов'язаний з витоком ключа API BeyondTrust. Саме такі облікові дані знаходяться в заголовках `-H "Authorization: Bearer ..." у продакшн-скриптах.

Захист не надто привабливий. Зчитуйте токени зі змінних середовища. Зберігайте їх у менеджері секретів, такому як AWS Secrets Manager, HashiCorp Vault або 1Password CLI. Залишайте пре-коміт-хук, що виконує `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.