API-szkennelés

Az API-szkenneléssel REST-híváson keresztül készíthetsz élethű, szkennelt másolatot egy PDF-ből, automatizált folyamatokhoz és alkalmazásintegrációkhoz. Hozz létre feladatot, töltsd fel a PDF-et, majd kérdezd le az állapotát, vagy várd meg a webhook értesítését. Ez a három lépés bármilyen HTTP-kérést küldeni képes környezetből vagy nyelvből elvégezhető. A színteret, a felbontást, az elforgatást, az elmosást, a zajt, a fényerőt, a kontrasztot és a szegélyt is beállíthatod.

A hívás menete

  1. Hozd létre a feladatot

    POST /v1/scan-jobs

    Küldd el a config mezőt és szükség esetén a webhookUrl értékét. A válaszban egy jobID azonosítót és egy előre aláírt uploadURL címet kapsz.

  2. Töltsd fel a PDF-et

    PUT {uploadURL}

    Küldd a fájlt PUT-kéréssel közvetlenül az előző lépésben kapott, előre aláírt S3-címre. Ehhez nem kell token.

  3. Töltsd le a szkennelt másolatot

    GET /v1/scan-jobs/{jobID}

    Kérdezd le rendszeresen az állapotot, vagy várd meg a webhook értesítését. Ha a feladat állapota completed, a downloadURL címről letöltheted az eredményt.

Mire használhatod?

Szerveroldali tömeges feldolgozás

A szerveren készülő szerződések, számlák és jelentések automatikusan megkapják a szkennelési hatást. Nem kell őket egyenként feldolgoznod a weboldalon.

Beépítés meglévő rendszerbe

Adj „Szkennelt másolat exportálása” műveletet egy CRM-, ERP- vagy hibajegykezelő rendszerhez, és hívd meg belőle az API-t.

Automatizált munkafolyamatok

A CI, az n8n, a Zapier és hasonló eszközök egy esemény hatására elindítják a feladatot. Amint elkészült, a webhook elindíthatja a következő lépést.

Sok fájl feldolgozása

A feladatok aszinkron módon, egymástól függetlenül készülnek el. A haladást a status és a createdAfter mező alapján követheted.

Nyelvek és környezetek

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLParancssor / CI
TovábbiakBármilyen HTTP-kliens

Az API HTTP-t és JSON-t használ, így bármilyen kérést küldeni képes programozási nyelvből vagy automatizálási platformról meghívhatod.

Kódpéldák

API Bearer Token

A token a fiókodhoz tartozik, és bármikor újat hozhatsz létre. Az API-szkenneléshez Pro-fiók kell: érvényes token nélkül az API 401-es, Pro-jogosultság nélkül 403-as választ ad.

Kipróbálás

Állítsd be a paramétereket, és figyeld, hogyan változik a kérés törzse. Ezután futtasd le a három API-hívást.

Szkennelési paraméterek

A próbafuttatás a saját tokeneddel hívja meg az API-t, ezért Pro-fiók szükséges hozzá. A paramétereket és a kérés törzsét ingyen is megnézheted.

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"
  }
}

Szkennelési feladat adatai

