Documentazione API

Invii un PDF, un documento Word o un'immagine e riceva JSON strutturato.

Introduzione

I dati che desidera si descrivono come categoria: un elenco di campi, come numero fattura, data o righe della fattura, configurato nella dashboard. Parsevix legge il documento, compila quei campi e li restituisce in JSON, insieme al testo letto e alla posizione in cui è stato trovato ogni valore.

L'API è servita in HTTPS da un unico URL di base. Richieste e risposte sono in JSON, tranne i caricamenti di file, che usano multipart/form-data.

https://parsevix.com/api/v1

Ogni chiave API appartiene a un progetto. Una chiave vede e modifica solo i documenti, le categorie e i webhook di quel progetto.

Oltre a chiamare l'API, può ricevere i risultati tramite webhook, collegare Zapier o inviare documenti all'indirizzo e-mail di un progetto.

Convenzioni

Le risposte dell'API usano nomi di campo in camelCase. I corpi di webhook e callback usano lo snake_case.
I timestamp sono in UTC, in formato ISO 8601 (2026-10-25T10:12:06.791Z).
I messaggi di errore sono in inglese, tedesco, turco, francese, spagnolo, italiano, olandese, polacco o portoghese, in base all'header Accept-Language.

Avvio rapido

1
Creare una chiave API
Nella dashboard apra il progetto, vada su Chiavi API e crei una chiave. Viene mostrata una sola volta: la conservi, ad esempio nella variabile d'ambiente PARSEVIX_API_KEY. Il piano Free include una chiave, i piani a pagamento di più (vedere Limiti e crediti).
2
Definire una categoria
In Categorie crei una categoria per il tipo di documento e aggiunga i campi necessari, oppure parta da un modello predefinito. Gli esempi di questa pagina usano una categoria denominata Supplier invoice.
3
Inviare un documento
POST /extract carica il file e attende il risultato. La risposta contiene i campi compilati in extracted.

Per elaborare molti documenti senza tenere aperte le richieste, li carichi in modo asincrono e riceva i risultati tramite webhook.

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

Risposta200· abbreviato

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

Video tutorial

Cinque brevi video mostrano i passaggi principali nella dashboard e la sua prima richiesta API. Ognuno ha voce e sottotitoli in nove lingue: li scelga dall'icona a forma di ingranaggio nel player.

I video vengono riprodotti da YouTube (youtube-nocookie.com). Finché non fa clic su riproduci, da YouTube non viene caricato nulla; dopo, Google riceve il suo indirizzo IP e può salvare cookie. Veda la nostra Informativa sulla privacy.

Autenticazione

Invii la chiave API nell'header X-API-Key con ogni richiesta.

X-API-Key: psvx_…

Una chiave funziona solo su /api/v1; non consente di accedere alla dashboard. Le chiavi si creano e si revocano in Chiavi API nel progetto. Una chiave revocata smette subito di funzionare.

Conservi le chiavi sul proprio server. Chiunque possieda una chiave può caricare documenti e leggere i risultati del progetto, e i caricamenti consumano i Suoi crediti.

Quando una chiave viene rifiutata

Stato	Codice	Significato
401	`apikey.missing`	Non è stato inviato alcun header `X-API-Key`.
401	`apikey.invalid`	La chiave non esiste o è stata revocata.
403	`apikey.plan_disabled`	Il piano dell'account non include l'accesso all'API.
403	`apikey.paused_by_plan`	La chiave o il suo progetto è sospeso perché il piano dell'account consente meno chiavi o progetti.
403	`apikey.account_unavailable`	L'account è chiuso o ne è stata programmata l'eliminazione.
403	`apikey.project_unavailable`	Il progetto della chiave è stato eliminato.
429	`apikey.too_many_invalid`	Dalla tua rete sono arrivate più di 30 chiavi non valide in 10 minuti. Attendi `Retry-After` secondi; una chiave che ha funzionato di recente non viene bloccata.

Risposta401

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

Modalità di elaborazione

Ogni caricamento viene letto in uno di quattro modi.

