Cara mengirim permintaan POST dengan curl: referensi lengkap

Saat ini, terdapat sekitar dua puluh miliar instalasi curl yang berjalan di suatu tempat di dunia. Angka tersebut berasal dari pencipta alat ini, Daniel Stenberg, yang hampir sendirian mengelolanya. Curl terpasang di dalam router, mobil, satelit, smart TV, server Linux yang mendukung sebagian besar web publik, dan setiap runtime LLM utama. Dari semua perintah HTTP yang digunakan instalasi tersebut, POST adalah yang paling banyak digunakan. Permintaan POST curl adalah cara sebagian besar pengembang menguji, men-debug, atau mengintegrasikan API untuk pertama kalinya.

Laporan State of the API 2025 dari Postman menempatkan REST pada tingkat adopsi 93%. 82% organisasi sekarang beroperasi setidaknya sebagian dengan pendekatan API-first. POST adalah kata kerja yang Anda gunakan setiap kali membuat, mengirimkan, atau mentransmisikan data ke server. Beban kerja AI semakin mempercepat tren tersebut. Lalu lintas API yang dikaitkan dengan penggunaan AI tumbuh 73% pada tahun 2024 (Postman, 2024), dan setiap dokumentasi penyedia LLM sekarang diawali dengan cuplikan curl POST sebagai "panggilan pertama" yang baku.

Referensi ini membahas setiap bentuk permintaan POST menggunakan curl, mulai dari yang paling sederhana satu baris hingga panggilan yang berfungsi terhadap API pembayaran kripto sungguhan. Tujuannya: sesuatu yang dapat Anda salin, bukan hanya dibaca. Baik itu mengirim data ke server untuk pertama kalinya atau membangun ulang penangan webhook pada pukul 2 pagi, pola-pola di bawah ini mencakup apa yang sebenarnya Anda butuhkan.

Tabel di bawah ini adalah versi singkatnya. Lembar contekan berisi opsi baris perintah curl yang paling sering digunakan saat mengirim permintaan POST. Masing-masing akan dijelaskan lebih detail di bagian-bagian selanjutnya.

Memahami permintaan POST curl dan metode HTTP

Permintaan POST curl adalah permintaan HTTP POST, yang dikirim dengan metode POST, yang dijalankan dari baris perintah. Alat curl sendiri mendeskripsikan tugasnya sebagai "mentransfer data" melalui lebih dari dua lusin protokol, di mana HTTP hanyalah salah satunya. POST berarti: ini adalah beberapa data, lakukan sesuatu dengannya. Muatan data masuk ke dalam badan permintaan, tidak pernah di URL. Sifat itulah mengapa POST menangani pembuatan sumber daya, pengiriman formulir, dan apa pun yang membawa kredensial. GET menyimpan data dalam string kueri, yang terlihat oleh setiap proxy dan setiap riwayat browser. POST tidak.

Sebagian besar tutorial melewatkan detail kecil namun bermanfaat. Lewatkan `-d` dan curl akan secara otomatis beralih ke POST. `-X POST` eksplisit, yang menentukan metode permintaan khusus yang akan digunakan, bersifat opsional. Banyak contoh masih menyertakannya karena membaca `-X POST` di samping payload membuat maksudnya jelas sekilas.

PUT dan POST seringkali membingungkan, sehingga perlu dijelaskan secara konkret. PUT mengganti sumber daya di lokasi yang diketahui. POST membuat sumber daya baru atau mengirim data untuk diproses di titik akhir generik.

Sintaks dasar curl POST dan flag -d dalam praktiknya

POST curl minimal adalah satu baris:

```

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

```

Itu saja. Permintaan POST, body form-urlencoded, tanpa ribet. `-d` melakukan tiga tugas sekaligus: memasukkan payload ke dalam body permintaan, mengubah metode permintaan menjadi POST, dan menambahkan `Content-Type: application/x-www-form-urlencoded` sebagai header default. Saya biasanya tetap menempelkan formulir yang sedikit lebih panjang, karena maksud POST lebih mudah dibaca dalam tinjauan kode:

```

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

```

