Curl ile POST isteği nasıl gönderilir: eksiksiz referans

Şu anda dünyanın bir yerinde yaklaşık yirmi milyar curl kurulumu çalışıyor. Bu rakam, aracı neredeyse tek başına sürdüren yaratıcısı Daniel Stenberg'den geliyor. Curl, yönlendiricilerde, arabalarda, uydularda, akıllı TV'lerde, halka açık web'in çoğunu destekleyen Linux sunucularında ve tüm büyük LLM çalışma ortamlarında yer alıyor. Bu kurulumların kullandığı tüm HTTP fiilleri arasında POST, en ağır işi yapıyor. Çoğu geliştirici, bir API'yi ilk kez test etmek, hata ayıklamak veya entegre etmek için curl POST isteğini kullanıyor.

Postman'ın 2025 API Durum Raporu, REST'in %93 oranında benimsendiğini gösteriyor. Kuruluşların %82'si artık en azından kısmen API öncelikli olarak çalışıyor. Bir sunucuya veri oluştururken, gönderirken veya iletirken kullandığınız fiil POST'tur. Yapay zeka iş yükleri bu trendi daha da hızlandırdı. Yapay zeka kullanımına atfedilen API trafiği 2024'te %73 arttı (Postman, 2024) ve her LLM sağlayıcısının dokümantasyonu artık standart "ilk çağrı" olarak bir curl POST kod parçasıyla başlıyor.

Bu kaynak, curl kullanarak yapılan bir POST isteğinin alabileceği her şekli, tek satırlık minimum koddan gerçek bir kripto ödeme API'sine yapılan çalışan bir çağrıya kadar adım adım açıklıyor. Amaç: Sadece okumak değil, kopyalayıp yapıştırabileceğiniz bir şey oluşturmak. Bir sunucuya ilk kez veri göndermek veya gece 2'de bir webhook işleyiciyi yeniden oluşturmak olsun, aşağıdaki örnekler gerçekten ihtiyacınız olanı kapsıyor.

Aşağıdaki tablo kısa bir özettir. POST istekleri gönderilirken en sık kullanılan curl komut satırı seçeneklerini kapsayan, bayrak ve amaç içeren kısa bir bilgi notu. Her biri aşağıdaki bölümlerde ayrıntılı olarak açıklanmıştır.

Curl POST isteğini ve HTTP yöntemini anlamak

Curl POST isteği, komut satırından gönderilen ve POST yöntemiyle iletilen bir HTTP POST isteğidir. Curl aracı, görevini yirmiyi aşkın protokol arasında "veri aktarımı" olarak tanımlar; HTTP bunlardan sadece biridir. POST şu anlama gelir: İşte bazı veriler, bunlarla bir şeyler yapın. Yük, istek gövdesine gider, asla URL'ye değil. Bu özellik, POST'un kaynak oluşturma, form gönderimleri ve kimlik bilgilerini içeren her şeyi ele almasının nedenidir. GET, verileri sorgu dizesine yerleştirir ve bu veriler her proxy ve her tarayıcı geçmişi tarafından görülebilir. POST bunu yapmaz.

Çoğu eğitimde küçük ama faydalı bir ayrıntı atlanıyor. `-d` parametresini geçerseniz, curl otomatik olarak POST yöntemine geçer. Kullanılacak özel bir istek yöntemini belirten açık `-X POST` parametresi isteğe bağlıdır. Birçok örnekte yine de yer alıyor çünkü yükün yanında `-X POST` yazması, amacı bir bakışta açıkça gösteriyor.

PUT ve POST işlemleri sıklıkla karıştırıldığı için açıklığa kavuşturmakta fayda var. PUT, bilinen bir konumdaki bir kaynağı değiştirir. POST ise yeni bir kaynak oluşturur veya verileri genel bir uç noktada işlenmek üzere gönderir.

Temel curl POST sözdizimi ve -d bayrağının pratikteki kullanımı

Minimum curl POST isteği tek satırdan oluşmalıdır:

```

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

```

İşte bu kadar. POST isteği, form-urlencoded gövde, sorun yok. `-d` üç görevi birden yerine getiriyor: yükü istek gövdesine yerleştiriyor, istek yöntemini POST'a çeviriyor ve varsayılan başlık olarak `Content-Type: application/x-www-form-urlencoded` ekliyor. Ben genellikle biraz daha ayrıntılı olan formu yapıştırıyorum çünkü POST amacı kod incelemesinde daha iyi okunuyor:

```

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

```

