Scanare prin API

Scanarea prin API transformă un PDF într-o copie cu aspect de scanare printr-un apel REST, potrivit pentru automatizări și integrarea în aplicații. Creează o sarcină, încarcă PDF-ul, apoi verifică periodic starea sau așteaptă notificarea webhook. Sunt trei pași, din orice mediu sau limbaj care poate trimite cereri HTTP. Poți regla spațiul de culoare, rezoluția, rotația, estomparea, zgomotul, luminozitatea, contrastul și chenarele.

Cum funcționează un apel

  1. Creează sarcina

    POST /v1/scan-jobs

    Trimite configurația și, opțional, un webhookUrl. Primești un jobID și un uploadURL presemnat.

  2. Încarcă PDF-ul

    PUT {uploadURL}

    Trimite fișierul prin PUT direct la adresa S3 presemnată din pasul anterior. Nu este nevoie de token.

  3. Descarcă copia scanată

    GET /v1/scan-jobs/{jobID}

    Verifică periodic starea sau așteaptă notificarea webhook. Când sarcina este finalizată, descarcă rezultatul de la downloadURL.

La ce îl poți folosi

Procesare în lot pe server

Aplică efectul de scanare direct contractelor, facturilor și rapoartelor generate pe server, fără să repeți manual operația pe site.

Integrare într-un sistem existent

Adaugă o acțiune de export al unei copii scanate într-un CRM, ERP sau sistem de tichete și conecteaz-o la API.

Fluxuri automatizate

CI, n8n, Zapier și alte instrumente pot porni o sarcină la un anumit eveniment. Notificarea webhook declanșează pasul următor la finalizare.

Cozi mari de fișiere

Sarcinile sunt asincrone: le creezi și fiecare este procesată separat. Poți urmări progresul folosind status și createdAfter.

Limbaje și medii

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLLinie de comandă / CI
AlteleOrice client HTTP

API-ul folosește HTTP și JSON, deci îl poți apela din orice limbaj sau platformă de automatizare care poate trimite o cerere.

Exemple de cod

API Bearer Token

Tokenul aparține contului tău și îl poți regenera oricând. Scanarea prin API necesită un cont Pro: fără un token valid, API-ul răspunde cu 401, iar fără rolul Pro, cu 403.

Încearcă API-ul

Reglează parametrii și urmărește cum se actualizează corpul cererii, apoi execută cele trei apeluri API.

Parametri de scanare

Testul apelează API-ul cu tokenul tău și necesită un cont Pro. Poți consulta gratuit parametrii și corpul cererii.

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

Detaliile sarcinii de scanare

exemplu
{
  "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-…"
}

Referință API

MetodăCaleDescriere
POST/v1/scan-jobsCreează o sarcină de scanare. Trimite config și, opțional, webhookUrl. Primești obiectul sarcinii cu starea created și un uploadURL presemnat.
PUT{uploadURL}Adresa S3 presemnată din pasul anterior, nu o adresă de pe api.lookscanned.ioÎncarcă PDF-ul sursă cu Content-Type: application/pdf și Content-Length. Adresa include propria semnătură, deci nu adăuga un antet Authorization.
GET/v1/scan-jobs/{jobID}Citește o sarcină pentru a-i verifica starea. Cât timp starea este created, obiectul include uploadURL; când este completed, include downloadURL.
GET/v1/scan-jobsListează propriile sarcini, filtrate după jobID, status sau createdAfter.
Starecreatedprocessingcompletedfailed
  • 401 token lipsă sau nevalid
  • 403 contul nu are Pro
  • 404 sarcina nu există

Corpul cererii

CâmpTipValoare implicităDescriere
webhookUrlstring · —Apelat o singură dată la finalizarea sarcinii, ca să nu fie nevoie să verifici periodic starea.
config.colorspace'gray' | 'sRGB' · graygraySpațiul de culoare al imaginii rezultate; gray produce o scanare în tonuri de gri.
config.resolutionnumber · 7272Rezoluția imaginii rezultate, în DPI.
config.rotatenumber · —Rotația întregului document, în grade.
config.rotate_varnumber · —Intervalul rotației aleatorii pentru fiecare pagină, în grade, pentru a imita hârtia așezată ușor strâmb.
config.blurnumber · 00Intensitatea estompării.
config.noisenumber · 00Intensitatea zgomotului.
config.brightnessnumber · 11Luminozitate; valoarea 1 o păstrează neschimbată.
config.contrastnumber · 11Contrast; valoarea 1 îl păstrează neschimbat.
config.borderboolean · falsefalseAdaugă sau nu un chenar de scanare paginii.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegFormatul de imagine în care sunt redate paginile.

Toate câmpurile sunt opționale. Valorile inițiale din „Încearcă API-ul” (rezoluție 150, rotație 1, luminozitate și contrast 1.3) sunt cele recomandate de aplicația web, nu valorile implicite ale API-ului.

Câmpuri de urmărit în obiectul sarcinii

status
created / processing / completed / failed — determină dacă sunt prezente cele două adrese de mai jos.
uploadURL
Doar în starea created. O adresă presemnată de încărcare, cu termen de valabilitate.
downloadURL
Doar în starea completed. O adresă presemnată de descărcare, cu termen de valabilitate.
inputUploadedAt / completedAt
Momentul încheierii încărcării și momentul finalizării sarcinii; diferența reprezintă timpul de procesare.

Întrebări frecvente

Am nevoie de Pro pentru scanarea prin API?

Da. Fără un token valid, API-ul răspunde cu 401, iar pentru un cont fără rolul Pro, cu 403. Treci la Pro și autentifică-te pentru a vedea tokenul pe această pagină.

Cum aflu când s-a terminat o sarcină?

Ai două opțiuni: verifici periodic GET /v1/scan-jobs/{jobID} sau trimiți un webhookUrl la crearea sarcinii, iar serviciul îl apelează o singură dată la finalizare.

Rezultatul este același ca la scanarea pe site?

Da. Ambele folosesc aceeași implementare a efectului de scanare. Spațiul de culoare, rezoluția, rotația, estomparea, zgomotul, luminozitatea, contrastul și chenarul din config corespund opțiunilor de pe site, sub alte nume. Aceiași parametri dau același rezultat. Diferă doar locul procesării: local pe site, pe server prin API.

Pot păstra adresele de încărcare și descărcare pentru a le refolosi?

Nu este recomandat. uploadURL și downloadURL sunt adrese presemnate care expiră. După expirare, citește din nou sarcina pentru a obține adrese noi.

Cât durează o sarcină?

Depinde de numărul de pagini și de rezoluție. Câteva pagini sunt de obicei gata în câteva secunde; rezoluțiile mai mari și documentele mai lungi necesită mai mult timp. Diferența dintre inputUploadedAt și completedAt este timpul efectiv de procesare.

Ce se întâmplă dacă o sarcină eșuează?

Starea devine failed. Cauzele obișnuite sunt un fișier PDF nevalid, restricții de criptare sau o încărcare întreruptă. Verifică dacă fișierul se deschide, apoi creează o sarcină nouă.

Pot consulta sarcinile anterioare?

Da. GET /v1/scan-jobs listează propriile sarcini și permite filtrarea după jobID, status și createdAfter, pentru verificarea evidențelor sau o nouă descărcare.