API-scan

De API-scan maakt met één REST-aanroep van een PDF een realistisch gescande kopie, wat past bij geautomatiseerde processen en app-integraties. Maak de taak aan, upload de PDF en poll de status of wacht op de webhook: drie stappen, vanuit elke omgeving of taal die een HTTP-verzoek kan versturen. Kleurruimte, resolutie, rotatie, vervaging, ruis, helderheid, contrast en rand zijn allemaal in te stellen.

Zo verloopt een aanroep

  1. De taak aanmaken

    POST /v1/scan-jobs

    Stuur je config en eventueel een webhookUrl; je krijgt een jobID en een vooraf ondertekende uploadURL terug.

  2. De PDF uploaden

    PUT {uploadURL}

    Doe een PUT van het bestand rechtstreeks naar het vooraf ondertekende S3-adres uit de vorige stap — zonder token.

  3. De gescande kopie ophalen

    GET /v1/scan-jobs/{jobID}

    Poll de status of wacht op de webhook; zodra de taak completed is, download je hem via downloadURL.

Waar het past

Bulkuitvoer vanuit de backend

Contracten, facturen en rapporten die op de server ontstaan gaan meteen door het scaneffect, zonder dat iemand dezelfde handeling op de webpagina overdoet.

In een bestaand systeem

Voeg aan een CRM, ERP of ticketsysteem een actie «gescande kopie exporteren» toe die de API aanroept.

Automatiseringsketens

CI, n8n, Zapier en dergelijke starten een taak bij een gebeurtenis, en de webhook geeft na afloop het stokje door aan de volgende stap.

Grote wachtrijen met bestanden

Taken zijn asynchroon: eenmaal aangemaakt wordt elke taak op zichzelf verwerkt, en de voortgang blijft opvraagbaar via status en createdAfter.

Talen en omgevingen

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLOpdrachtregel / CI
MeerElke HTTP-client

De API is gewoon HTTP en JSON, dus elke taal of automatiseringsplatform dat een verzoek kan versturen, kan hem aanroepen.

Codevoorbeelden

API Bearer Token

Het token hoort bij je account en kan altijd opnieuw worden gegenereerd. De API-scan vraagt een Pro-account: zonder geldig token antwoordt de API met 401, en zonder de Pro-rol met 403.

Uitproberen

Stel de parameters in, kijk hoe de request body meebeweegt en doe dan de drie aanroepen naar de API.

Scanparameters

Een proefrun roept de API aan met jouw token en vraagt een Pro-account; de parameters en de request body mag je vrij bekijken.

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

Scantaakinformatie

voorbeeld
{
  "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-referentie

MethodePadBeschrijving
POST/v1/scan-jobsMaakt een scantaak aan. Stuur config en eventueel webhookUrl; je krijgt het taakobject met status created en een vooraf ondertekende uploadURL terug.
PUT{uploadURL}Het vooraf ondertekende S3-adres uit de vorige stap, niet op api.lookscanned.ioUploadt de bron-PDF met Content-Type: application/pdf en Content-Length. Het adres draagt zijn eigen handtekening, dus voeg geen Authorization-header toe.
GET/v1/scan-jobs/{jobID}Leest één taak, voor het pollen. Bij created bevat hij uploadURL, bij completed downloadURL.
GET/v1/scan-jobsSomt je eigen taken op, te filteren op jobID, status of createdAfter.
Statuscreatedprocessingcompletedfailed
  • 401 geen geldig token
  • 403 het account is geen Pro
  • 404 taak bestaat niet

Request body

VeldTypeStandaardBeschrijving
webhookUrlstring · —Wordt één keer aangeroepen zodra de taak klaar is, dan hoef je niet te pollen.
config.colorspace'gray' | 'sRGB' · graygrayKleurruimte van de uitvoerafbeelding; gray is een zwart-witte scan.
config.resolutionnumber · 7272Resolutie van de uitvoerafbeelding, in dpi.
config.rotatenumber · —Rotatie van het hele document, in graden.
config.rotate_varnumber · —Bereik van de willekeurige rotatie per pagina, in graden — het effect van scheef neergelegd papier.
config.blurnumber · 00Mate van vervaging.
config.noisenumber · 00Mate van ruis.
config.brightnessnumber · 11Helderheid; 1 laat die ongewijzigd.
config.contrastnumber · 11Contrast; 1 laat dat ongewijzigd.
config.borderboolean · falsefalseOf de pagina een scanrand krijgt.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegAfbeeldingsformaat waarin de pagina's worden gerenderd.

Elk veld mag ontbreken. De beginwaarden van «Uitproberen» — resolutie 150, rotatie 1, helderheid en contrast 1,3 — zijn de combinatie die de webapp aanraadt, niet de standaardwaarden van de API.

Velden in het taakobject om op te letten

status
created / processing / completed / failed — bepaalt of de twee adressen hieronder aanwezig zijn.
uploadURL
Alleen zolang de taak created is. Een vooraf ondertekend uploadadres dat verloopt.
downloadURL
Pas als de taak completed is. Een vooraf ondertekend downloadadres dat verloopt.
inputUploadedAt / completedAt
Wanneer de upload van de bron klaar was en wanneer de taak klaar was; het verschil is de verwerkingstijd.

Veelgestelde vragen

Is Pro nodig voor de API-scan?

Ja. Zonder geldig token antwoordt de API met 401, en een account zonder de Pro-rol krijgt 403. Na de upgrade en het inloggen staat het token op deze pagina.

Hoe weet ik wanneer een taak klaar is?

Op twee manieren: poll GET /v1/scan-jobs/{jobID}, of geef bij het aanmaken een webhookUrl mee en laat de dienst je één keer terugbellen.

Is het resultaat hetzelfde als scannen op de webpagina?

Ja. Beide gebruiken dezelfde implementatie van het scaneffect, en kleurruimte, resolutie, rotatie, vervaging, ruis, helderheid, contrast en rand in config zijn de gelijknamige opties van de webpagina: dezelfde parameters geven dezelfde uitvoer. Alleen de plaats van verwerking verschilt — lokaal op de pagina, op afstand via de API.

Kan ik de upload- en downloadadressen bewaren en hergebruiken?

Liever niet. uploadURL en downloadURL zijn vooraf ondertekende adressen met een houdbaarheid; na het verlopen moet je de taak opnieuw opvragen om nieuwe te krijgen.

Hoe lang duurt een taak?

Dat hangt af van het aantal pagina's en de resolutie. Een paar pagina's zijn meestal binnen seconden klaar; een hogere resolutie of een langer document duurt langer. Het verschil tussen inputUploadedAt en completedAt is de werkelijke duur.

Wat als een taak mislukt?

De status wordt failed. De gebruikelijke oorzaken zijn een bestand dat geen geldige PDF is, versleutelingsbeperkingen of een afgebroken upload. Controleer of het bestand opengaat en maak een nieuwe taak aan.

Kan ik eerdere taken opzoeken?

Ja. GET /v1/scan-jobs somt je eigen taken op en laat filteren op jobID, status en createdAfter — genoeg om af te stemmen of iets opnieuw te downloaden.