İletim hattında aynı baytlar. Aynı istek argümanları. Ekibinizin taramayı daha kolay bulduğu hangisi ise onu kullanın. `-d` bayrağı, komut satırından bir sunucuya veri göndermek için kullanılan temel araçtır ve bir arka uç geliştiricisinin curl'e gönderdiği şeylerin yüzde doksanını halleder: kabuk çağrıları, webhook testleri, Makefile hedefleri, GitHub Actions adımları.

`-d` seçeneğinin üç yakın akrabası. `--data-binary` baytlarınızı olduğu gibi korur; standart `-d` yeni satırları kaldırır ve ikili veriyi bozar. `--data-urlencode` sizin için yüzde kodlaması yapar: `--data-urlencode "name=I am Daniel"` `name=I%20am%20Daniel` olarak gelir. `--data-raw`, bir değer `@` ile başladığında ve curl'ün bir dosyayı okumaması gerektiğinde kullanılan bir kaçış yoludur. Birden fazla `-d` bayrağı `&` ile birleştirilir. Formlar için uygundur. Asla JSON için değil.

Son bir püf noktası: tırnak işaretleri. Yükün etrafına tek tırnak koymak, kabuğun `$` veya ters eğik çizgileri yorumlamasını engeller. Bunları unutursanız, POST verilerinizin yarısının neden eksik olduğunu sorarak gece 2'yi geçirirsiniz.

Bu ayrıntılar önemlidir çünkü curl, gezegendeki en çok test edilen HTTP istemcilerinden biridir. Stenberg'in Aralık 2025 tarihli retrospektif raporunda o yıl sekiz sürüm yayınlandığı belirtiliyor. Dokuz CVE (güvenlik açığı), hepsi düşük veya orta seviyede derecelendirilmiş. 2.179 aktif test senaryosu, bunlardan 232'si on iki aydan daha öncesine ait. Aralık 2024'te yayınlanan 8.11.1 sürümü, CVE-2024-11053'ü (netrc ve yönlendirme kimlik bilgisi sızıntısı) yamaladı. Nisan 2026 sonu itibariyle mevcut kararlı sürüm curl 8.20.0'dır. 7.82.0'ın altında kalanlar hala `--json` bayrağına sahip değil ve eski üç bayraklı modele geri dönüyor.

--json veya -H seçeneklerini kullanarak curl ile JSON verisi gönderme

JSON, 2026 yılında REST API'lerinin ortak dilidir. Curl ile POST etmenin iki yolu vardır. Hangisini kullanacağınız tamamen makinede kurulu olan curl sürümüne bağlıdır.

Klasik üç bayrak deseni, CentOS 6 ve sonrasındaki tüm sürümlerde çalışır:

```

curl -X POST \

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

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

https://api.example.com/orders

```

Curl 7.82.0 (Mart 2022) sürümünden itibaren kullanılabilen modern stenografi:

```

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

```

`--json` bayrağı üç şey yapar: `Content-Type: application/json` değerini ayarlar, `Accept: application/json` değerini ayarlar ve gövdeyi gönderir. Ayrıca birleştirme işlemi de yapar: `--json` değerini birden fazla kez geçerseniz, yükler birleşir. JSON parçalarını akış uç noktasına yönlendirirken kullanışlıdır.

Dosyada saklanan JSON verileri için dosya yolunun başına `@` ekleyin. JSON nesnesi satır içi yapıştırma için çok büyük olduğunda, sürüm kontrolünde bulunduğunda veya başka bir komut dosyası tarafından oluşturulduğunda, dosyadan veri göndermek standart yöntem haline gelir:

```

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

```

İkinci yöntem, `order.json` adlı bir dosyadan verileri okur ve tüm doğru başlıklarla birlikte gönderir. Büyük veya potansiyel olarak ikili JSON içeriği için `--data-binary @file.json` daha güvenli bir seçenektir. Yeni satırları kaldırmaz, özel karakterleri yorumlamaz ve form alanları yerine bayt bekleyen bir uç noktaya ham ikili veri gönderir. Üçüncü yöntem, `-d @-` aracılığıyla verileri standart girişten okur. Başka bir komutun çıktısını doğrudan curl POST'a yönlendirirken kullanışlıdır.

Aşağıdaki tablo, dört yaygın JSON biçimini tek bir uç noktaya eşleştirmektedir:

Bu, eskiden olduğundan daha önemli. Her büyük LLM sağlayıcısı — OpenAI, Anthropic, Mistral, Google — API dokümanlarını tam olarak bu şekli kullanan bir curl POST örneğiyle açıyor. Yapay zeka destekli trafik, 2024 yılında genel API çağrı hacmine %73 oranında katkı sağladı (Postman). curl artık "bu uç noktayı nasıl çağırırım" sorusunun standart referansı haline geldi.

Content-Type, başlıklar ve curl'ün varsayımları