Byte yang sama di jaringan. Argumen permintaan yang sama. Gunakan mana pun yang menurut tim Anda lebih mudah dipindai. Flag `-d` adalah andalan yang digunakan untuk mengirim data ke server dari baris perintah, dan menangani sembilan puluh persen dari apa yang pernah diberikan pengembang backend pada curl: panggilan shell, pengujian webhook, target Makefile, langkah-langkah GitHub Actions.

Tiga sepupu dekat dari `-d`. `--data-binary` menjaga byte Anda tetap utuh; `-d` biasa menghilangkan baris baru dan akan merusak muatan biner. `--data-urlencode` melakukan pengkodean persen untuk Anda: `--data-urlencode "name=I am Daniel"` akan menghasilkan `name=I%20am%20Daniel`. `--data-raw` adalah jalan keluar ketika sebuah nilai dimulai dengan `@` dan curl tidak boleh membaca file. Beberapa flag `-d` digabungkan dengan `&`. Baik untuk formulir. Tidak pernah untuk JSON.

Satu hal terakhir yang perlu diperhatikan: penggunaan tanda kutip. Tanda kutip tunggal di sekitar payload akan mencegah shell menginterpretasikan `$` atau garis miring terbalik. Jika Anda melupakannya, Anda akan menghabiskan waktu hingga pukul 2 pagi bertanya-tanya mengapa setengah dari data POST Anda hilang.

Detail-detail ini penting karena curl sendiri merupakan salah satu klien HTTP yang paling banyak diuji di dunia. Retrospektif Stenberg pada Desember 2025 mencatat delapan rilis pada tahun itu. Sembilan CVE, semuanya diberi peringkat rendah atau sedang. 2.179 kasus uji aktif, 232 lebih banyak daripada dua belas bulan sebelumnya. Rilis 8.11.1, Desember 2024, menambal CVE-2024-11053 (kebocoran kredensial netrc-and-redirect). Versi stabil saat ini pada akhir April 2026 adalah curl 8.20.0. Siapa pun yang masih menggunakan versi di bawah 7.82.0 masih belum memiliki flag `--json` dan kembali ke pola tiga flag yang lebih lama.

Mengirim data JSON dengan curl menggunakan --json atau -H

JSON adalah bahasa umum API REST di tahun 2026. Ada dua cara untuk mengirimkannya menggunakan curl. Cara mana yang akan digunakan sepenuhnya bergantung pada versi curl yang terpasang di mesin tersebut.

Pola tiga bendera klasik, berfungsi di mana saja mulai dari CentOS 6 dan seterusnya:

```

curl -X POST \

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

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

https://api.example.com/orders

```

Singkatan modern, tersedia sejak curl 7.82.0 (Maret 2022):

```

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

```

Opsi `--json` melakukan tiga hal. Mengatur `Content-Type: application/json`. Mengatur `Accept: application/json`. Mengirimkan isi pesan. Opsi ini juga menggabungkan: jika `--json` diberikan lebih dari sekali, muatan data akan digabungkan. Berguna saat mengirimkan potongan JSON ke endpoint streaming.

Untuk muatan JSON yang disimpan dalam file, tambahkan awalan `@` pada jalur file. Mengirim data dari file menjadi pola standar setelah objek JSON terlalu besar untuk ditempelkan langsung, atau setelah disimpan dalam kontrol versi, atau setelah skrip lain membuatnya:

```

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

```

Pola kedua membaca data dari file bernama `order.json` dan mengirimkannya dengan semua header yang tepat. Untuk konten JSON yang besar atau berpotensi biner, `--data-binary @file.json` adalah pilihan yang lebih aman. Ini tidak menghapus baris baru, tidak menginterpretasikan karakter khusus, dan mengirimkan data biner mentah ke endpoint yang mengharapkan byte, bukan field formulir. Pola ketiga membaca data dari stdin melalui `-d @-`. Berguna saat mengalirkan output dari perintah lain langsung ke POST curl.

Tabel di bawah ini memetakan empat bentuk JSON umum terhadap satu titik akhir (endpoint):

Hal ini menjadi lebih penting dari sebelumnya. Setiap penyedia LLM utama — OpenAI, Anthropic, Mistral, Google — membuka dokumentasi API mereka dengan contoh curl POST yang menggunakan bentuk persis seperti ini. Lalu lintas yang didorong oleh AI menambahkan 73% pada volume panggilan API secara keseluruhan pada tahun 2024 (Postman). curl sekarang menjadi referensi standar untuk "bagaimana cara saya memanggil endpoint ini."

