Dokumentacja API

Wyślij plik PDF, dokument Word lub obraz i otrzymaj ustrukturyzowany JSON.

Wprowadzenie

Dane, które chcesz otrzymać, opisujesz jako kategorię: listę pól, takich jak numer faktury, data czy pozycje, skonfigurowaną w panelu. Parsevix odczytuje dokument, wypełnia te pola i zwraca je jako JSON wraz z odczytanym tekstem oraz miejscem, w którym znaleziono każdą wartość.

API jest udostępniane przez HTTPS pod jednym bazowym adresem URL. Żądania i odpowiedzi są w formacie JSON, z wyjątkiem przesyłania plików, które używa multipart/form-data.

https://parsevix.com/api/v1

Każdy klucz API należy do jednego projektu. Klucz widzi i zmienia wyłącznie dokumenty, kategorie i webhooki tego projektu.

Oprócz wywoływania API wyniki można odbierać przez webhooki, połączyć Zapier lub wysyłać dokumenty na adres e-mail projektu.

Konwencje

Odpowiedzi API używają nazw pól w camelCase. Treści webhooków i wywołań zwrotnych używają snake_case.
Znaczniki czasu są w UTC, w formacie ISO 8601 (2026-10-25T10:12:06.791Z).
Komunikaty błędów są w języku angielskim, niemieckim, tureckim, francuskim, hiszpańskim, włoskim, niderlandzkim, polskim lub portugalskim, zgodnie z nagłówkiem Accept-Language.

Szybki start

1
Utwórz klucz API
W panelu otwórz projekt, przejdź do sekcji Klucze API i utwórz klucz. Jest wyświetlany tylko raz; zapisz go, na przykład jako zmienną środowiskową PARSEVIX_API_KEY. Plan Free obejmuje jeden klucz, plany płatne więcej (zob. Limity i kredyty).
2
Zdefiniuj kategorię
W sekcji Kategorie utwórz kategorię dla swojego typu dokumentu i dodaj potrzebne pola albo zacznij od wbudowanego szablonu. Przykłady na tej stronie używają kategorii o nazwie Supplier invoice.
3
Wyślij dokument
POST /extract przesyła plik i czeka na wynik. Odpowiedź zawiera wypełnione pola w extracted.

Aby przetwarzać wiele dokumentów bez utrzymywania otwartych żądań, przesyłaj je asynchronicznie i odbieraj wyniki przez webhooki.

curl https://parsevix.com/api/v1/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice"

Odpowiedź200· skrócono

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Samouczki wideo

Pięć krótkich filmów pokazuje najważniejsze kroki w panelu i Twoje pierwsze żądanie API. Każdy ma lektora i napisy w dziewięciu językach: wybierz je pod ikoną koła zębatego w odtwarzaczu.

Filmy są odtwarzane z YouTube (youtube-nocookie.com). Dopóki nie klikniesz odtwarzania, nic nie jest ładowane z YouTube; potem Google otrzymuje Twój adres IP i może zapisać pliki cookie. Zob. naszą Politykę prywatności.

Uwierzytelnianie

Wysyłaj klucz API w nagłówku X-API-Key w każdym żądaniu.

X-API-Key: psvx_…

Klucz działa tylko w /api/v1; nie pozwala zalogować się do panelu. Klucze tworzy się i unieważnia w sekcji Klucze API projektu. Unieważniony klucz natychmiast przestaje działać.

Przechowuj klucze na swoim serwerze. Każdy, kto ma klucz, może przesyłać dokumenty i odczytywać wyniki projektu, a przesłane dokumenty zużywają Twoje kredyty.

Gdy klucz zostanie odrzucony

Status	Kod	Znaczenie
401	`apikey.missing`	Nie wysłano nagłówka `X-API-Key`.
401	`apikey.invalid`	Klucz nie istnieje lub został unieważniony.
403	`apikey.plan_disabled`	Plan konta nie obejmuje dostępu do API.
403	`apikey.paused_by_plan`	Klucz lub jego projekt jest wstrzymany, ponieważ plan konta dopuszcza mniej kluczy lub projektów.
403	`apikey.account_unavailable`	Konto jest zamknięte lub zaplanowane do usunięcia.
403	`apikey.project_unavailable`	Projekt klucza został usunięty.
429	`apikey.too_many_invalid`	Z Twojej sieci w ciągu 10 minut przyszło ponad 30 nieprawidłowych kluczy. Odczekaj `Retry-After` sekund; klucz, który niedawno działał, nie jest blokowany.

Odpowiedź401

{
  "error": {
    "code": "apikey.invalid",
    "message": "The API key is not valid. It may have been revoked; create a new one in the project under API Keys."
  }
}

Tryby przetwarzania

Każdy przesłany dokument jest odczytywany na jeden z czterech sposobów.

