API taraması

API taraması, tek bir REST çağrısıyla bir PDF'i gerçekçi bir taranmış kopyaya çevirir; otomatik iş akışlarına ve uygulama entegrasyonlarına uygundur. İşi oluşturun, PDF'i yükleyin, sonra durumu yoklayın ya da webhook'u bekleyin: HTTP isteği gönderebilen her ortamdan ve her dilden üç adım. Renk uzayı, çözünürlük, döndürme, bulanıklık, gürültü, parlaklık, karşıtlık ve kenarlık ayarlanabilir.

Bir çağrı nasıl işler

  1. İşi oluşturun

    POST /v1/scan-jobs

    config'inizi ve isterseniz bir webhookUrl gönderin; karşılığında bir jobID ve önceden imzalanmış bir uploadURL alırsınız.

  2. PDF'i yükleyin

    PUT {uploadURL}

    Dosyayı doğrudan önceki adımdaki önceden imzalanmış S3 adresine PUT edin — belirteç gerekmez.

  3. Taranmış kopyayı alın

    GET /v1/scan-jobs/{jobID}

    Durumu yoklayın ya da webhook'u bekleyin; iş completed olduğunda downloadURL üzerinden indirin.

Nerelere uyar

Sunucuda toplu üretim

Sunucuda üretilen sözleşmeler, faturalar ve raporlar doğrudan tarama efektinden geçer; kimsenin aynı işi web sayfasında elle tekrarlaması gerekmez.

Mevcut bir sistemin içinde

CRM, ERP ya da talep sistemine bir “taranmış kopya dışa aktar” eylemi ekleyin ve API'yi çağırmasını sağlayın.

Otomasyon zincirleri

CI, n8n, Zapier ve benzerleri bir olayla iş başlatır; bitince webhook sırayı bir sonraki adıma devreder.

Büyük dosya kuyrukları

İşler eşzamansızdır: oluşturulduktan sonra her biri kendi başına işlenir, ilerleme ise status ve createdAfter ile izlenebilir.

Diller ve ortamlar

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLKomut satırı / CI
Daha fazlaHerhangi bir HTTP istemcisi

API sıradan HTTP ve JSON kullanır; istek gönderebilen her dil ve her otomasyon platformu onu çağırabilir.

Kod örnekleri

API Bearer Token

Belirteç hesabınıza aittir ve istediğiniz zaman yeniden oluşturulabilir. API taraması bir Pro hesabı gerektirir: geçerli belirteç yoksa API 401, Pro rolü yoksa 403 döndürür.

Deneyin

Parametreleri ayarlayın, istek gövdesinin nasıl değiştiğini görün, sonra üç çağrıyı API’ye gönderin.

Tarama parametreleri

Deneme çalıştırması API’yi sizin belirtecinizle çağırır ve Pro hesabı gerektirir; parametrelere ve istek gövdesine dilediğiniz gibi bakabilirsiniz.

POST/v1/scan-jobs
{
  "config": {
    "rotate": 1,
    "rotate_var": 0.5,
    "colorspace": "gray",
    "blur": 0,
    "noise": 0,
    "border": false,
    "brightness": 1.3,
    "contrast": 1.3,
    "resolution": 150,
    "output_format": "image/jpeg"
  }
}

Tarama İşi Bilgisi

örnek
{
  "jobID": "3f9c1e64-0000-4000-8000-00000000a71b",
  "userID": "8f21c4b0-0000-4000-8000-000000004a17",
  "createdAt": 1724409600,
  "status": "completed",
  "inputUploadedAt": 1724409601,
  "completedAt": 1724409602,
  "numPages": 6,
  "downloadURL": "https://…/output/3f9c.pdf?X-Amz-…"
}

API başvurusu

YöntemYolAçıklama
POST/v1/scan-jobsBir tarama işi oluşturur. config ve gerekiyorsa webhookUrl gönderin; karşılığında durumu created olan iş nesnesini ve önceden imzalanmış bir uploadURL alırsınız.
PUT{uploadURL}Önceki adımdan gelen, api.lookscanned.io üzerinde bulunmayan önceden imzalanmış S3 adresiKaynak PDF'i Content-Type: application/pdf ve Content-Length ile yükler. Adres kendi imzasını taşıdığı için Authorization başlığı eklemeyin.
GET/v1/scan-jobs/{jobID}Tek bir işi okur; yoklama içindir. created durumunda uploadURL, completed durumunda downloadURL içerir.
GET/v1/scan-jobsKendi işlerinizi listeler; jobID, status ve createdAfter ile süzülebilir.
Durumcreatedprocessingcompletedfailed
  • 401 geçerli belirteç yok
  • 403 hesap Pro değil
  • 404 iş bulunamadı

