Skanowanie przez API

Skanowanie przez API zamienia PDF w wiarygodną zeskanowaną kopię jednym wywołaniem REST, co sprawdza się w procesach automatycznych i integracjach z aplikacjami. Utwórz zadanie, prześlij PDF, a potem odpytuj status albo poczekaj na webhook — trzy kroki, z dowolnego środowiska i języka, który potrafi wysłać żądanie HTTP. Przestrzeń barw, rozdzielczość, obrót, rozmycie, szum, jasność, kontrast i obramowanie są w pełni konfigurowalne.

Przebieg wywołania

  1. Utwórz zadanie

    POST /v1/scan-jobs

    Wyślij swoją config i opcjonalnie webhookUrl; w odpowiedzi otrzymasz jobID i podpisany wcześniej uploadURL.

  2. Prześlij PDF

    PUT {uploadURL}

    Wykonaj PUT pliku prosto na podpisany wcześniej adres S3 z poprzedniego kroku — token nie jest potrzebny.

  3. Odbierz zeskanowaną kopię

    GET /v1/scan-jobs/{jobID}

    Odpytuj status albo poczekaj na webhook; gdy zadanie ma status completed, pobierz plik spod downloadURL.

Gdzie się przyda

Zbiorcza produkcja po stronie serwera

Umowy, faktury i raporty tworzone na serwerze od razu przechodzą przez efekt skanowania, bez powtarzania tego samego ręcznie na stronie.

Wewnątrz istniejącego systemu

Dodaj do CRM-a, ERP-a lub systemu zgłoszeń akcję „eksportuj zeskanowaną kopię”, która wywołuje API.

Łańcuchy automatyzacji

CI, n8n, Zapier i podobne uruchamiają zadanie na zdarzenie, a webhook po zakończeniu przekazuje pracę dalej.

Duże kolejki plików

Zadania są asynchroniczne: po utworzeniu każde jest przetwarzane osobno, a postęp można sprawdzać przez status i createdAfter.

Języki i środowiska

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLWiersz poleceń / CI
WięcejDowolny klient HTTP

API to zwykły HTTP i JSON, więc wywoła je każdy język i każda platforma automatyzacji, która potrafi wysłać żądanie.

Przykłady kodu

API Bearer Token

Token należy do Twojego konta i można go w każdej chwili wygenerować ponownie. Skanowanie przez API wymaga konta Pro: bez ważnego tokena API odpowiada 401, a bez roli Pro — 403.

Wypróbuj

Ustaw parametry, obserwuj, jak zmienia się treść żądania, a potem wykonaj trzy wywołania do API.

Parametry skanowania

Przebieg próbny wywołuje API Twoim tokenem i wymaga konta Pro; parametry i treść żądania możesz oglądać swobodnie.

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

Informacje o zadaniu skanowania

przykład
{
  "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-…"
}

Dokumentacja API

MetodaŚcieżkaOpis
POST/v1/scan-jobsTworzy zadanie skanowania. Wyślij config i opcjonalnie webhookUrl; w odpowiedzi otrzymasz obiekt zadania ze statusem created i podpisany wcześniej uploadURL.
PUT{uploadURL}Podpisany wcześniej adres S3 z poprzedniego kroku, który nie znajduje się na api.lookscanned.ioPrzesyła źródłowy PDF z nagłówkami Content-Type: application/pdf i Content-Length. Adres ma własny podpis, więc nie dodawaj nagłówka Authorization.
GET/v1/scan-jobs/{jobID}Odczytuje pojedyncze zadanie, na potrzeby odpytywania. Przy created zawiera uploadURL, przy completed — downloadURL.
GET/v1/scan-jobsWypisuje Twoje zadania z filtrami po jobID, status i createdAfter.
Statuscreatedprocessingcompletedfailed
  • 401 brak ważnego tokena
  • 403 konto nie jest Pro
  • 404 zadanie nie istnieje

Treść żądania