Automatyczna kategoria (auto-classify). Parsevix wybiera najlepiej pasującą kategorię projektu, a następnie wyodrębnia jej pola. Używany, gdy nie podasz kategorii lub wyślesz category=auto.
Tylko klasyfikacja (classify-only). Parsevix wybiera najlepiej pasującą kategorię i niczego nie wyodrębnia, co pozwala sortować dokumenty według typu. Odczytuje pierwsze 3 strony i kosztuje 1 kredyt za dokument. Pola można wyodrębnić później. Zob. Klasyfikacja dokumentu.
Wskazana kategoria (specific). Podajesz kategorię; wyodrębniane są jej pola.
Bez schematu (auto-entity). Nie jest używana żadna kategoria. Parsevix zwraca znalezione pola, nazwane według etykiet z samego dokumentu. Zob. Ekstrakcja bez schematu.

Język dokumentu jest wykrywany automatycznie. Opcjonalny parametr language służy jedynie jako wartość zapasowa dla dokumentów ze zbyt małą ilością tekstu, by wykryć język.

Ekstrakcja danych z dokumentu

POST/api/v1/extract

Przesyła dokument i czeka na zakończenie przetwarzania. Odpowiedź zawiera wyodrębnione pola.

filefilewymagane: Dokument: PDF, DOCX, PNG, JPEG lub TIFF, do 10 MB i 30 stron.
categorystringopcjonalne: Nazwa kategorii w projekcie. Pomiń ją lub wyślij auto, aby Parsevix wybrał sam.
languagestringopcjonalne: Dwuliterowy kod ISO 639-1, np. de. Używany tylko wtedy, gdy nie da się wykryć języka.

Oczekiwanie i limity

Żądanie pozostaje otwarte do chwili, gdy wynik jest gotowy, najdłużej 285 sekund. Ustaw limit czasu klienta HTTP powyżej tej wartości.
Jeśli przetwarzanie trwa dłużej, otrzymasz 504 z document.sync_timeout i documentId. Przetwarzanie trwa dalej; wynik trafi do Twoich webhooków.
Jeśli przetwarzanie się nie powiedzie, otrzymasz 422 z document.sync_failed. reason podaje przyczynę; zob. przyczyny niepowodzenia.
Każdy klucz API może mieć jednocześnie 5 otwartych żądań. Kolejne zwracają 429 z document.sync_concurrency_limit. Żądanie, które zamkniesz lub które przekroczy limit czasu, zajmuje miejsce, dopóki jego dokument nie zostanie przetworzony. Do masowego przesyłania używaj przesyłania asynchronicznego.

Odpowiedź

idstring: Identyfikator dokumentu.
fileNamestring: Nazwa przesłanego pliku.
statusstring: Completed.
categorystring | null: Użyta kategoria; null bez schematu.
processingModestring: auto-classify, specific lub auto-entity.
confidenceScorenumber: Wartość od 0 do 1: pewność ekstrakcji.
pageCountinteger: Przetworzone strony; każda kosztuje jeden kredyt.
languagestring: Wykryty język, ISO 639-1.
retainedboolean: Czy Parsevix przechowuje plik i wynik. Zob. Przechowywanie danych.
extractedobject: Wyodrębnione pola. Zob. Wynik.

curl https://parsevix.com/api/v1/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice"

Odpowiedź200· skrócono

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Odpowiedź422