İstek gövdesi

AlanTürVarsayılanAçıklama
webhookUrlstring · —İş bittiğinde bir kez çağrılır, böylece durumu yoklamanız gerekmez.
config.colorspace'gray' | 'sRGB' · graygrayÇıktı görüntüsünün renk uzayı; gray siyah beyaz bir taranmış kopya verir.
config.resolutionnumber · 7272Çıktı görüntüsünün çözünürlüğü, DPI cinsinden.
config.rotatenumber · —Belgenin tamamının döndürme açısı, derece cinsinden.
config.rotate_varnumber · —Sayfa başına rastgele döndürmenin aralığı, derece cinsinden — kâğıdın eğri konmuş görüntüsü.
config.blurnumber · 00Bulanıklık miktarı.
config.noisenumber · 00Gürültü miktarı.
config.brightnessnumber · 11Parlaklık; 1 hiçbir şeyi değiştirmez.
config.contrastnumber · 11Karşıtlık; 1 hiçbir şeyi değiştirmez.
config.borderboolean · falsefalseSayfaya tarama kenarlığı eklenip eklenmeyeceği.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegSayfaların görüntüye dönüştürüldüğü biçim.

Her alan atlanabilir. “Deneyin” bölümünün başlangıç değerleri — çözünürlük 150, döndürme 1, parlaklık ve karşıtlık 1,3 — web uygulamasının önerdiği bileşimdir, API'nin varsayılanları değil.

İş nesnesinde dikkat edilecek alanlar

status
created / processing / completed / failed — aşağıdaki iki adresin bulunup bulunmayacağını belirler.
uploadURL
Yalnızca created iken verilir. Süresi dolan, önceden imzalanmış bir yükleme adresi.
downloadURL
Yalnızca completed olduğunda verilir. Süresi dolan, önceden imzalanmış bir indirme adresi.
inputUploadedAt / completedAt
Kaynağın yüklenmesinin bittiği an ile işin bittiği an; aradaki fark işlem süresidir.

Sıkça sorulan sorular

API taraması Pro gerektirir mi?

Evet. Geçerli belirteç yoksa API 401, Pro rolü olmayan bir hesap ise 403 alır. Yükseltip oturum açtığınızda belirteç bu sayfada görünür.

Bir işin bittiğini nasıl anlarım?

İki yolla: GET /v1/scan-jobs/{jobID} adresini yoklayın ya da işi oluştururken bir webhookUrl geçirip hizmetin bir kez geri aramasını sağlayın.

Sonuç web sayfasındaki taramayla aynı mı?

Aynı. İkisi de tarama efektinin aynı uygulamasını kullanır; config içindeki renk uzayı, çözünürlük, döndürme, bulanıklık, gürültü, parlaklık, karşıtlık ve kenarlık web sayfasındaki aynı adlı seçeneklere karşılık gelir, aynı parametreler aynı çıktıyı verir. Yalnızca işin yapıldığı yer değişir: sayfada yerel, API'de uzak hizmet.

Yükleme ve indirme adreslerini saklayıp yeniden kullanabilir miyim?

Önerilmez. uploadURL ve downloadURL süreli, önceden imzalanmış adreslerdir; süreleri dolduğunda yenilerini almak için işi yeniden okumanız gerekir.

Bir iş ne kadar sürer?

Sayfa sayısına ve çözünürlüğe bağlıdır. Birkaç sayfalık belgeler genellikle saniyeler içinde biter; çözünürlük yükseldikçe ve sayfa arttıkça süre uzar. inputUploadedAt ile completedAt arasındaki fark gerçek süreyi verir.

Bir iş başarısız olursa ne yapmalıyım?

Durum failed olur. Sık görülen nedenler dosyanın geçerli bir PDF olmaması, şifreleme kısıtlamaları ya da yüklemenin yarıda kesilmesidir. Dosyanın açıldığını doğrulayıp yeni bir iş oluşturun.

Geçmiş işleri sorgulayabilir miyim?

Evet. GET /v1/scan-jobs kendi işlerinizi listeler ve jobID, status ile createdAfter üzerinden süzülebilir; mutabakat ya da yeniden indirme için yeterlidir.