"415 Desteklenmeyen Medya Türü" yanıtlarının çoğu, eksik bir başlıktan kaynaklanır. `-d` seçeneğiyle curl, isteğinize sessizce `Content-Type: application/x-www-form-urlencoded` damgasını ekler. `-H "Content-Type: application/json"` veya `--json` olmadan bir JSON gövdesi gönderirseniz, 415 hatası alırsınız. Hiçbir uyarı yok, sadece reddedilme.

Diğer meta veriler de gövdeyle birlikte gelir: Content-Length, Authorization başlığı, izleme için X-Request-Id. Bu meta verileri doğru ayarlamak, herhangi bir API entegrasyonunun yarısıdır. JSON nesnesinin kendisi ise kolay olan yarısıdır.

`-H`, özel başlıklar ekler. Gerektiği kadar tekrarlayın. Başlık adları büyük/küçük harf duyarlı değildir; değerler ise duyarlıdır. Yanlış yapılandırılmış bir POST isteğini gidermenin en hızlı yolu: `-v` ile bir kez çalıştırın, istek satırını okuyun ve API belgeleriyle karşılaştırın. On vakadan sekizinde hata saniyeler içinde ortaya çıkar.

İki not daha. Content-Length, curl tarafından body size'dan otomatik olarak ayarlanır; nadiren geçersiz kılmanız gerekir. `Accept: application/json`, sunucuya HTML yerine JSON formatında yanıt vermesini söyler. Bunun için başka bir `-H` ekleyin veya Content-Type ve Accept'i birlikte ayarlayan `--json` kullanın.

curl POST -F komutuyla form verileri ve dosya yüklemeleri

Dosya içeren HTML tarzı form verileri için doğru bayrak `-F`'dir. Bu, `multipart/form-data` isteği oluşturur. Varsayılan olarak `-d` ile kodlanan formdan farklı bir içerik türüdür. Farklı bir zihinsel model söz konusudur. Tek paragraflık eğitimlerde bu iki kavram sıklıkla karıştırıldığı için gerçek hatalara yol açmaktadır.

`-F` her alan için bir kez kullanılır. Düz metin alanı:

```

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

```

Dosya yükleme:

```

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

```

`@` öneki, curl'e dosyayı diskten okumasını ve içeriğini istek gövdesine dahil etmesini söyler. curl, dosya adından MIME türünü otomatik olarak algılar; gerektiğinde bunu açıkça geçersiz kılabilirsiniz:

```

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

```

Birden fazla `-F` bayrağı, birden fazla alanı veya dosyayı tek bir istekte birleştirir:

```

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

```

Çok parçalı sarmalayıcı olmadan ham dosya içeriği için (bir JSON dosyası veya ikili veri bloğunu akış uç noktasına gönderirken sıkça ihtiyaç duyulan bir durum), bunun yerine `--data-binary @file.bin` kullanın. Bu, dosya baytlarını, açıkça belirlediğiniz Content-Type ile birlikte, istek gövdesi olarak olduğu gibi gönderir.

Curl POST isteğinde kimlik doğrulama: temel, taşıyıcı, API anahtarları

2026 yılında neredeyse tüm REST API'leri kapsayan üç kimlik doğrulama şekli vardır. Temel kimlik doğrulama (kullanıcı adı ve parola, base64 kodlu olarak bir başlığa yerleştirilir):

```

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

```

OAuth tarafından verilen tüm kimlik bilgileri de dahil olmak üzere çoğu modern API tarafından kullanılan taşıyıcı token'lar, özel bir Authorization başlığı üzerinde yer alır:

```

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

```

API anahtarları genellikle hizmete özgü bir başlıkta bulunur:

```

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

```

Ortam değişkeninden veya gizli bilgi yöneticisinden alınan kimlik bilgileri asla doğrudan kod içine yazılmaz. Neden? GitGuardian'ın 2025 Gizli Bilgi Yayılımı Durumu raporuna göre, 2024 yılında halka açık GitHub'a 23,8 milyon yeni gizli bilgi sızdırıldı. Bu, 2023'e göre %25'lik bir artış anlamına geliyor. Bunların %90'ından fazlası, ifşa edildikten beş gün sonra bile geçerliliğini korudu. Curl komut dosyalarındaki doğrudan kod içine yazılan kimlik bilgileri, bu sızıntıların önde gelen kaynaklarından biridir. Aşağıdaki güvenlik bölümü iş akışını ele almaktadır.

Gerçek dünya curl POST örneği: Plisio ödeme API'si