{
  "error": {
    "code": "document.sync_failed",
    "message": "The file is damaged or is not a valid PDF, Word document or image.",
    "reason": "file_unreadable",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Odpowiedź504

{
  "error": {
    "code": "document.sync_timeout",
    "message": "Extraction did not finish within 285 seconds. Large documents may need to be split.",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Ekstrakcja bez schematu

POST/api/v1/extract-auto

Jak POST /extract, ale bez kategorii: Parsevix zwraca wszystkie pola, które znajdzie w dokumencie.

filefilewymagane: Dokument: PDF, DOCX, PNG, JPEG lub TIFF, do 10 MB i 30 stron.
languagestringopcjonalne: Dwuliterowy kod ISO 639-1. Używany tylko wtedy, gdy nie da się wykryć języka.

Wynik pozostaje w języku dokumentu. Klucze to etykiety z samego dokumentu w snake_case (faktura w języku niemieckim daje rechnungsnummer), a wartości są kopiowane tak, jak zostały wydrukowane: daty w formacie dokumentu, kwoty jako ciągi znaków, np. "2.430,09".

Używaj tego trybu do poznania nowego typu dokumentu. Dla danych przetwarzanych automatycznie kategoria zapewnia stałe klucze i znormalizowane wartości.

Odpowiedź ma te same pola co POST /extract, z processingMode równym auto-entity i category równym null.

curl https://parsevix.com/api/v1/extract-auto \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf

Klasyfikacja dokumentu

POST/api/v1/classify

Przesyła dokument i czeka, aż Parsevix wybierze jedną z kategorii projektu. Żadne pola nie są wyodrębniane. Służy do sortowania lub kierowania dokumentów według typu.

Kandydatami są własne kategorie projektu, a nie wbudowane szablony. Parsevix odczytuje pierwsze 3 strony, więc klasyfikacja kosztuje 1 kredyt niezależnie od długości dokumentu.

filefilewymagane: Dokument: PDF, DOCX, PNG, JPEG lub TIFF, do 10 MB i 30 stron.
languagestringopcjonalne: Dwuliterowy kod ISO 639-1. Używany tylko wtedy, gdy nie da się wykryć języka.

Oczekiwanie i błędy działają jak w POST /extract: najdłużej 285 sekund, 504 z document.sync_timeout, jeśli trwa to dłużej, 422 z document.sync_failed, jeśli dokumentu nie da się przetworzyć. Limit 5 otwartych żądań na klucz jest wspólny dla obu endpointów.

Odpowiedź

idstring: Identyfikator dokumentu.
fileNamestring: Nazwa przesłanego pliku.
statusstring: Completed.
categorystring: Kategoria wybrana przez Parsevix.
processingModestring: classify-only.
pageCountinteger: Liczba stron dokumentu. Odczytano pierwsze 3.
languagestring: Wykryty język, ISO 639-1.
retainedboolean: Czy Parsevix przechowuje plik. Później można wyodrębnić dane tylko z przechowywanego dokumentu.

Późniejsza ekstrakcja

POST /documents/{id}/extract wyodrębnia pola dokumentu według przypisanej mu kategorii lub wskazanej przez Ciebie. Kosztuje tyle kredytów, ile dokument ma stron, pomniejszone o 1 kredyt już zapłacony: dokument 5-stronicowy kosztuje jeszcze 4, łącznie 5.

Wymaga to pliku, więc projekt musi przechowywać dokumenty przesłane przez API (zob. Przechowywanie danych). Dokumenty wysłane z panelu lub e-mailem są zawsze przechowywane. Dokumenty przesyłane asynchronicznie również można klasyfikować: processingMode=classify-only w POST /documents.

curl https://parsevix.com/api/v1/classify \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf

Odpowiedź200

{
  "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "classify-only",
  "pageCount": 1,
  "language": "en",
  "retained": true
}

Przesyłanie asynchroniczne

POST/api/v1/documents

Umieszcza dokument w kolejce i natychmiast odpowiada kodem 202 oraz rekordem dokumentu. Używaj go do masowego przesyłania i w klientach, które nie mogą utrzymywać otwartego żądania, takich jak Zapier.

filefilewymagane: Dokument: PDF, DOCX, PNG, JPEG lub TIFF, do 10 MB i 30 stron.
categorystringopcjonalne: Nazwa kategorii. Pomiń ją lub wyślij auto, aby Parsevix wybrał sam.
processingModestringopcjonalne: auto-classify, specific, auto-entity lub classify-only. Opcjonalny: domyślnie wynika z category. classify-only nie można łączyć z kategorią.
languagestringopcjonalne: Dwuliterowy kod ISO 639-1. Używany tylko wtedy, gdy nie da się wykryć języka.
callbackUrlstringopcjonalne: Publiczny adres URL https. Parsevix wysyła tam wynik jeden raz, jako POST z tą samą treścią co zdarzenie webhooka.

Odbieranie wyniku

Webhooki projektu otrzymują extraction.completed lub extraction.failed. Dokument przesłany z classify-only wysyła classification.completed zamiast extraction.completed.
callbackUrl, jeśli został podany, otrzymuje to samo zdarzenie z tymi samymi ponowieniami. Nie jest podpisywany, więc umieść w adresie URL tajny token i go sprawdzaj.
Odpytywanie GET /documents/{id} pokazuje status, a wynik tylko wtedy, gdy projekt przechowuje dokumenty przesłane przez API (zob. Przechowywanie danych).

curl https://parsevix.com/api/v1/documents \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice" \
  -F callbackUrl="https://example.com/parsevix/callback?token=a-secret-only-you-know"

Odpowiedź202

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "status": "Pending",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "discardFiles": true,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": null,
  "reprocessCount": 0,
  "lastReprocessedAt": null,
  "approvalStatus": "Unapproved",
  "isTrainingExample": false
}

Wynik

extracted

Obiekt, którego kluczami są nazwy pól kategorii (fieldName w schemacie kategorii). Obiekty i listy odpowiadają schematowi.

Daty mają format YYYY-MM-DD. Liczby są liczbami JSON, bez symboli walut i separatorów tysięcy. Pole, którego nie ma w dokumencie, jest pomijane lub ma wartość null.

Dane osobowe, takie jak imiona i nazwiska czy numery IBAN, są zwracane tak, jak zapisano je w dokumencie. Są maskowane tylko w drodze do modelu AI i przywracane, zanim je otrzymasz.

_field_blocks

Miejsce, w którym znaleziono każdą wartość. Klucze to ścieżki pól, np. seller.name lub line_items[0].total; każdy wpis zawiera wiersze tekstu ze stroną, ramką i tekstem. Wartości, której nie udało się zlokalizować, tu brak. Jeśli potrzebujesz tylko danych, ignoruj klucze zaczynające się od _.

Współrzędne

PDF i DOCX: punkty PDF (1/72 cala). Początek układu to lewy dolny róg strony; y to górna krawędź ramki mierzona od dołu.
Obrazy: piksele. Początek układu to lewy górny róg; y to górna krawędź mierzona od góry.

extracted200· skrócono

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Dokumenty

Dokumenty projektu ze wszystkich źródeł: z panelu, z API i z e-maila.

Lista dokumentów

GET/api/v1/documents

Od najnowszych. Obejmuje tylko przechowywane dokumenty: dokumenty przesłane przez API pojawiają się tylko wtedy, gdy projekt je przechowuje.

pageintegeropcjonalne: Numer strony, od 1.
pageSizeintegeropcjonalne: Od 1 do 100; domyślnie 20.
statusstringopcjonalne: Pending, Processing, Completed lub Failed.
categorystringopcjonalne: Nazwa kategorii.
searchstringopcjonalne: Fragment nazwy pliku.
fileTypestringopcjonalne: pdf, docx lub image.
sourcestringopcjonalne: dashboard, api lub email.
processingModestringopcjonalne: auto-classify, specific, auto-entity lub classify-only.

Pobieranie dokumentu

GET/api/v1/documents/{id}

Dokument wraz z wynikiem. outputDeanonymized to wyodrębnione dane, ten sam obiekt co extracted. Dokument classify-only ma kategorię w categoryName i nie ma outputDeanonymized. Dokument z błędem ma errorCode i errorMessage. Jeśli projekt nie przechowuje dokumentów przesłanych przez API, dostępny jest status, ale nie wynik.

Ponowne przetwarzanie dokumentu

POST/api/v1/documents/{id}/reprocess

Ponownie uruchamia ekstrakcję, na przykład po zmianie pól kategorii. Opcjonalna treść JSON: category (nazwa lub auto) i processingMode. Odpowiada kodem 202; wynik przychodzi tak jak przy przesyłaniu asynchronicznym. Kredyty są naliczane ponownie. Dokument classify-only jest klasyfikowany ponownie (1 kredyt), chyba że wskażesz kategorię. Niemożliwe dla dokumentów przesłanych przez API, których pliki nie zostały zachowane (document.files_not_retained).

Ekstrakcja danych ze sklasyfikowanego dokumentu

POST/api/v1/documents/{id}/extract

Dla dokumentu przesłanego z classify-only: wyodrębnia jego pola według przypisanej mu kategorii lub kategorii category podanej w opcjonalnej treści JSON. Kosztuje tyle kredytów, ile dokument ma stron, pomniejszone o 1 kredyt za klasyfikację. Odpowiada kodem 202; wynik przychodzi tak jak przy przesyłaniu asynchronicznym, jako extraction.completed. Dla każdego innego dokumentu odpowiada 400 z document.not_classify_only; użyj wtedy ponownego przetwarzania.

Usuwanie dokumentu

DELETE/api/v1/documents/{id}

Usuwa dokument, jego plik i wyniki. Odpowiada kodem 204.

Identyfikator, który nie istnieje w projekcie klucza, zwraca 404 z document.not_found.

cURL

curl "https://parsevix.com/api/v1/documents?status=Completed&pageSize=20" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Odpowiedź200· skrócono

{
  "data": [
    {
      "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
      "status": "Completed",
      "categoryName": "Supplier invoice",
      "processingMode": "specific",
      "fileName": "invoice.pdf",
      "fileSize": 22579,
      "source": "api",
      "discardFiles": false,
      "createdAt": "2026-10-25T10:12:06.791Z",
      "completedAt": "2026-10-25T10:12:15.212Z",
      "reprocessCount": 0,
      "lastReprocessedAt": null,
      "approvalStatus": "Unapproved",
      "isTrainingExample": false
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}

curl https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Odpowiedź200· skrócono

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "status": "Completed",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "language": "en",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "outputDeanonymized": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  },
  "errorMessage": null,
  "errorCode": null,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": "2026-10-25T10:12:15.212Z"
}

cURL

curl https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581/reprocess \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category": "auto"}'

cURL

curl https://parsevix.com/api/v1/documents/01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Odpowiedź202

{
  "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
  "status": "Pending",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "discardFiles": false,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": null,
  "reprocessCount": 1,
  "lastReprocessedAt": "2026-10-25T11:04:12.530Z",
  "approvalStatus": "Unapproved",
  "isTrainingExample": false
}

cURL

curl -X DELETE https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Kategorie

Kategorie projektu, w tym wbudowane szablony (isGlobal: true). Kategorie tworzy się i edytuje w panelu.

Lista kategorii

GET/api/v1/categories

Pobieranie schematu kategorii

GET/api/v1/categories/{name}

Pola, które wyodrębnia kategoria. fieldName to klucz w extracted. fieldType to string, number, date, boolean, object lub array; obiekty i tablice mają swoje pola w children. Wielkość liter w nazwie w ścieżce nie ma znaczenia.

cURL

curl https://parsevix.com/api/v1/categories \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Odpowiedź200· skrócono

[
  {
    "id": 1,
    "name": "Invoice",
    "description": "Invoices and billing documents with seller/buyer info, line items, and totals",
    "isGlobal": true,
    "fieldCount": 48
  },
  {
    "id": 54,
    "name": "Supplier invoice",
    "description": "Commercial invoice: seller, buyer, line items and totals.",
    "isGlobal": false,
    "fieldCount": 26
  }
]

cURL

curl "https://parsevix.com/api/v1/categories/Supplier%20invoice" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Odpowiedź200· skrócono

{
  "id": 54,
  "name": "Supplier invoice",
  "description": "Commercial invoice: seller, buyer, line items and totals.",
  "fields": [
    {
      "fieldName": "invoice_number",
      "displayName": "Invoice number",
      "fieldType": "string",
      "description": null,
      "children": []
    },
    {
      "fieldName": "invoice_date",
      "displayName": "Invoice date",
      "fieldType": "date",
      "description": null,
      "children": []
    },
    {
      "fieldName": "seller",
      "displayName": "Seller",
      "fieldType": "object",
      "description": null,
      "children": [
        {
          "fieldName": "name",
          "displayName": "Name",
          "fieldType": "string",
          "description": null,
          "children": []
        },
        {
          "fieldName": "vat_id",
          "displayName": "VAT / tax id",
          "fieldType": "string",
          "description": null,
          "children": []
        }
      ]
    }
  ]
}

Klucz i kredyty

GET/api/v1/me

Projekt klucza i saldo kredytów konta. Kredyty należą do konta i są wspólne dla wszystkich jego projektów; resetsOn to początek następnego okresu. W planie rocznym okresem jest rok rozliczeniowy, a monthlyLimit zawiera kredyty na cały rok.

cURL

curl https://parsevix.com/api/v1/me \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Odpowiedź200

{
  "projectId": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "projectName": "Accounts payable",
  "projectSlug": "accounts-payable",
  "keyName": "ERP connector",
  "keyPrefix": "psvx_nyskxlv",
  "email": "you@example.com",
  "credits": {
    "period": "2026-10-04",
    "resetsOn": "2026-11-04",
    "monthlyLimit": 1000,
    "used": 312,
    "remaining": 688,
    "planName": "Growth"
  }
}

Zarządzanie webhookami

Webhookami można zarządzać w panelu (Webhooki) lub przez poniższe endpointy.

Tworzenie webhooka

POST/api/v1/webhooks

urlstringwymagane: Publiczny adres URL https. Adresy w sieciach prywatnych są odrzucane.
eventsstring[]wymagane: Jedno lub więcej z extraction.completed, extraction.failed i classification.completed.
filtersobjectopcjonalne: Opcjonalne. sources (dashboard, api, email) i categories (nazwy) ograniczają, które dokumenty wysyłają zdarzenia.

Odpowiedź zawiera jednorazowo secret do podpisywania. Zapisz go, aby weryfikować podpisy.

Lista webhooków

GET/api/v1/webhooks

Usuwanie webhooka

DELETE/api/v1/webhooks/{id}

Przykładowe zdarzenia

GET/api/v1/webhooks/samples

Najnowsze dokumenty projektu jako treści zdarzeń, do testowania odbiornika. Parametry zapytania: event (wymagany), limit (1–10, domyślnie 3), category. Jeśli nie ma jeszcze takiego dokumentu, przykład jest budowany na podstawie schematu kategorii.

cURL

curl https://parsevix.com/api/v1/webhooks \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/parsevix/webhook",
    "events": ["extraction.completed", "extraction.failed"],
    "filters": { "sources": ["api", "email"] }
  }'

Odpowiedź201

{
  "secret": "d0726faeb5c655d349fc30ed226e93e531ac2499800aacde100e83554b48701c",
  "id": "01a17295-c761-7b8f-b173-388bc754b1ba",
  "url": "https://example.com/parsevix/webhook",
  "events": [
    "extraction.completed",
    "extraction.failed"
  ],
  "filters": {
    "sources": [
      "api",
      "email"
    ],
    "categories": null
  },
  "isActive": true,
  "disabledAt": null,
  "disabledReason": null,
  "managedBy": null,
  "createdAt": "2026-10-25T10:23:09.311Z"
}

cURL

curl "https://parsevix.com/api/v1/webhooks/samples?event=extraction.completed&limit=1" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Webhooki

Gdy dokument zostanie przetworzony, Parsevix wysyła POST z treścią JSON do każdego webhooka projektu. Webhooki otrzymują dokumenty ze wszystkich źródeł: z panelu, z API i z e-maila.

Zdarzenia

Zdarzenie	Opis
extraction.completed	Dokument został przetworzony. `data` zawiera wyodrębnione pola.
classification.completed	Dokument `classify-only` otrzymał kategorię: `document.category`, z liczbą stron dokumentu w `document.page_count`. Brak `data`.
extraction.failed	Nie udało się przetworzyć dokumentu, także dokumentu `classify-only`. `error_code` to jedna z przyczyn niepowodzenia; `error` to komunikat wyświetlany w panelu.
test.ping	Wysyłane przyciskiem Test na stronie webhooka w panelu.

Nagłówki

Nagłówek	Opis
X-Webhook-Id	Identyfikator zdarzenia. Taki sam w każdej próbie; używaj go do pomijania duplikatów. Jest to także `id` w treści.
X-Webhook-Event	Nazwa zdarzenia.
X-Webhook-Timestamp	Czas uniksowy tej próby, w sekundach.
X-Webhook-Signature	`sha256=`, a po nim szesnastkowy HMAC-SHA256 z `{timestamp}.{raw body}`, z kluczem w postaci sekretu webhooka.
X-Webhook-Attempt	Numer próby, od 1.

Weryfikacja podpisu

Obliczaj HMAC na surowej treści żądania dokładnie w postaci odebranej, przed jej sparsowaniem. Odrzucaj zdarzenia, których znacznik czasu jest starszy niż 5 minut.

Odpowiadanie

Odpowiedz statusem 2xx w ciągu 10 sekund, a dopiero potem przetwarzaj zdarzenie. Każda inna odpowiedź jest traktowana jako niepowodzenie. Przekierowania nie są obsługiwane.
Nieudane doręczenia są ponawiane po 1 minucie, 5 minutach, 30 minutach, 2 godzinach, 6 godzinach i 24 godzinach: 7 prób w ciągu około 33 godzin.
Odpowiedź 410 Gone natychmiast wyłącza webhook. Jest on wyłączany także wtedy, gdy trzy zdarzenia nie powiodły się we wszystkich próbach, a przez 3 dni nie udało się żadne doręczenie. Właściciel otrzymuje e-mail; webhook można ponownie włączyć w panelu. Zdarzenia z tego okresu nie są wysyłane ponownie.
Sekret można zmienić w panelu. Stary sekret natychmiast przestaje działać.

extraction.completed200· skrócono

{
  "id": "01a172a0-3f1e-7d42-9b6c-8e2f5a7d1c90",
  "event": "extraction.completed",
  "timestamp": "2026-10-25T10:12:21.592Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "specific",
    "language": "en",
    "confidence_score": 0.97
  },
  "data": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

classification.completed200

{
  "id": "01a172b5-8e47-7a13-b2c9-4f6d0a8e3b51",
  "event": "classification.completed",
  "timestamp": "2026-10-25T10:14:02.334Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "classify-only",
    "language": "en",
    "page_count": 1
  }
}

extraction.failed200

{
  "id": "01a172a1-0c55-7e18-a3d4-6b9f2e8c1d07",
  "event": "extraction.failed",
  "timestamp": "2026-10-25T10:12:23.711Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "specific"
  },
  "error_code": "file_unreadable",
  "error": "The file is damaged or is not a valid PDF, Word document or image."
}