Categoria automatica (auto-classify). Parsevix sceglie la categoria del progetto più adatta, poi ne estrae i campi. Si usa quando non invia alcuna categoria, oppure category=auto.
Solo classificazione (classify-only). Parsevix sceglie la categoria più adatta senza estrarre nulla, per ordinare i documenti per tipo. Legge le prime 3 pagine e costa 1 credito per documento. I campi possono essere estratti in seguito. Vedere Classificare un documento.
Categoria specifica (specific). Lei indica la categoria; ne vengono estratti i campi.
Senza schema (auto-entity). Non si usa alcuna categoria. Parsevix restituisce i campi che trova, denominati in base alle etichette del documento stesso. Vedere Estrarre senza schema.

La lingua del documento viene rilevata automaticamente. Il parametro facoltativo language serve solo come ripiego per i documenti con troppo poco testo per il rilevamento.

Estrarre un documento

POST/api/v1/extract

Carica un documento e attende che sia elaborato. La risposta contiene i campi estratti.

filefileobbligatorio: Il documento: PDF, DOCX, PNG, JPEG o TIFF, fino a 10 MB e 30 pagine.
categorystringfacoltativo: Nome di una categoria del progetto. Lo ometta, oppure invii auto, per lasciare la scelta a Parsevix.
languagestringfacoltativo: Codice ISO 639-1 di due lettere, ad esempio de. Usato solo se la lingua non può essere rilevata.

Attesa e limiti

La richiesta resta aperta finché il risultato è pronto, per al massimo 285 secondi. Imposti il timeout del client HTTP oltre questo valore.
Se l'elaborazione richiede più tempo, riceve 504 con document.sync_timeout e il documentId. L'elaborazione prosegue; il risultato viene inviato ai Suoi webhook.
Se l'elaborazione non riesce, riceve 422 con document.sync_failed. reason ne indica il motivo; vedere motivi di errore.
Ogni chiave API può avere 5 richieste aperte contemporaneamente. Quelle in più ricevono 429 con document.sync_concurrency_limit. Una richiesta che chiudi, o che va in timeout, mantiene il suo posto finché il suo documento non è stato elaborato. Per i caricamenti in blocco usi il caricamento asincrono.

Risposta

idstring: ID del documento.
fileNamestring: Il nome del file caricato.
statusstring: Completed.
categorystring | null: La categoria usata; null senza schema.
processingModestring: auto-classify, specific o auto-entity.
confidenceScorenumber: Tra 0 e 1: quanto è affidabile l'estrazione.
pageCountinteger: Pagine elaborate; ciascuna costa un credito.
languagestring: Lingua rilevata, ISO 639-1.
retainedboolean: Indica se Parsevix conserva il file e il risultato. Vedere Conservazione dei dati.
extractedobject: I campi estratti. Vedere Il risultato.

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

Risposta200· abbreviato

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

Risposta422

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

Risposta504

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

Estrarre senza schema

POST/api/v1/extract-auto

Come POST /extract, ma senza categoria: Parsevix restituisce tutti i campi che trova nel documento.

filefileobbligatorio: Il documento: PDF, DOCX, PNG, JPEG o TIFF, fino a 10 MB e 30 pagine.
languagestringfacoltativo: Codice ISO 639-1 di due lettere. Usato solo se la lingua non può essere rilevata.

L'output resta nella lingua del documento. Le chiavi sono le etichette del documento stesso in snake_case (una fattura in tedesco dà rechnungsnummer) e i valori sono copiati così come stampati: le date nel formato del documento, gli importi come stringhe, ad esempio "2.430,09".

Lo usi per esplorare un nuovo tipo di documento. Per i dati che elabora in modo automatico, una categoria offre chiavi fisse e valori normalizzati.

La risposta ha gli stessi campi di POST /extract, con processingMode auto-entity e category null.

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

Classificare un documento

POST/api/v1/classify

Carica un documento e attende che Parsevix abbia scelto una delle categorie del progetto. Non viene estratto alcun campo. Lo usi per ordinare o instradare i documenti per tipo.

Le candidate sono le categorie del progetto, non i modelli predefiniti. Parsevix legge le prime 3 pagine, quindi una classificazione costa 1 credito indipendentemente dalla lunghezza del documento.