Gerçek bir örnek içermeyen referans belgeleri teoriden ibarettir. Aşağıdaki curl POST isteği, Plisio'nun REST API'si aracılığıyla bir kripto para ödeme faturası oluşturur. Plisio %0,5 sabit ücret alır; kart işlemcileri genellikle %2-4 arası ücret alır. Plisio otuzdan fazla kripto para birimini destekler ve on dokuz e-ticaret platformu için entegrasyon sunar.

Kripto API'lerinin neden pratik hedefler olarak işe yaradığı. Stablecoin'ler 2025 yılında yaklaşık 28 trilyon dolarlık reel ekonomik hacim hareket ettirdi. Chainalysis, 2023'ten bu yana büyüme oranını %133 yıllık bileşik büyüme oranı (CAGR) olarak belirledi. Kripto ödeme ağ geçidi pazarı 2025'te 2 milyar dolar civarında seyretti ve 2026'da 2,39 milyar dolara ulaşması bekleniyor (The Business Research Company'ye göre). BitPay, Coinbase Commerce, Plisio: herhangi birini seçin. Herhangi bir modern ağ geçidiyle ilk entegrasyon adımı neredeyse her zaman bir curl POST işlemidir.

Yeni bir fatura oluşturmak için gereken minimum işlem:

```

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

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

-H "Yetkilendirme: Taşıyıcı $PLISIO_API_KEY" \

-d '{

"source_currency": "USD",

"source_amount": 49.99,

"order_number": "INV-1042",

"currency": "BTC",

"email": "[email protected]",

"order_name": "Annual subscription"

}'

```

Başarılı bir çağrı HTTP 201 döndürür. Yanıt gövdesi bir JSON nesnesidir: oluşturulan bir fatura kimliği, müşterinin ödeme yaptığı bir `invoice_url`, hedef cüzdan adresi ve bir son kullanma zaman damgası. Bundan sonra ihtiyacınız olan alanı çekmek için bunu `jq` üzerinden geçirin:

```

... | jq '.data.invoice_url'

```

İşte tüm model bu. Uç noktayı değiştirin, yükü değiştirin ve yapı doğrudan BitPay ödemesine, Coinbase Commerce ödeme sayfasına veya Stripe ödeme amacına aktarılır. Bayraklar değişmez; sadece JSON değişir.

Curl POST isteğinde hata ayıklama: -v, --trace, errors

Başarısız bir POST işlemi, hata ayıklama gerektiren bir bulmacadır. Körlemesine tekrar denemek en kötü hamledir. Komut satırındaki dört seçenek, ihtiyaç duyduğunuz şeylerin çoğunu karşılar.

`-v`, istek satırını, her istek başlığını ve yanıt durumunu yazdırır. Bu, ilk başvurmanız gereken bayraktır. `--trace-ascii -` daha güçlüdür: POST isteğinin gövdesi de dahil olmak üzere tüm konuşmayı standart çıktıya yazdırır. Yanıt başlıklarını gövdenin üstüne eklemek için `curl -i` kullanın. Ve `-w "%{http_code}\n"` yalnızca HTTP durum kodunu yazar; bu, bir API'ye karşı CI kontrolleri betiklerken kullanışlıdır.

En sık göreceğiniz durum kodları hakkında: 400: Sunucu isteğinizi ayrıştırdı ancak yükü reddetti. 401: Eksik veya geçersiz kimlik doğrulama başlığı. 415: Yanlış Content-Type. 500: Sunucu girişinizde çöktü. Her biri belirli bir katmanı devre dışı bırakır; bu da ilk hatada `-v` çalıştırmanın değerinin yarısıdır.

curl POST güvenliği: API anahtarları, sırlar ve veri sızıntıları

Her referans bu bölümü atlıyor. Her olay sonrası incelemede bundan bahsediliyor. Aralık 2024: ABD Hazine Bakanlığı'ndaki veri ihlali, sızdırılan bir BeyondTrust API anahtarına kadar izlendi. Tam olarak üretim komut dosyalarındaki `-H "Authorization: Bearer ..."` başlıklarının içinde yer alan türden bir kimlik bilgisi.

Savunma yöntemi gösterişsizdir. Token'ları ortam değişkenlerinden okuyun. Bunları AWS Secrets Manager, HashiCorp Vault veya 1Password CLI gibi bir gizli veri yöneticisinde saklayın. `gitleaks` veya `trufflehog` çalıştıran bir ön taahhüt kancası bulundurun. Kabuk geçmişinde yer alan tüm token'ları döndürün. Bunların hiçbiri heyecan verici değil. Ama hepsi işe yarıyor. Bunu gönderdiğiniz her curl POST isteğine uygulamak, bir arka uç geliştiricisinin 2026'da edinebileceği en önemli alışkanlıktır.

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.