import hashlib
import hmac
import time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"]  # "sha256=<hex>"
    if abs(time.time() - int(timestamp)) > 300:
        return False  # starsze niż 5 minut: możliwe ponowne odtworzenie
    expected = hmac.new(
        secret.encode(),
        timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, "sha256=" + expected)

Zapier

Aplikacja Parsevix dla Zapiera łączy się za pomocą klucza API projektu. Dodaj ją przez link z zaproszeniem na stronie Zapier projektu w panelu lub tutaj.

Wyzwalacze

Extraction Completed: dokument został przetworzony. Opcjonalnie tylko jedna kategoria lub źródło.
Extraction Failed: nie udało się przetworzyć dokumentu.
Document Classified: dokument wysłany tylko do klasyfikacji otrzymał kategorię, np. z adresu e-mail ustawionego na samą klasyfikację.

Akcje

Extract Document wysyła plik z wcześniejszego kroku, opcjonalnie z kategorią, i przekazuje wyodrębnione pola do kolejnych kroków. Po wybraniu kategorii jej pola można mapować podczas budowania Zapa.
Classify Document wysyła plik i przekazuje kategorię wybraną przez Parsevix do kolejnych kroków, bez wyodrębniania pól. Służy do kierowania dokumentów według typu.

Włączone Zapy pojawiają się na stronie Zapier projektu oraz w sekcji Webhooki.