Content-Type, header, dan asumsi yang digunakan curl.

Sebagian besar balasan "415 Unsupported Media Type" disebabkan oleh satu header yang hilang. Dengan `-d`, curl secara diam-diam menambahkan `Content-Type: application/x-www-form-urlencoded` ke permintaan Anda. Kirim body JSON tanpa `-H "Content-Type: application/json"` atau `--json`, dan Anda akan mendapatkan kode kesalahan 415. Tidak ada peringatan, hanya penolakan.

Metadata lain juga ikut terbawa bersama body permintaan: Content-Length, header Authorization, X-Request-Id untuk pelacakan. Memastikan metadata tersebut benar adalah setengah dari keberhasilan integrasi API. Objek JSON itu sendiri adalah bagian yang mudah.

`-H` menambahkan header kustom. Ulangi sesuai kebutuhan. Nama header tidak peka huruf besar/kecil; nilainya peka huruf besar/kecil. Cara tercepat untuk men-debug POST yang salah konfigurasi: jalankan dengan `-v` sekali, baca baris permintaan, bandingkan dengan dokumentasi API. Delapan dari sepuluh kali, bug akan muncul dalam hitungan detik.

Dua catatan lagi. Content-Length diatur secara otomatis oleh curl dari ukuran body; Anda jarang mengubahnya. `Accept: application/json` adalah yang memberi tahu server untuk membalas dalam format JSON, bukan HTML. Tambahkan `-H` lagi untuk itu, atau gunakan `--json`, yang mengatur Content-Type dan Accept secara bersamaan.

Unggahan data formulir dan file dengan curl POST -F

Untuk data formulir bergaya HTML dengan file, flag yang tepat adalah `-F`. Ini menghasilkan permintaan `multipart/form-data`. Tipe konten berbeda dari yang dienkode URL formulir yang dihasilkan oleh `-d` secara default. Model mental yang berbeda. Tutorial satu paragraf seringkali mencampuradukkan keduanya sehingga menyebabkan bug nyata.

`-F` sekali per kolom. Kolom formulir biasa:

```

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

```

Unggahan file:

```

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

```

Awalan `@` memberi tahu curl untuk membaca file dari disk dan menyertakan isinya dalam isi permintaan. Curl secara otomatis mendeteksi tipe MIME dari nama file; ganti secara eksplisit jika diperlukan:

```

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

```

Beberapa flag `-F` menggabungkan beberapa field atau file ke dalam satu permintaan:

```

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

```

Untuk konten file mentah tanpa pembungkus multipart, yang merupakan kebutuhan umum saat mengirim file JSON atau blob biner ke endpoint streaming, gunakan `--data-binary @file.bin` sebagai gantinya. Ini mengirimkan byte file sebagai isi permintaan apa adanya, dengan Content-Type apa pun yang Anda tetapkan secara eksplisit.

Autentikasi dalam curl POST: basic, bearer, kunci API

Tiga bentuk otentikasi mencakup hampir semua API REST pada tahun 2026. Otentikasi dasar (nama pengguna ditambah kata sandi, dienkode base64 ke dalam header):

```

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

```

Token bearer, yang digunakan oleh sebagian besar API modern termasuk setiap kredensial yang diterbitkan OAuth, menggunakan header Otorisasi khusus:

```

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

```

Kunci API biasanya terdapat di header khusus layanan:

```

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

```

Kredensial berasal dari variabel lingkungan atau pengelola rahasia, tidak pernah diketik langsung. Mengapa? Laporan GitGuardian State of Secrets Sprawl 2025 mencatat 23,8 juta rahasia baru bocor ke GitHub publik selama tahun 2024. Peningkatan 25% dibandingkan tahun 2023. Lebih dari 90% di antaranya tetap valid lima hari setelah terungkap. Kredensial langsung dalam skrip curl adalah sumber utama kebocoran tersebut. Bagian keamanan di bawah ini membahas alur kerjanya.

Contoh nyata penggunaan curl POST: API pembayaran Plisio

