API Dokümantasyonu

PDF Move API'si ile dosya dönüştürme ve işleme araçlarını kendi uygulamanızdan çalıştırın: kimlik doğrulama, dosya yükleme, iş oluşturma ve iş akışları.

Genel bakış

PDF Move API'si dosya dönüştürme ve işleme araçlarını programatik olarak kullanmanızı sağlar. Tüm uçlar `https://pdfmove.com/api/v1` altındadır ve JSON konuşur (belirtilen istisnalar dışında). Akış her zaman aynıdır: dosyayı imzalı bir URL ile yükleyin, iş oluşturun, durumu sorgulayın, sonucu indirin.

Kimlik doğrulama

API anahtarınızı `Authorization` başlığında Bearer token olarak gönderin. Anahtarlar `pdfx_live_` (canlı) veya `pdfx_test_` (test) önekiyle başlar. Anahtar yalnızca oluşturulduğu yanıtta düz metin olarak döner; veritabanında SHA-256 özeti saklanır, kaybederseniz kurtarılamaz, yeni anahtar üretmeniz gerekir.

Bazı uçlar kimlik doğrulama gerektirmez: dosya yükleme ve iş oluşturma misafir olarak da yapılabilir (daha düşük hız sınırıyla). İmza ve form bağlantısı uçları ise bağlantıyı bilen herkese açıktır — yetkiyi bağlantının kendisi taşır.

Kimlikli istekbash

curl https://pdfmove.com/api/v1/jobs \
  -H "Authorization: Bearer pdfx_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"toolSlug":"merge-pdf","inputFileKey":"uploads/guest/abc.json"}'

Hızlı başlangıç: uçtan uca dönüştürme

Aşağıdaki akış her araç için aynıdır. Dikkat edilecek nokta: `POST /jobs` ucuna gönderdiğiniz `inputFileKey`, ham dosyanın değil MANİFEST dosyasının anahtarıdır. Manifest, aracın hangi ayarlarla çalışacağını ve hangi dosyayı işleyeceğini tanımlayan bir JSON'dur ve o da aynı yolla yüklenir.

PDF birleştirme (4 adım)bash

# 1) Dosya için imzalı yükleme adresi al
curl -X POST https://pdfmove.com/api/v1/uploads/presigned-url \
  -H "Content-Type: application/json" \
  -d '{"fileExtension":"pdf","contentLength":184320}'
# → {"fileKey":"uploads/guest/9f2....pdf","uploadUrl":"https://...","maxBytes":536870912}

# 2) Dosyayı doğrudan o adrese PUT et (gövde = ham dosya)
curl -X PUT "<uploadUrl>" --data-binary @belge.pdf

# 3) Manifest JSON'unu aynı yolla yükle, sonra işi oluştur
curl -X POST https://pdfmove.com/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{"toolSlug":"merge-pdf","inputFileKey":"<manifest fileKey>"}'
# → {"jobId":"clx...","status":"QUEUED"}

# 4) Durumu sorgula (1-2 saniyede bir yeterli)
curl https://pdfmove.com/api/v1/jobs/clx...
# → {"jobId":"clx...","status":"COMPLETED","downloadUrl":"https://...","progress":null,"retryable":false}

Dosya yükleme

POST/uploads/presigned-urlMisafir kullanılabilir

Doğrudan depolamaya yükleme için imzalı bir PUT adresi üretir.

Alan	Tip	Zorunlu	Açıklama
`fileExtension`	string	evet	Noktasız uzantı (`pdf`, `docx`, `mp4`). 1-10 harf/rakam.
`contentLength`	number	evet	Dosyanın tam bayt boyutu. İmzaya gömülür — PUT ettiğiniz gövde bu boyutla birebir aynı olmalı, aksi halde depolama isteği reddeder.

Yanıtjson

{
  "fileKey": "uploads/guest/9f2e1c4a-....pdf",
  "uploadUrl": "https://storage.pdfmove.com/...",
  "maxBytes": 536870912
}

Hata kodu	HTTP	Ne zaman
`INVALID_BODY`	400	Uzantı biçimi hatalı veya boyut sınırı aşıldı.
`RATE_LIMITED`	429	Saatlik yükleme sınırı doldu. `Retry-After` başlığına bakın.

Dosya adı sizden alınmaz; anahtar sunucuda üretilir. Yükleme adresi 300 saniye geçerlidir.