E-mail

Od planu Starter każdy projekt ma adres e-mail w sekcji Skrzynka e-mail. Każdy załącznik wiadomości wysłanej na ten adres staje się dokumentem; wyniki pojawiają się w panelu i są wysyłane do Twoich webhooków ze źródłem email.

Adresy mają postać name+inbox@inbox.parsevix.com. W zależności od planu projekt może mieć więcej niż jeden adres, np. po jednym dla każdego dostawcy lub działu.

Ustawienia adresu

Załączniki: wyodrębniaj dane z każdego załącznika według jednej stałej kategorii; pozwól Parsevix wybrać kategorię, a następnie wyodrębnić dane; albo tylko wybierz kategorię (classify-only, 1 kredyt za dokument), a pola wyodrębnij później, jeśli będą potrzebne.
Dozwoleni nadawcy: przyjmowane są tylko wiadomości z tych domen i tylko wtedy, gdy przejdą weryfikację DKIM lub SPF dla danej domeny, więc sfałszowany nadawca zostaje odrzucony.

Co jest przetwarzane

Załączniki PDF, DOCX, PNG, JPEG i TIFF, także te w przekazanych dalej wiadomościach. Obrazy wyświetlane w treści wiadomości, np. logo w podpisie, są pomijane.
Wiadomość może mieć do 30 MB, a dokumentami staje się jej pierwszych 20 załączników. Jeden adres przyjmuje do 1000 wiadomości i tworzy do 1000 dokumentów w ciągu 24 godzin; powyżej tego limitu wiadomości są odrzucane, a załączniki oznaczane jako niezaimportowane. Odbieranie jest bezpłatne; każdy dokument kosztuje kredyty jak każdy inny.
Ta sama wiadomość doręczona dwukrotnie (ten sam Message-ID) jest przetwarzana raz.