PoleTypDomyślnieOpis
webhookUrlstring · —Wywoływany raz po zakończeniu zadania, więc nie trzeba go odpytywać.
config.colorspace'gray' | 'sRGB' · graygrayPrzestrzeń barw obrazu wynikowego; gray to czarno-biała zeskanowana kopia.
config.resolutionnumber · 7272Rozdzielczość obrazu wynikowego w DPI.
config.rotatenumber · —Obrót całego dokumentu w stopniach.
config.rotate_varnumber · —Zakres losowego obrotu każdej strony w stopniach — wrażenie krzywo położonej kartki.
config.blurnumber · 00Siła rozmycia.
config.noisenumber · 00Siła szumu.
config.brightnessnumber · 11Jasność; 1 nie zmienia nic.
config.contrastnumber · 11Kontrast; 1 nie zmienia nic.
config.borderboolean · falsefalseCzy dodać stronie obramowanie skanu.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegFormat obrazu, do którego renderowane są strony.

Każde pole można pominąć. Wartości początkowe w sekcji „Wypróbuj” — rozdzielczość 150, obrót 1, jasność i kontrast 1,3 — to zestaw zalecany przez aplikację webową, a nie wartości domyślne API.

Pola obiektu zadania warte uwagi

status
created / processing / completed / failed — decyduje o tym, czy poniższe dwa adresy w ogóle się pojawiają.
uploadURL
Tylko dopóki zadanie ma status created. Podpisany wcześniej adres przesyłania, który wygasa.
downloadURL
Dopiero po statusie completed. Podpisany wcześniej adres pobierania, który wygasa.
inputUploadedAt / completedAt
Kiedy zakończyło się przesyłanie źródła i kiedy zakończyło się zadanie; różnica to czas przetwarzania.

Najczęstsze pytania

Czy skanowanie przez API wymaga Pro?

Tak. Bez ważnego tokena API odpowiada 401, a konto bez roli Pro dostaje 403. Po przejściu na Pro i zalogowaniu token pojawia się na tej stronie.

Skąd wiadomo, że zadanie się skończyło?

Na dwa sposoby: odpytywać GET /v1/scan-jobs/{jobID} albo przekazać webhookUrl przy tworzeniu zadania i pozwolić usłudze zgłosić się raz po zakończeniu.

Czy wynik jest taki sam jak przy skanowaniu na stronie?

Taki sam. Obie drogi korzystają z tej samej implementacji efektu skanowania, a przestrzeń barw, rozdzielczość, obrót, rozmycie, szum, jasność, kontrast i obramowanie w config odpowiadają opcjom o tych samych nazwach na stronie: te same parametry dają ten sam wynik. Różni się tylko miejsce przetwarzania — lokalnie na stronie, zdalnie przez API.

Czy mogę zapisać adresy przesyłania i pobierania i używać ich ponownie?

Lepiej nie. uploadURL i downloadURL to podpisane wcześniej adresy o ograniczonej ważności; po wygaśnięciu trzeba ponownie odczytać zadanie, żeby dostać nowe.

Jak długo trwa zadanie?

Zależy od liczby stron i rozdzielczości. Kilka stron zwykle kończy się w kilka sekund, a wyższa rozdzielczość i dłuższe dokumenty zajmują więcej czasu. Różnica między inputUploadedAt a completedAt to rzeczywisty czas.

Co zrobić, gdy zadanie się nie powiedzie?

Status zmienia się na failed. Najczęstsze przyczyny to plik, który nie jest poprawnym PDF-em, ograniczenia szyfrowania albo przerwane przesyłanie. Sprawdź, czy plik się otwiera, i utwórz nowe zadanie.

Czy mogę sprawdzić wcześniejsze zadania?

Tak. GET /v1/scan-jobs wypisuje Twoje zadania i pozwala filtrować po jobID, status i createdAfter, co wystarcza do uzgodnienia albo ponownego pobrania.