İşler

Durum	Anlamı
`QUEUED`	İş kuyrukta, henüz işlenmeye başlanmadı.
`PROCESSING`	İşleniyor. Bu durumdayken `progress` alanı dolu gelir.
`COMPLETED`	Tamamlandı. `downloadUrl` bu durumda üretilir.
`FAILED`	Başarısız. `errorMessage` sebebi açıklar.
`DEAD_LETTER`	Tekrarlanan denemeler sonrası kalıcı hata. `retryable: true` döner.

POST/jobsMisafir kullanılabilir

Bir aracı çalıştırmak üzere iş oluşturur.

Alan	Tip	Zorunlu	Açıklama
`toolSlug`	string	evet	Araç kimliği (`merge-pdf`, `pdf-to-word`, `jpg-to-png` …). Format çifti kimlikleri kabul edilir ve arka planda ilgili işleyiciye eşlenir.
`inputFileKey`	string	evet	Yüklenen MANİFEST dosyasının anahtarı (bkz. Hızlı başlangıç).

Yanıtjson

{
  "jobId": "clx8f2e1c4a0000",
  "status": "QUEUED"
}

Hata kodu	HTTP	Ne zaman
`INVALID_BODY`	400	Zorunlu alan eksik veya tip hatalı.
`UNKNOWN_TOOL`	404	`toolSlug` tanınmıyor.
`TOOL_UNAVAILABLE`	503	Araç geçici olarak kapalı (ör. gerekli altyapı bu sunucuda etkin değil).
`INSUFFICIENT_CREDITS`	402	Kimlikli kullanıcının kredisi yetersiz.
`RATE_LIMITED`	429	Saatlik iş oluşturma sınırı doldu.

İşler oluşturulduktan 2 saat sonra otomatik olarak silinir; girdi ve çıktı dosyaları da bu sırada temizlenir. Sonucu bu süre içinde indirin.

GET/jobs/{jobId}Misafir kullanılabilir

İşin durumunu ve hazırsa indirme adresini döner.

Yanıtjson

{
  "jobId": "clx8f2e1c4a0000",
  "status": "COMPLETED",
  "errorMessage": null,
  "downloadUrl": "https://storage.pdfmove.com/...",
  "progress": null,
  "retryable": false
}

Hata kodu	HTTP	Ne zaman
`NOT_FOUND`	404	İş yok ya da size ait değil.

Misafir olarak oluşturulan işler, kimliği bilen herkes tarafından sorgulanabilir. Kimlikli kullanıcıya ait işler yalnızca sahibine döner. `downloadUrl` 300 saniye geçerlidir; süresi dolarsa aynı ucu tekrar çağırın.

API anahtarları

POST/api-keysKimlik zorunlu

Yeni bir API anahtarı üretir.

Alan	Tip	Zorunlu	Açıklama
`name`	string	evet	Anahtarı tanımlayan ad (1-100 karakter).
`isTestKey`	boolean	hayır	`true` ise `pdfx_test_` önekli anahtar üretir. Varsayılan `false`.

Yanıtjson

{
  "id": "clx...",
  "key": "pdfx_live_3f9a...",
  "keyPrefix": "pdfx_live_3f9a",
  "name": "Üretim sunucusu",
  "isTestKey": false,
  "createdAt": "2026-08-17T10:00:00.000Z"
}

Hata kodu	HTTP	Ne zaman
`UNAUTHENTICATED`	401	Oturum yok.
`FORBIDDEN`	403	İstek bir API anahtarıyla yapılmış. Yeni anahtar yalnızca panelden/oturumla üretilebilir.
`INVALID_BODY`	400	Ad boş veya çok uzun.

`key` alanı SADECE bu yanıtta döner. Kaydedin — tekrar gösterilemez.

GET/api-keysKimlik zorunlu

Anahtarlarınızı listeler (düz metin anahtar dönmez).

Yanıtjson

{
  "apiKeys": [
    {
      "id": "clx...",
      "name": "Üretim sunucusu",
      "keyPrefix": "pdfx_live_3f9a",
      "isTestKey": false,
      "lastUsedAt": "2026-08-17T09:41:00.000Z",
      "createdAt": "2026-08-01T12:00:00.000Z",
      "revokedAt": null
    }
  ]
}