Błędy

Błędy mają status HTTP i treść ze stałym code oraz czytelnym message. Uzależniaj logikę od code; komunikaty mogą się zmieniać.

Kody statusu

Status	Znaczenie
400	Żądanie jest nieprawidłowe: brakujący lub błędny parametr, nieobsługiwany plik, za mało kredytów. `validation.failed` wymienia problemy dla każdego parametru w `fields`.
401	Brak klucza API lub klucz jest nieprawidłowy.
403	Klucz jest prawidłowy, ale nie może zostać użyty. Zob. Uwierzytelnianie.
404	Dokument, kategoria, webhook lub endpoint nie istnieje w tym projekcie.
413	Przesyłany plik przekracza limit rozmiaru żądania.
422	`POST /extract` lub `POST /classify` zostało wykonane, ale dokumentu nie udało się przetworzyć.
429	Osiągnięto limit liczby żądań lub limit równoczesnych żądań. Odczekaj `Retry-After` sekund.
5xx	Błąd serwera (z identyfikatorem do podania pomocy technicznej), prace serwisowe (`503`) lub przekroczenie czasu (`504`).

Najczęstsze kody

Kod	Znaczenie
validation.file_required	Nie wysłano `file`.
document.content_not_supported	Zawartość pliku nie jest w formacie PDF, DOCX, PNG, JPEG ani TIFF, niezależnie od jego nazwy.
credit.file_size_exceeds_plan	Plik jest większy, niż pozwala plan.
validation.language_invalid	`language` nie jest kodem dwuliterowym.
document.callback_url_*	`callbackUrl` nie jest publicznym adresem URL `https` o długości do 2000 znaków.
credit.insufficient_credits	Za mało kredytów w tym okresie.
document.refund_pending	Zwrot za subskrypcję jest rozpatrywany; do jego rozstrzygnięcia nic nie jest przetwarzane.
category.not_found	W projekcie nie ma kategorii o tej nazwie.
document.classify_only_category	Wysłano `classify-only` razem z kategorią. Ten tryb sam wybiera kategorię.
document.not_classify_only	Wywołano `POST /documents/{id}/extract` dla dokumentu, który nie został przesłany z `classify-only`.
document.files_not_retained	Pliki dokumentu przesłanego przez API nie zostały zachowane, więc nie można go ponownie przetworzyć.
webhook.url_*	Adres URL webhooka nie jest publicznym adresem URL `https`.
*.limit_reached	Osiągnięto limit planu, np. liczbę webhooków na projekt.