filefileobbligatorio: Il documento: PDF, DOCX, PNG, JPEG o TIFF, fino a 10 MB e 30 pagine.
languagestringfacoltativo: Codice ISO 639-1 di due lettere. Usato solo se la lingua non può essere rilevata.

Attesa ed errori funzionano come per POST /extract: al massimo 285 secondi, 504 con document.sync_timeout se richiede più tempo, 422 con document.sync_failed se il documento non può essere elaborato. Le 5 richieste aperte per chiave sono condivise tra i due endpoint.

Risposta

idstring: ID del documento.
fileNamestring: Il nome del file caricato.
statusstring: Completed.
categorystring: La categoria scelta da Parsevix.
processingModestring: classify-only.
pageCountinteger: Pagine del documento. Sono state lette le prime 3.
languagestring: Lingua rilevata, ISO 639-1.
retainedboolean: Indica se Parsevix conserva il file. Solo un documento conservato può essere estratto in seguito.

Estrarre in seguito

POST /documents/{id}/extract estrae i campi del documento, secondo la categoria che gli è stata assegnata o una indicata da Lei. Costa le pagine del documento meno il credito già pagato: un documento di 5 pagine costa altri 4 crediti, 5 in totale.

Serve il file, quindi il progetto deve conservare i caricamenti API (vedere Conservazione dei dati). I documenti inviati dalla dashboard o via e-mail vengono sempre conservati. Anche i caricamenti asincroni possono essere classificati: processingMode=classify-only su POST /documents.

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

Risposta200

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

Caricamento asincrono

POST/api/v1/documents

Mette in coda un documento e risponde subito con 202 e il record del documento. Lo usi per i caricamenti in blocco e per i client che non possono tenere aperta una richiesta, come Zapier.

filefileobbligatorio: Il documento: PDF, DOCX, PNG, JPEG o TIFF, fino a 10 MB e 30 pagine.
categorystringfacoltativo: Nome di una categoria. Lo ometta, oppure invii auto, per lasciare la scelta a Parsevix.
processingModestringfacoltativo: auto-classify, specific, auto-entity o classify-only. Facoltativo: per impostazione predefinita deriva da category. classify-only non può essere combinato con una categoria.
languagestringfacoltativo: Codice ISO 639-1 di due lettere. Usato solo se la lingua non può essere rilevata.
callbackUrlstringfacoltativo: Un URL https pubblico. Parsevix vi invia il risultato una volta, come POST con lo stesso corpo di un evento webhook.

Ottenere il risultato

I webhook del progetto ricevono extraction.completed o extraction.failed. Un caricamento classify-only invia classification.completed invece di extraction.completed.
callbackUrl, se indicato, riceve lo stesso evento, con gli stessi nuovi tentativi. Non è firmato: inserisca un token segreto nell'URL e lo verifichi.
Il polling di GET /documents/{id} mostra lo stato, e il risultato solo se il progetto conserva i caricamenti API (vedere Conservazione dei dati).

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"

Risposta202

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

Il risultato

extracted

Un oggetto le cui chiavi sono i nomi dei campi della categoria (fieldName nello schema della categoria). Oggetti ed elenchi seguono lo schema.

Le date sono nel formato YYYY-MM-DD. I numeri sono numeri JSON, senza simboli di valuta né separatori delle migliaia. Un campo che il documento non contiene è omesso o vale null.

I dati personali, come nomi e IBAN, vengono restituiti così come scritti nel documento. Sono mascherati solo nel percorso verso il modello di IA e ripristinati prima che Lei li riceva.

_field_blocks

Dove è stato trovato ogni valore. Le chiavi sono percorsi di campo come seller.name o line_items[0].total; ogni voce elenca le righe di testo con pagina, riquadro e testo. Un valore che non è stato possibile localizzare non compare. Ignori le chiavi che iniziano con _ se Le servono solo i dati.

Coordinate

PDF e DOCX: punti PDF (1/72 di pollice). L'origine è l'angolo inferiore sinistro della pagina; y è il bordo superiore del riquadro, misurato dal basso.
Immagini: pixel. L'origine è l'angolo superiore sinistro; y è il bordo superiore, misurato dall'alto.