Dokumen referensi tanpa contoh nyata hanyalah teori. Permintaan POST curl di bawah ini membuat faktur pembayaran kripto melalui API REST Plisio. Plisio mengenakan biaya tetap 0,5%; pemroses kartu biasanya 2-4%. Plisio mendukung lebih dari tiga puluh mata uang kripto dan menyediakan integrasi untuk sembilan belas platform e-commerce.

Mengapa API kripto berfungsi sebagai target latihan. Stablecoin menggerakkan volume ekonomi riil sekitar $28 triliun selama tahun 2025. Chainalysis memperkirakan pertumbuhannya sebesar 133% CAGR sejak tahun 2023. Pasar gerbang pembayaran kripto berada di kisaran $2 miliar pada tahun 2025, dan diperkirakan mencapai $2,39 miliar pada tahun 2026 (menurut The Business Research Company). BitPay, Coinbase Commerce, Plisio: pilih salah satu. Langkah integrasi pertama dengan gerbang modern mana pun hampir selalu berupa POST curl.

Perintah minimal untuk membuat faktur baru:

```

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

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

-H "Otorisasi: Pemegang $PLISIO_API_KEY" \

-d '{

"source_currency": "USD",

"source_amount": 49.99,

"order_number": "INV-1042",

"currency": "BTC",

"email": "[email protected]",

"order_name": "Annual subscription"

}'

```

Panggilan yang berhasil akan mengembalikan HTTP 201. Isi respons berupa objek JSON: ID faktur yang dihasilkan, `invoice_url` tempat pelanggan melakukan pembayaran, alamat dompet tujuan, dan stempel waktu kedaluwarsa. Salurkan melalui `jq` untuk mengambil bidang mana pun yang Anda butuhkan selanjutnya:

```

... | jq '.data.invoice_url'

```

Itulah keseluruhan polanya. Tukar endpoint, tukar payload, dan bentuknya akan langsung sama untuk pembayaran BitPay, checkout Coinbase Commerce, atau intent pembayaran Stripe. Flagnya tidak berubah; hanya JSON-nya yang berubah.

Mendebug permintaan POST curl: -v, --trace, errors

POST yang gagal adalah teka-teki debugging. Mencoba lagi tanpa arah adalah langkah terburuk. Empat opsi pada baris perintah mencakup sebagian besar yang Anda butuhkan.

`-v` mencetak baris permintaan, setiap header permintaan, dan status respons. Itu adalah flag pertama yang Anda gunakan. `--trace-ascii -` adalah cara yang lebih ampuh: ia mencetak seluruh percakapan, termasuk isi dari POST, ke output standar. Gunakan `curl -i` untuk menyisipkan header respons di atas isi. Dan `-w "%{http_code}\n"` hanya menulis kode status HTTP, berguna saat membuat skrip pemeriksaan CI terhadap API.

Berikut adalah kode status yang paling sering Anda lihat: 400: server telah memproses permintaan Anda tetapi menolak muatannya. 401: header otentikasi hilang atau tidak valid. 415: Content-Type salah. 500: server mengalami crash saat menerima input Anda. Masing-masing kode status tersebut mengesampingkan lapisan tertentu, yang nilainya setengah dari menjalankan `-v` pada kegagalan pertama.

Keamanan POST curl: kunci API, rahasia, dan kebocoran

Setiap referensi melewatkan bagian ini. Setiap analisis pasca-insiden menyebutkannya. Desember 2024: pelanggaran data Departemen Keuangan AS ditelusuri kembali ke kunci API BeyondTrust yang bocor. Persis jenis kredensial yang terdapat di dalam header `-H "Authorization: Bearer ..."` dalam skrip produksi.

Strategi pertahanan ini tidak glamor. Baca token dari variabel lingkungan. Simpan token tersebut di pengelola rahasia seperti AWS Secrets Manager, HashiCorp Vault, atau CLI 1Password. Jalankan hook pre-commit seperti `gitleaks` atau `trufflehog`. Rotasi token apa pun yang pernah ada dalam riwayat shell. Semua ini tidak menarik. Namun, semuanya berhasil. Menerapkannya pada setiap permintaan POST curl yang Anda kirimkan adalah kebiasaan paling penting yang dapat dibangun oleh seorang pengembang backend pada tahun 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.