Hata kodu	HTTP	Ne zaman
`UNAUTHENTICATED`	401	Oturum veya anahtar yok.

DELETE/api-keys/{id}Kimlik zorunlu

Anahtarı iptal eder.

Yanıtjson

{ "revoked": true }

Hata kodu	HTTP	Ne zaman
`UNAUTHENTICATED`	401	Oturum veya anahtar yok.
`NOT_FOUND`	404	Anahtar yok ya da size ait değil.

İptal geri alınamaz; kayıt silinmez, yalnızca kullanılamaz hale gelir.

İş akışları

Birden fazla aracı sırayla çalıştırmak için iş akışı tanımlayabilirsiniz — ör. önce sıkıştır, sonra filigran ekle, sonra şifrele. Bir akış en fazla 10 adım içerir.

POST/workflowsKimlik zorunlu

İş akışı tanımlar.

Alan	Tip	Zorunlu	Açıklama
`name`	string	evet	Akış adı (1-100 karakter).
`steps`	array	evet	1-10 adım. Her adım `{ toolSlug, manifestTemplate }` içerir. `manifestTemplate` o aracın ayar nesnesidir.

Yanıtjson

{
  "id": "clx...",
  "name": "Sıkıştır ve şifrele",
  "steps": [
    { "toolSlug": "compress-pdf", "manifestTemplate": { "quality": "medium" } },
    { "toolSlug": "protect-pdf", "manifestTemplate": { "password": "..." } }
  ]
}

Hata kodu	HTTP	Ne zaman
`UNAUTHENTICATED`	401	Oturum veya anahtar yok.
`INVALID_BODY`	400	Adım yok, 10'dan fazla adım var, ya da alan eksik.
`UNKNOWN_TOOL`	404	Adımlardan birinin `toolSlug` değeri tanınmıyor.

İş akışı adımlarında format-çifti kimlikleri (`pdf-to-word` gibi) `POST /jobs`'taki gibi eşlenmez — burada işleyici kimliğini doğrudan verin.

POST/workflows/{id}/runsKimlik zorunlu

Tanımlı akışı bir girdi dosyasıyla çalıştırır.

Alan	Tip	Zorunlu	Açıklama
`inputFileKey`	string	evet	Yüklenmiş girdi dosyasının anahtarı.

Yanıtjson

{ "runId": "clx...", "status": "QUEUED" }

Hata kodu	HTTP	Ne zaman
`UNAUTHENTICATED`	401	Oturum veya anahtar yok.
`NOT_FOUND`	404	Akış yok ya da size ait değil.
`INVALID_BODY`	400	`inputFileKey` eksik.
`INSUFFICIENT_CREDITS`	402	Kredi yetersiz.

GET/workflows/runs/{runId}Kimlik zorunlu

Çalıştırmanın durumunu ve adım sonuçlarını döner.

Yanıtjson

{
  "runId": "clx...",
  "status": "COMPLETED",
  "stepResults": [
    { "toolSlug": "compress-pdf", "status": "COMPLETED", "outputFileKey": "outputs/..." },
    { "toolSlug": "protect-pdf", "status": "COMPLETED", "outputFileKey": "outputs/..." }
  ],
  "errorMessage": null,
  "downloadUrl": "https://storage.pdfmove.com/..."
}

Hata kodu	HTTP	Ne zaman
`NOT_FOUND`	404	Çalıştırma yok ya da size ait değil.

Hata biçimi

Tüm hatalar aynı zarfla döner. `retryable` alanı isteğin aynen tekrarlanmasının anlamlı olup olmadığını söyler — `false` ise isteği düzeltmeden tekrar göndermeyin.

Hata gövdesijson

{
  "error": {
    "code": "TOOL_UNAVAILABLE",
    "message": "Bu araç şu anda kullanılamıyor.",
    "retryable": false
  }
}

Hız sınırları

Sınırlar sabit pencerelidir ve kimlikli isteklerde kullanıcı, misafir isteklerde IP adresi başına uygulanır. Sınır aşıldığında `429` ve `Retry-After` başlığı döner. Sınır altyapısı geçici olarak erişilemezse istekler engellenmez — sınırlama açık tarafta hata verir.

Kapsam	Sınır	Pencere
İş oluşturma (misafir)	20	saat
İş oluşturma (kimlikli)	200	saat
Yükleme (misafir)	40	saat
Yükleme (kimlikli)	400	saat