Przyczyny niepowodzenia

Dlaczego przetwarzanie dokumentu się nie powiodło: reason w odpowiedzi 422 z POST /extract lub POST /classify, error_code w extraction.failed, errorCode w dokumencie.

Kod	Znaczenie
too_many_pages	Ponad 30 stron. Podziel plik.
sync_too_many_pages	Więcej stron, niż akceptują `POST /extract` i `POST /classify`.
pdf_encrypted	Plik PDF jest chroniony hasłem.
file_unreadable	Plik jest uszkodzony lub nie jest prawidłowym dokumentem.
no_text	Nie znaleziono tekstu: dokument jest pusty lub skan jest nieczytelny.
no_categories	Kategoria miała zostać wybrana automatycznie, ale projekt nie ma kategorii.
no_schema_fields	Kategoria nie ma pól.
no_fields_found	W dokumencie nie znaleziono żadnego z pól kategorii; prawdopodobnie ma niewłaściwą kategorię. Przetwórz go ponownie z właściwą.
no_data_found	Automatyczna ekstrakcja nie znalazła w dokumencie żadnych danych.
insufficient_credits	Dokument wymaga więcej kredytów, niż pozostało w tym okresie. Nic nie zostało naliczone; przetwórz go ponownie po przejściu na wyższy plan lub po odnowieniu kredytów.
refund_pending	Zwrot za subskrypcję był rozpatrywany. Jeśli zostanie odrzucony, przetwórz dokument ponownie.
masking_failed	Nie udało się zamaskować danych osobowych, więc dokument nie został wysłany do modelu AI. Spróbuj ponownie.
worker_unavailable	Przetwarzanie było chwilowo niedostępne. Spróbuj ponownie.
ai_failed	Model AI chwilowo zawiódł. Spróbuj ponownie.
processing_failed	Błąd wewnętrzny. Spróbuj ponownie; jeśli się powtarza, skontaktuj się z pomocą techniczną.
processing_timeout	Przetwarzanie zostało przerwane przed zakończeniem (np. podczas restartu). Spróbuj ponownie.