extracted200· abbreviato

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

Documenti

I documenti del progetto, da tutte le origini: la dashboard, l'API e l'e-mail.

Elencare i documenti

GET/api/v1/documents

Dal più recente. Elenca solo i documenti archiviati: i caricamenti API compaiono solo se il progetto li conserva.

pageintegerfacoltativo: Numero di pagina, da 1.
pageSizeintegerfacoltativo: Da 1 a 100; predefinito 20.
statusstringfacoltativo: Pending, Processing, Completed o Failed.
categorystringfacoltativo: Nome della categoria.
searchstringfacoltativo: Parte del nome del file.
fileTypestringfacoltativo: pdf, docx o image.
sourcestringfacoltativo: dashboard, api o email.
processingModestringfacoltativo: auto-classify, specific, auto-entity o classify-only.

Ottenere un documento

GET/api/v1/documents/{id}

Il documento con il suo risultato. outputDeanonymized contiene i dati estratti, lo stesso oggetto di extracted. Un documento classify-only ha la categoria in categoryName e nessun outputDeanonymized. Un documento non riuscito ha errorCode ed errorMessage. Se il progetto non conserva i caricamenti API, lo stato è disponibile ma il risultato no.

Rielaborare un documento

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

Esegue di nuovo l'estrazione, ad esempio dopo aver modificato i campi della categoria. Corpo JSON facoltativo: category (un nome, oppure auto) e processingMode. Risponde 202; il risultato arriva come per un caricamento asincrono. I crediti vengono addebitati di nuovo. Un documento classify-only viene classificato di nuovo (1 credito), a meno che non indichi una categoria. Non è possibile per i caricamenti API i cui file non sono stati conservati (document.files_not_retained).

Estrarre un documento classificato

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

Per un documento caricato con classify-only: ne estrae i campi secondo la categoria assegnata, oppure secondo la category indicata nel corpo JSON facoltativo. Costa le pagine del documento meno il credito pagato per la classificazione. Risponde 202; il risultato arriva come per un caricamento asincrono, come extraction.completed. Per qualsiasi altro documento risponde 400 con document.not_classify_only; usi invece la rielaborazione.

Eliminare un documento

DELETE/api/v1/documents/{id}

Elimina il documento, il suo file e i suoi risultati. Risponde 204.

Un ID che non esiste nel progetto della chiave restituisce 404 con document.not_found.

cURL

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

Risposta200· abbreviato

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

Risposta200· abbreviato

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

Risposta202

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

Categorie

Le categorie del progetto, compresi i modelli predefiniti (isGlobal: true). Le categorie si creano e si modificano nella dashboard.

Elencare le categorie

GET/api/v1/categories

Ottenere lo schema di una categoria

GET/api/v1/categories/{name}

I campi che una categoria estrae. fieldName è la chiave in extracted. fieldType è string, number, date, boolean, object o array; oggetti e array hanno i loro campi in children. Il nome nel percorso non distingue tra maiuscole e minuscole.

cURL

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

Risposta200· abbreviato

[
  {
    "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"

Risposta200· abbreviato

{
  "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": []
        }
      ]
    }
  ]
}

Chiave e crediti

GET/api/v1/me

Il progetto della chiave e il saldo crediti dell'account. I crediti appartengono all'account e sono condivisi da tutti i suoi progetti; resetsOn è l'inizio del periodo successivo. Con un piano annuale il periodo è l'anno di fatturazione e monthlyLimit contiene i crediti dell'intero anno.

cURL

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

Risposta200

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

Gestire i webhook

I webhook possono essere gestiti nella dashboard (Webhook) o tramite questi endpoint.

Creare un webhook

POST/api/v1/webhooks

urlstringobbligatorio: Un URL https pubblico. Gli indirizzi di reti private vengono rifiutati.
eventsstring[]obbligatorio: Uno o più tra extraction.completed, extraction.failed e classification.completed.
filtersobjectfacoltativo: Facoltativo. sources (dashboard, api, email) e categories (nomi) limitano i documenti che inviano eventi.