példa
{
  "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-dokumentáció

MetódusÚtvonalLeírás
POST/v1/scan-jobsSzkennelési feladat létrehozása. Küldd el a config mezőt és szükség esetén a webhookUrl értékét. A válaszban a feladat objektumát kapod created állapottal és egy előre aláírt uploadURL címmel.
PUT{uploadURL}Az előző lépésben kapott, előre aláírt S3-cím, nem az api.lookscanned.ioTöltsd fel a forrás-PDF-et Content-Type: application/pdf és Content-Length fejléccel. A cím már tartalmazza az aláírást, ezért ne adj hozzá Authorization fejlécet.
GET/v1/scan-jobs/{jobID}Egy feladat lekérdezése az állapot rendszeres ellenőrzéséhez. created állapotban uploadURL, completed állapotban downloadURL szerepel benne.
GET/v1/scan-jobsSaját feladatok listázása jobID, status vagy createdAfter szerinti szűréssel.
Állapotcreatedprocessingcompletedfailed
  • 401 nincs érvényes token
  • 403 a fiók nem Pro
  • 404 nincs ilyen feladat

Kérés törzse

MezőTípusAlapértékLeírás
webhookUrlstring · —A feladat befejezésekor egyszer hívja meg a szolgáltatás, így nem kell rendszeresen lekérdezned az állapotot.
config.colorspace'gray' | 'sRGB' · graygrayA kimeneti kép színtere; a gray szürkeárnyalatos eredményt ad.
config.resolutionnumber · 7272A kimeneti kép felbontása DPI-ben.
config.rotatenumber · —A teljes dokumentum elforgatása fokban.
config.rotate_varnumber · —Az oldalankénti véletlenszerű elforgatás tartománya fokban. A ferdén behelyezett papír hatását utánozza.
config.blurnumber · 00Az elmosás mértéke.
config.noisenumber · 00A zaj mértéke.
config.brightnessnumber · 11Fényerő; az 1 változatlanul hagyja.
config.contrastnumber · 11Kontraszt; az 1 változatlanul hagyja.
config.borderboolean · falsefalseKerüljön-e szkennelési szegély az oldalra.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegAz oldalak kimeneti képformátuma.

Minden mező elhagyható. A „Kipróbálás” kezdőértékei (150-es felbontás, 1-es elforgatás, 1.3-as fényerő és kontraszt) a webalkalmazás ajánlott beállításai, nem az API alapértékei.

A feladat objektumának fontosabb mezői

status
created / processing / completed / failed – ettől függ, hogy az alábbi két cím közül melyik érhető el.
uploadURL
Csak created állapotban. Előre aláírt feltöltési cím, amelynek lejár az érvényessége.
downloadURL
Csak completed állapotban. Előre aláírt letöltési cím, amelynek lejár az érvényessége.
inputUploadedAt / completedAt
A forrásfájl feltöltésének és a feladat befejezésének időpontja. A kettő különbsége a feldolgozási idő.

Gyakori kérdések

Kell Pro az API-szkenneléshez?

Igen. Érvényes token nélkül az API 401-es választ ad, Pro-jogosultság nélküli fiókkal pedig 403-ast. Válts Pro csomagra, és jelentkezz be: a tokened ezen az oldalon jelenik meg.

Honnan tudom, hogy elkészült egy feladat?

Két lehetőséged van: rendszeresen hívd meg a GET /v1/scan-jobs/{jobID} végpontot, vagy adj meg webhookUrl értéket a feladat létrehozásakor. Utóbbi esetben a szolgáltatás egyszer értesít a befejezésről.

Ugyanazt az eredményt kapom, mint a weboldalon?

Igen. Mindkettő ugyanazt a szkennelési eljárást használja. A config színtér-, felbontás-, elforgatás-, elmosás-, zaj-, fényerő-, kontraszt- és szegélybeállításai a weboldal lehetőségeinek felelnek meg, más néven. Azonos paraméterekkel azonos eredményt kapsz. A feldolgozás helye tér el: a weboldalon helyben, az API-val távolról történik.

Elmenthetem a feltöltési és letöltési címeket későbbi használatra?

Nem érdemes. Az uploadURL és a downloadURL előre aláírt, korlátozott ideig érvényes cím. Ha lejárnak, kérdezd le újra a feladatot, hogy friss címeket kapj.

Mennyi ideig tart egy feladat?

Az oldalszámtól és a felbontástól függ. Néhány oldal általában másodpercek alatt elkészül; nagyobb felbontás vagy hosszabb dokumentum esetén több idő kell. Az inputUploadedAt és a completedAt különbsége mutatja a tényleges feldolgozási időt.

Mi történik, ha sikertelen egy feladat?

Az állapota failed lesz. Ennek gyakori oka az érvénytelen PDF, a titkosítási korlátozás vagy a megszakadt feltöltés. Ellenőrizd, hogy megnyitható-e a fájl, majd hozz létre új feladatot.

Visszakereshetem a korábbi feladatokat?

Igen. A GET /v1/scan-jobs a saját feladataidat listázza, jobID, status és createdAfter szerinti szűréssel. Így ellenőrizheted az előzményeket vagy újra letöltheted az eredményt.