Skenování přes API

Pomocí volání REST API vytvoříte z PDF kopii se vzhledem skenu. Hodí se pro automatizované zpracování i propojení s vlastní aplikací. Vytvořte úlohu, nahrajte PDF a pak se dotazujte na stav nebo počkejte na webhook. Stačí prostředí, ze kterého lze odeslat HTTP požadavek. Nastavit můžete barevný režim, rozlišení, otočení, rozmazání, šum, jas, kontrast i okraje.

Jak volání probíhá

  1. Vytvořte úlohu

    POST /v1/scan-jobs

    Odešlete konfiguraci a případně webhookUrl. Zpět dostanete jobID a předem podepsanou adresu uploadURL.

  2. Nahrajte PDF

    PUT {uploadURL}

    Pošlete soubor metodou PUT přímo na podepsanou adresu S3 z předchozího kroku. Token není potřeba.

  3. Stáhněte výsledek

    GET /v1/scan-jobs/{jobID}

    Dotazujte se na stav nebo počkejte na webhook. Jakmile je úloha dokončena, stáhněte soubor z downloadURL.

K čemu se API hodí

Hromadné zpracování na serveru

Smlouvy, faktury a zprávy vytvořené na serveru rovnou získají vzhled skenu. Nikdo je nemusí po jednom zpracovávat na webu.

Propojení s vaším systémem

Přidejte do CRM, ERP nebo systému pro správu požadavků akci „Exportovat jako sken“, která zavolá API.

Automatizované postupy

CI, n8n, Zapier a podobné nástroje spustí úlohu při určité události. Webhook po jejím dokončení naváže dalším krokem.

Velké fronty souborů

Úlohy se zpracovávají asynchronně. Po vytvoření běží každá samostatně a průběh můžete sledovat pomocí status a createdAfter.

Jazyky a prostředí

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLPříkazový řádek / CI
DalšíLibovolný HTTP klient

API používá běžné HTTP a JSON. Lze jej volat z jakéhokoli jazyka nebo automatizační platformy, která umí odeslat požadavek.

Ukázky kódu

API Bearer Token

Token patří k vašemu účtu a můžete jej kdykoli vygenerovat znovu. Skenování přes API vyžaduje účet Pro: bez platného tokenu API vrací 401, bez oprávnění Pro vrací 403.

Vyzkoušet API

Nastavte parametry a sledujte, jak se mění tělo požadavku. Pak spusťte tři volání API.

Parametry skenování

Zkušební volání používá váš token a vyžaduje účet Pro. Parametry a tělo požadavku si můžete prohlédnout i bez něj.

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

Informace o úloze

ukázka
{
  "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-…"
}

Přehled API

MetodaCestaPopis
POST/v1/scan-jobsVytvoří úlohu skenování. Odešlete config a případně webhookUrl. Zpět dostanete objekt úlohy se stavem created a předem podepsanou adresou uploadURL.
PUT{uploadURL}Podepsaná adresa S3 z předchozího kroku, nikoli adresa na api.lookscanned.ioNahraje zdrojové PDF s hlavičkami Content-Type: application/pdf a Content-Length. Adresa obsahuje vlastní podpis, proto nepřidávejte hlavičku Authorization.
GET/v1/scan-jobs/{jobID}Vrátí jednu úlohu pro kontrolu jejího stavu. Ve stavu created obsahuje uploadURL, po dokončení ve stavu completed obsahuje downloadURL.
GET/v1/scan-jobsVrátí vaše úlohy filtrované podle jobID, status nebo createdAfter.
Stavcreatedprocessingcompletedfailed
  • 401 chybí platný token
  • 403 účet nemá Pro
  • 404 úloha neexistuje

Tělo požadavku

PoleTypVýchozí hodnotaPopis
webhookUrlstring · —Po dokončení úlohy se zavolá jednou, takže se nemusíte dotazovat na stav.
config.colorspace'gray' | 'sRGB' · graygrayBarevný prostor výstupního obrázku; gray znamená sken v odstínech šedi.
config.resolutionnumber · 7272Rozlišení výstupního obrázku v DPI.
config.rotatenumber · —Otočení celého dokumentu ve stupních.
config.rotate_varnumber · —Rozsah náhodného natočení jednotlivých stránek ve stupních. Napodobuje křivě položený papír.
config.blurnumber · 00Míra rozmazání.
config.noisenumber · 00Míra šumu.
config.brightnessnumber · 11Jas; hodnota 1 jej nemění.
config.contrastnumber · 11Kontrast; hodnota 1 jej nemění.
config.borderboolean · falsefalseUrčuje, zda se ke stránce přidá okraj skenu.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegFormát obrázků, do kterých se stránky vykreslí.

Všechna pole jsou volitelná. Výchozí nastavení v části „Vyzkoušet API“ — rozlišení 150, otočení 1, jas a kontrast 1,3 — odpovídají doporučení webové aplikace, nikoli výchozím hodnotám API.

Důležitá pole objektu úlohy

status
created / processing / completed / failed — podle stavu jsou dostupné následující dvě adresy.
uploadURL
Pouze ve stavu created. Podepsaná adresa pro nahrání souboru s omezenou platností.
downloadURL
Pouze ve stavu completed. Podepsaná adresa pro stažení souboru s omezenou platností.
inputUploadedAt / completedAt
Čas dokončení nahrávání a čas dokončení úlohy. Jejich rozdíl udává dobu zpracování.

Časté dotazy

Potřebuji pro skenování přes API Pro?

Ano. Bez platného tokenu API vrací 401, účtu bez oprávnění Pro vrací 403. Po přechodu na Pro se přihlaste a token najdete na této stránce.

Jak poznám, že je úloha hotová?

Můžete opakovaně volat GET /v1/scan-jobs/{jobID}, nebo při vytváření úlohy zadat webhookUrl. Služba tuto adresu po dokončení jednou zavolá.

Je výsledek stejný jako při skenování na webu?

Ano. Obě varianty používají stejné zpracování efektů. Barevný prostor, rozlišení, otočení, rozmazání, šum, jas, kontrast a okraj v config odpovídají nastavením na webu, jen mají jiné názvy. Stejné parametry dávají stejný výsledek. Liší se pouze místo zpracování: na webu probíhá místně, přes API vzdáleně.

Mohu si adresy pro nahrání a stažení uložit a používat je znovu?

Raději ne. Podepsané adresy uploadURL a downloadURL mají omezenou platnost. Po jejím vypršení znovu načtěte úlohu a získáte nové adresy.

Jak dlouho zpracování trvá?

Záleží na počtu stránek a rozlišení. Několik stránek bývá hotových za pár sekund, delší dokumenty a vyšší rozlišení trvají déle. Skutečnou dobu zpracování zjistíte z rozdílu inputUploadedAt a completedAt.

Co když úloha selže?

Stav se změní na failed. Obvyklou příčinou je neplatný soubor PDF, omezení kvůli šifrování nebo přerušené nahrávání. Ověřte, že soubor lze otevřít, a vytvořte novou úlohu.

Mohu dohledat předchozí úlohy?

Ano. GET /v1/scan-jobs vrací vaše úlohy a umožňuje filtrovat podle jobID, status a createdAfter. Můžete tak zkontrolovat zpracování nebo znovu stáhnout výsledek.