La risposta contiene una sola volta il secret di firma. Lo conservi per verificare le firme.

Elencare i webhook

GET/api/v1/webhooks

Eliminare un webhook

DELETE/api/v1/webhooks/{id}

Eventi di esempio

GET/api/v1/webhooks/samples

Gli ultimi documenti del progetto come corpi di evento, per testare il Suo ricevitore. Parametri: event (obbligatorio), limit (1–10, predefinito 3), category. Se non esiste ancora un documento di questo tipo, viene creato un esempio a partire dallo schema della categoria.

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

Risposta201

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

Webhook

Quando un documento è terminato, Parsevix invia un POST con un corpo JSON a ciascun webhook del progetto. I webhook ricevono i documenti da tutte le origini: dashboard, API ed e-mail.

Eventi

Evento	Descrizione
extraction.completed	Un documento è stato elaborato. `data` contiene i campi estratti.
classification.completed	Un documento `classify-only` ha ricevuto la sua categoria: `document.category`, con le pagine del documento in `document.page_count`. Non c'è `data`.
extraction.failed	Un documento non è stato elaborato, anche se `classify-only`. `error_code` è uno dei motivi di errore; `error` è il messaggio mostrato nella dashboard.
test.ping	Inviato dal pulsante Test nella pagina di un webhook nella dashboard.

Header

Header	Descrizione
X-Webhook-Id	ID dell'evento. Uguale in ogni tentativo; lo usi per ignorare i duplicati. È anche l'`id` del corpo.
X-Webhook-Event	Il nome dell'evento.
X-Webhook-Timestamp	Ora Unix di questo tentativo, in secondi.
X-Webhook-Signature	`sha256=` seguito dall'HMAC-SHA256 esadecimale di `{timestamp}.{raw body}`, calcolato con il secret del webhook.
X-Webhook-Attempt	Numero del tentativo, da 1.

Verificare la firma

Calcoli l'HMAC sul corpo grezzo della richiesta esattamente come ricevuto, prima di analizzarlo. Rifiuti gli eventi il cui timestamp ha più di 5 minuti.

Rispondere

Risponda con uno stato 2xx entro 10 secondi, poi elabori l'evento. Qualsiasi altra risposta conta come errore. I reindirizzamenti non vengono seguiti.
Le consegne non riuscite vengono ritentate dopo 1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore e 24 ore: 7 tentativi in circa 33 ore.
Rispondere 410 Gone disattiva subito il webhook. Viene disattivato anche quando tre eventi hanno esaurito i tentativi senza successo e nessuna consegna è riuscita da 3 giorni. Il proprietario riceve un'e-mail; lo riattivi nella dashboard. Gli eventi intercorsi non vengono reinviati.
Il secret può essere rinnovato nella dashboard. Il vecchio secret smette subito di funzionare.

extraction.completed200· abbreviato

