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
İş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.
PDF'i yükleyin
PUT {uploadURL}
Dosyayı doğrudan önceki adımdaki önceden imzalanmış S3 adresine PUT edin — belirteç gerekmez.
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
API sıradan HTTP ve JSON kullanır; istek gönderebilen her dil ve her otomasyon platformu onu çağırabilir.
Kod örnekleri
Add Look Scanned API Scan to this project, so I can turn a PDF into a
realistic scanned copy from code.
API docs: https://lookscanned.io/en/scan/api
Write one function that:
1. POST https://api.lookscanned.io/v1/scan-jobs
Header: Authorization: Bearer $LOOKSCANNED_API_TOKEN
Body: {"config": {"colorspace": "gray", "resolution": 150, "rotate": 1}}
It returns jobID and a presigned uploadURL.
2. PUT the PDF bytes to uploadURL with Content-Type: application/pdf.
Send no Authorization header — that URL is already signed.
3. Poll GET /v1/scan-jobs/{jobID} until status is "completed" (or "failed"),
then return downloadURL.
Read the token from the LOOKSCANNED_API_TOKEN environment variable. Use the
language and HTTP client this project already uses, and add one test.interface ScanConfig {
rotate?: number // degrees to rotate the document
rotate_var?: number // degrees to rotate the document randomly
colorspace?: 'gray' | 'sRGB' // the colorspace of the output image
blur?: number // the amount of blur to apply to the image
noise?: number // the amount of noise to apply to the image
border?: boolean // whether to add a border to the image
brightness?: number // the brightness of the image. 1 is no change
contrast?: number // the contrast of the image. 1 is no change
resolution?: number // the resolution of the image in DPI
output_format?: 'image/png' | 'image/jpeg' // the format of the output image
}
interface ScanOptions {
config: ScanConfig
webhookUrl?: string // webhook URL to notify when job is completed
}
interface ScanResponse {
jobID: string // UUID of the scan job
userID: string // UUID of the user who created the job
createdAt: number // timestamp of job creation
status: 'pending' | 'processing' | 'completed' | 'failed'
config: ScanConfig
inputUploadedAt?: number // timestamp when input file was uploaded
completedAt?: number // timestamp when job was completed
webhookUrl?: string // webhook URL for notifications
uploadURL?: string // S3 presigned URL for file upload
downloadURL?: string // S3 presigned URL for file download
}
async function apiScan(pdfBlob: Blob, scanOptions: ScanOptions, token: string): Promise<ScanResponse> {
const response = await fetch('https://api.lookscanned.io/v1/scan-jobs', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
},
body: JSON.stringify(scanOptions)
})
const result: ScanResponse = await response.json()
// PUT PDF Blob to upload URL
const uploadURL = result.uploadURL
await fetch(uploadURL, {
method: 'PUT',
headers: {
'Content-Type': 'application/pdf',
'Content-Length': pdfBlob.size.toString()
},
body: pdfBlob
})
// get scan job status
const jobStatusResponse = await fetch(`https://api.lookscanned.io/v1/scan-jobs/${result.jobID}`, {
headers: {
'Authorization': `Bearer ${token}`
}
})
return await jobStatusResponse.json()
}import requests
def api_scan(pdf_file, scan_options, token):
# Create scan job
response = requests.post(
'https://api.lookscanned.io/v1/scan-jobs',
headers={'Authorization': f'Bearer {token}'},
json=scan_options
)
result = response.json()
# Upload PDF to presigned URL
upload_url = result['uploadURL']
requests.put(
upload_url,
headers={
'Content-Type': 'application/pdf',
'Content-Length': str(len(pdf_file))
},
data=pdf_file
)
# Get scan job status
job_status = requests.get(
f'https://api.lookscanned.io/v1/scan-jobs/{result["jobID"]}',
headers={'Authorization': f'Bearer {token}'}
)
return job_status.json()
# Example usage
if __name__ == "__main__":
with open('document.pdf', 'rb') as f:
pdf_content = f.read()
options = {
'config': {
# Optional parameters:
# 'rotate': 0, # degrees to rotate the document
# 'colorspace': 'gray', # gray or sRGB
# 'resolution': 300, # DPI
# 'rotate_var': 0, # random rotation variance in degrees
# 'blur': 0, # amount of blur
# 'noise': 0, # amount of noise
# 'border': False, # whether to add border
# 'brightness': 1, # 1 is no change
# 'contrast': 1, # 1 is no change
# 'output_format': 'image/png' # image/png or image/jpeg
},
'webhookUrl': 'https://example.com/webhook'
}
result = api_scan(pdf_content, options, 'your-api-token')
print(f"Scan job created with ID: {result['jobID']}")# Set your API token and PDF file as environment variables
export LOOKSCANNED_API_TOKEN='your_api_token_here'
# Create a new scan job
curl -X POST 'https://api.lookscanned.io/v1/scan-jobs' \
-H "Authorization: Bearer ${LOOKSCANNED_API_TOKEN}" \
-H 'Content-Type: application/json' \
-d '{
"config": {
"rotate": 0,
"rotate_var": 1,
"colorspace": "gray",
"blur": 0.2,
"noise": 0.1,
"border": true,
"brightness": 1.0,
"contrast": 1.0,
"resolution": 300,
"output_format": "image/jpeg"
},
"webhookUrl": "https://your-domain.com/webhook"
}'
# Response will include uploadURL and jobID
# {
# "jobID": "550e8400-e29b-41d4-a716-446655440000",
# "userID": "446655440000-e29b-41d4-a716-550e8400",
# "createdAt": 1616161616,
# "status": "created",
# "uploadURL": "...",
# "config": { ... }
# }
# Upload PDF file to the presigned URL
curl -X PUT 'PRESIGNED_UPLOAD_URL' \
-H 'Content-Type: application/pdf' \
-H "Content-Length: PDF_FILE_SIZE" \
--data-binary "@path/to/your/file.pdf"
# Check job status
curl 'https://api.lookscanned.io/v1/scan-jobs/JOB_ID' \
-H "Authorization: Bearer ${LOOKSCANNED_API_TOKEN}"
# Response will include status and downloadURL when completed
# {
# "jobID": "550e8400-e29b-41d4-a716-446655440000",
# "status": "completed",
# "downloadURL": "...",
# ...
# }
# Download the PDF
curl -o scanned.pdf 'DOWNLOAD_URL'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.
API taraması bir Pro özelliğidir
Bu hesap henüz Pro değil; yükselttiğinizde belirteç burada görünür. Belirteç ya da rol yoksa API 401 / 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.
{
"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öntem | Yol | Açıklama |
|---|---|---|
| POST | /v1/scan-jobs | Bir 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 adresi | Kaynak 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-jobs | Kendi işlerinizi listeler; jobID, status ve createdAfter ile süzülebilir. |
401geçerli belirteç yok403hesap Pro değil404iş bulunamadı
İstek gövdesi
| Alan | Tür | Varsayılan | Açıklama |
|---|---|---|---|
| webhookUrl | string · — | — | İş bittiğinde bir kez çağrılır, böylece durumu yoklamanız gerekmez. |
| config.colorspace | 'gray' | 'sRGB' · gray | gray | Çıktı görüntüsünün renk uzayı; gray siyah beyaz bir taranmış kopya verir. |
| config.resolution | number · 72 | 72 | Çıktı görüntüsünün çözünürlüğü, DPI cinsinden. |
| config.rotate | number · — | — | Belgenin tamamının döndürme açısı, derece cinsinden. |
| config.rotate_var | number · — | — | Sayfa başına rastgele döndürmenin aralığı, derece cinsinden — kâğıdın eğri konmuş görüntüsü. |
| config.blur | number · 0 | 0 | Bulanıklık miktarı. |
| config.noise | number · 0 | 0 | Gürültü miktarı. |
| config.brightness | number · 1 | 1 | Parlaklık; 1 hiçbir şeyi değiştirmez. |
| config.contrast | number · 1 | 1 | Karşıtlık; 1 hiçbir şeyi değiştirmez. |
| config.border | boolean · false | false | Sayfaya tarama kenarlığı eklenip eklenmeyeceği. |
| config.output_format | 'image/png' | 'image/jpeg' · image/jpeg | image/jpeg | Sayfaları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.