Ostatnie pięć jest tymczasowych: przetwórz dokument ponownie lub wyślij go jeszcze raz. Za strony nieudanych przebiegów nie są naliczane kredyty.

Odpowiedź400

{
  "error": {
    "code": "validation.failed",
    "message": "The file field is required.",
    "fields": {
      "file": [
        "The file field is required."
      ]
    }
  }
}

Odpowiedź422

{
  "error": {
    "code": "document.sync_failed",
    "message": "The file is damaged or is not a valid PDF, Word document or image.",
    "reason": "file_unreadable",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Limity i kredyty

Pliki

PDF, DOCX, PNG, JPEG i TIFF (także wielostronicowy). Typ jest ustalany na podstawie zawartości pliku, a nie jego nazwy.
Do 10 MB i 30 stron na dokument.

Kredyty

Każda przetworzona strona kosztuje 1 kredyt. Automatyczny wybór kategorii nie kosztuje nic dodatkowo.
Tryb „Tylko klasyfikacja” (classify-only) kosztuje 1 kredyt za dokument. Późniejsza ekstrakcja danych z takiego dokumentu kosztuje tyle kredytów, ile ma on stron, pomniejszone o ten kredyt, więc łącznie nadal jest to 1 kredyt za stronę.
Nieudany przebieg nie kosztuje nic za swoje strony. Ponowne przetwarzanie ponownie kosztuje kredyty. Odbieranie e-maili jest bezpłatne.
Gdy kredyty z danego okresu się wyczerpią, przesyłane dokumenty są odrzucane z credit.insufficient_credits do następnego okresu lub przejścia na wyższy plan. Kredyty dokumentu są rezerwowane, gdy tylko zostaną policzone jego strony; jeśli już się nie mieszczą, np. po wielu równoczesnych przesłaniach, przetwarzanie dokumentu kończy się niepowodzeniem z insufficient_credits i nic nie jest naliczane.

Liczba żądań

Każdy klucz API może wykonać określoną liczbę żądań na minutę, zależną od planu. Każda odpowiedź zawiera X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset (czas uniksowy). Po przekroczeniu limitu otrzymasz 429 z Retry-After.

Według planu

Plan	Żądania / minutę	Kredyty / miesiąc	Klucze API	Webhooki / projekt
Free	10	20	1	1
Starter	30	500	2	2
Growth	60	2000	3	5
Pro	120	6000	10	10
Business	300	20 000	bez limitu	25

Ponadto: POST /extract i POST /classify czekają najdłużej 285 sekund i łącznie dopuszczają 5 otwartych żądań na klucz.

Odpowiedź429

{
  "error": {
    "code": "apikey.rate_limited",
    "message": "Too many requests for this API key: the limit is 60 per minute. Retry in 18 s.",
    "limit": 60,
    "retryAfterSeconds": 18
  }
}

Przechowywanie danych

To, co Parsevix przechowuje z dokumentu przesłanego przez API, zależy od ustawienia projektu: Przesyłanie przez API w sekcji Ustawienia projektu. Domyślnie jest to Usuwaj po przetworzeniu; opcja Przechowuj jak pliki z panelu zachowuje te dokumenty.

Usuwaj po przetworzeniu: plik jest usuwany po zakończeniu przetwarzania, a wynik nie jest zapisywany. Odpowiedź API, webhook lub wywołanie zwrotne to jedyna kopia. Takie dokumenty nie pojawiają się na liście i nie można ich ponownie przetworzyć ani pobrać; retained ma wartość false.
Przechowuj jak pliki z panelu: pliki i wyniki są przechowywane jak dokumenty przesłane z panelu, dopóki ich nie usuniesz.

Dokumenty przesłane z panelu i e-mailem są zawsze przechowywane. Dane osobowe są maskowane, zanim jakikolwiek tekst trafi do modelu AI; zob. Bezpieczeństwo.