{
  "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  # più vecchio di 5 minuti: forse riprodotto
    expected = hmac.new(
        secret.encode(),
        timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, "sha256=" + expected)

Zapier

L'app Parsevix per Zapier si collega con una chiave API di un progetto. La aggiunga tramite il link di invito nella pagina Zapier del progetto nella dashboard oppure qui.

Trigger

Extraction Completed: un documento è stato elaborato. Facoltativamente solo una categoria o un'origine.
Extraction Failed: un documento non è stato elaborato.
Document Classified: un documento inviato solo per essere classificato ha ricevuto la sua categoria, ad esempio da un indirizzo e-mail impostato su solo classificazione.

Azioni

Extract Document invia un file da un passaggio precedente, facoltativamente con una categoria, e passa i campi estratti ai passaggi successivi. Se è scelta una categoria, i suoi campi possono essere mappati durante la creazione dello Zap.
Classify Document invia un file e passa ai passaggi successivi la categoria scelta da Parsevix, senza estrarre campi. Lo usi per instradare i documenti per tipo.

Gli Zap che attiva compaiono nella pagina Zapier del progetto e in Webhook.

E-mail

Dal piano Starter in su, ogni progetto ha un indirizzo e-mail in Casella e-mail. Ogni allegato di un'e-mail inviata a quell'indirizzo diventa un documento; i risultati compaiono nella dashboard e vengono inviati ai Suoi webhook con origine email.

Gli indirizzi hanno la forma name+inbox@inbox.parsevix.com. A seconda del piano, un progetto può averne più di uno, ad esempio uno per fornitore o per reparto.

Per indirizzo

Allegati: estrarre ogni allegato secondo una categoria fissa; lasciare che Parsevix scelga la categoria, poi estrarre; oppure solo scegliere la categoria (classify-only, 1 credito per documento), con i campi estratti in seguito se servono.
Mittenti consentiti: viene accettata solo la posta da questi domini, e solo se supera DKIM o SPF per quel dominio, quindi un mittente falsificato viene rifiutato.

Cosa viene elaborato

Allegati PDF, DOCX, PNG, JPEG e TIFF, compresi quelli all'interno di e-mail inoltrate. Le immagini mostrate nel corpo dell'e-mail, come i loghi nelle firme, vengono ignorate.
Un'e-mail può pesare fino a 30 MB e i suoi primi 20 allegati diventano documenti. Un indirizzo accetta fino a 1.000 e-mail e crea fino a 1.000 documenti in 24 ore; oltre, la posta viene rifiutata e gli allegati risultano non importati. La ricezione è gratuita; ogni documento costa crediti come qualsiasi altro.
La stessa e-mail consegnata due volte (stesso Message-ID) viene elaborata una sola volta.

Errori

Gli errori hanno uno stato HTTP e un corpo con un code stabile e un message leggibile. Basi la logica su code; i messaggi possono cambiare.

Codici di stato

Stato	Significato
400	La richiesta non è valida: un parametro mancante o errato, un file non supportato, crediti insufficienti. `validation.failed` elenca i problemi per parametro in `fields`.
401	Nessuna chiave API, oppure una chiave non valida.
403	La chiave è valida ma non può essere usata. Vedere Autenticazione.
404	Il documento, la categoria, il webhook o l'endpoint non esiste in questo progetto.
413	Il caricamento supera il limite di dimensione della richiesta.
422	`POST /extract` o `POST /classify` è stato eseguito, ma il documento non è stato elaborato.
429	Raggiunto il limite di frequenza o di richieste simultanee. Attenda `Retry-After` secondi.
5xx	Un errore del server (con un riferimento da comunicare all'assistenza), una manutenzione (`503`) o un timeout (`504`).

Codici comuni

Codice	Significato
validation.file_required	Non è stato inviato alcun `file`.
document.content_not_supported	Il contenuto del file non è PDF, DOCX, PNG, JPEG o TIFF, qualunque sia il suo nome.
credit.file_size_exceeds_plan	Il file supera la dimensione consentita dal piano.
validation.language_invalid	`language` non è un codice di due lettere.
document.callback_url_*	`callbackUrl` non è un URL `https` pubblico di al massimo 2.000 caratteri.
credit.insufficient_credits	Crediti rimanenti insufficienti per questo periodo.
document.refund_pending	Un rimborso dell'abbonamento è in fase di verifica; non viene elaborato nulla finché non è definito.
category.not_found	Nessuna categoria con questo nome nel progetto.
document.classify_only_category	`classify-only` è stato inviato insieme a una categoria. Questa modalità sceglie da sé la categoria.
document.not_classify_only	`POST /documents/{id}/extract` è stato chiamato per un documento non caricato con `classify-only`.
document.files_not_retained	I file del caricamento API non sono stati conservati, quindi non può essere rielaborato.
webhook.url_*	L'URL del webhook non è un URL `https` pubblico.
*.limit_reached	È stato raggiunto un limite del piano, ad esempio il numero di webhook per progetto.

Motivi di errore

Perché un documento non è riuscito: reason nella risposta 422 di POST /extract o POST /classify, error_code in extraction.failed, errorCode sul documento.

Codice	Significato
too_many_pages	Più di 30 pagine. Divida il file.
sync_too_many_pages	Più pagine di quante ne accettino `POST /extract` e `POST /classify`.
pdf_encrypted	Il PDF è protetto da password.
file_unreadable	Il file è danneggiato o non è un documento valido.
no_text	Non è stato trovato alcun testo: pagina vuota o scansione illeggibile.
no_categories	La categoria doveva essere scelta automaticamente, ma il progetto non ha categorie.
no_schema_fields	La categoria non ha campi.
no_fields_found	Nessuno dei campi della categoria è stato trovato nel documento; probabilmente è nella categoria sbagliata. Lo rielabori con quella corretta.
no_data_found	L'estrazione automatica non ha trovato dati nel documento.
insufficient_credits	Il documento richiede più crediti di quelli rimasti in questo periodo. Non è stato addebitato nulla; lo rielabori dopo il passaggio a un piano superiore o il rinnovo dei crediti.
refund_pending	Un rimborso dell'abbonamento era in fase di verifica. Se viene respinto, rielabori il documento.
masking_failed	Non è stato possibile mascherare i dati personali, quindi il documento non è stato inviato al modello di IA. Riprovi.
worker_unavailable	L'elaborazione era temporaneamente non disponibile. Riprovi.
ai_failed	Il modello di IA ha avuto un errore temporaneo. Riprovi.
processing_failed	Un errore interno. Riprovi; se si ripete, contatti l'assistenza.
processing_timeout	L'elaborazione si è interrotta prima di terminare (ad esempio durante un riavvio). Riprovi.

Gli ultimi cinque sono temporanei: rielabori il documento o lo invii di nuovo. Le esecuzioni non riuscite non vengono addebitate per pagina.

Risposta400

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

Risposta422

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

Limiti e crediti

File

PDF, DOCX, PNG, JPEG e TIFF (anche multipagina). Il tipo è determinato dal contenuto del file, non dal suo nome.
Fino a 10 MB e 30 pagine per documento.

Crediti

Ogni pagina elaborata costa 1 credito. La scelta automatica della categoria non costa nulla in più.
La sola classificazione (classify-only) costa 1 credito per documento. Estrarre in seguito un documento di questo tipo costa le sue pagine meno quel credito, quindi il totale resta di 1 credito per pagina.
Un'esecuzione non riuscita non costa nulla per le sue pagine. La rielaborazione costa di nuovo crediti. La ricezione di e-mail è gratuita.
Quando i crediti di un periodo sono esauriti, i caricamenti vengono rifiutati con credit.insufficient_credits fino al periodo successivo o al passaggio a un piano superiore. I crediti di un documento vengono riservati appena le sue pagine sono contate; se non bastano più, ad esempio dopo molti caricamenti in parallelo, il documento non riesce con insufficient_credits e non viene addebitato nulla.

Frequenza delle richieste

Ogni chiave API può effettuare un certo numero di richieste al minuto, a seconda del piano. Ogni risposta contiene X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (ora Unix). Oltre il limite riceve 429 con Retry-After.

Per piano

Piano	Richieste / minuto	Crediti / mese	Chiavi API	Webhook / progetto
Free	10	20	1	1
Starter	30	500	2	2
Growth	60	2000	3	5
Pro	120	6000	10	10
Business	300	20.000	illimitati	25

Inoltre: POST /extract e POST /classify attendono al massimo 285 secondi e consentono insieme 5 richieste aperte per chiave.

Risposta429

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

Conservazione dei dati

Cosa Parsevix conserva di un caricamento API è un'impostazione del progetto: Caricamenti API, in Impostazioni progetto. Per impostazione predefinita è selezionato Elimina dopo l'elaborazione; Conserva come i caricamenti dalla dashboard li conserva.

Elimina dopo l'elaborazione: il file viene eliminato al termine dell'elaborazione e il risultato non viene archiviato. La risposta dell'API, il webhook o il callback è l'unica copia. Questi documenti non vengono elencati e non possono essere rielaborati né scaricati; retained è false.
Conserva come i caricamenti dalla dashboard: file e risultati vengono archiviati, finché non li elimina.

I caricamenti dalla dashboard e via e-mail vengono sempre archiviati. I dati personali vengono mascherati prima che qualsiasi testo raggiunga il modello di IA; vedere Sicurezza.