` | nessuno | Allowlist e denylist regex, massimo 50 ciascuna. La denylist viene applicata per seconda. |
| `sameDomainOnly`, `respectRobots` | `boolean` | `true`, nessuno | Resta sul dominio seed, e rispetta le regole robots del sito. |
### Lookup
Ricerca web categorizzata, con rendering automatico opzionale dei risultati migliori. Riferimento dell'endpoint: [Lookup](/it/docs/v2-lookup).
```java
LookupResult search = client.v2.lookup("best static site generators",
LookupOptions.builder()
.category("web") // web, news, images, scholar, patents, maps
.numResults(10)
.country("us")
.timeFilter("month") // hour, day, week, month, year
.perceiveTop(3) // renderizza automaticamente i 3 risultati migliori
.build());
search.results().forEach(hit -> {
System.out.println(hit.position() + " " + hit.title() + " " + hit.url());
if (hit.perceive() != null) System.out.println(" quality " + hit.perceive().renderQuality());
});
```
Con `perceiveTop` maggiore di 0 (da 0 a 10, predefinito 0), gli URL dei primi N risultati vengono renderizzati tramite perceive e ogni risultato porta inline il suo `PerceiveResult` completo su `hit.perceive()`. `numResults` va da 1 a 100 e vale 10 per impostazione predefinita; `page` va da 1 a 10.
### Distill
Estrazione strutturata guidata da schema su una o più pagine. Riferimento dell'endpoint: [Distill](/it/docs/v2-distill).
```java
DistillResult extraction = client.v2.distill(
DistillOptions.builder(Map.of("products", "list of product names with their listed price"))
.urls(List.of("https://example.com/catalog"))
.cssSchema(CssSchema.builder(".product-card", List.of(
CssField.builder("name", "text").selector("h3").build(),
CssField.builder("price", "text").selector(".price").build()))
.targetField("products")
.build())
.build());
extraction.results().forEach(item ->
System.out.println(item.data() + " via " + item.extractionTier()));
```
Il `cssSchema` opzionale esegue prima un passaggio CSS gratuito; solo i campi a cui non riesce a rispondere passano al livello LLM, e `item.extractionTier()` riporta quale percorso ha prodotto il record (`css`, `llm`, `mixed` oppure `none`). Puoi anche individuare prima gli URL invece di elencarli:
```java
client.v2.distill(
DistillOptions.builder(Map.of("title", "page title", "summary", "one-line summary"))
.discoverFrom(new DistillDiscoverFrom("https://example.com", "sitemap", 10))
.build());
```
Esattamente uno tra `urls` (massimo 50) e `discoverFrom` deve essere impostato, e `schema` è richiesto dalla factory del builder. Entrambe le regole vengono verificate lato client e generano `IllegalArgumentException` prima che parta qualsiasi richiesta.
### Ingest
Trasforma un intero sito, o un insieme di documenti caricati, in JSONL suddiviso in chunk e pronto per il RAG attraverso un'unica pipeline. Ingest è sempre asincrono. Riferimento dell'endpoint: [Ingest](/it/docs/v2-ingest).
```java
// Da un sito
IngestJob job = client.v2.ingest(IngestOptions.builder()
.mode("sitemap") // "urls" (predefinito), "sitemap", "crawl"
.url("https://docs.example.com")
.maxPages(100)
.chunk(new IngestChunkOptions(512, 1)) // maxWords, sentenceOverlap
.webhookUrl("https://my.app/hooks/enconvert")
.build());
// Oppure da file caricati
IngestJob fileJob = client.v2.ingestFiles(
List.of(new FileInput(Files.readAllBytes(Path.of("handbook.pdf")), "handbook.pdf"),
new FileInput(Files.readAllBytes(Path.of("notes.docx")), "notes.docx")),
IngestFilesOptions.builder().chunk(new IngestChunkOptions(512, 1)).build());
// Esegui il polling per il JSONL
IngestJob status = client.v2.getIngestJob(job.jobId());
if ("completed".equals(status.status())) {
System.out.println(status.outputUrl() + " (" + status.totalChunks() + " chunks)");
}
client.v2.listIngestJobs(V2ListOptions.builder().limit(20).build());
client.v2.cancelIngestJob(job.jobId()); // idempotente
```
`ingestFiles` accetta PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT e MD, oltre ai formati office legacy e ODF. Il chunking usa per impostazione predefinita 512 parole (da 32 a 4000) con 1 frase di sovrapposizione (da 0 a 10). `mode` vale `urls` per impostazione predefinita, il che richiede un elenco `urls` non vuoto e vieta `url`; ogni altra modalità richiede un `url` seed e vieta `urls`. L'SDK verifica quell'abbinamento prima dell'invio.
I webhook di completamento sono firmati con HMAC. Recupera il secret e i nomi degli header che ti servono per verificare una consegna, ruotalo quando trapela e rispedisci una consegna che il tuo endpoint ha perso:
```java
WebhookSecret secret = client.v2.getWebhookSecret();
System.out.println(secret.signatureHeader() + " " + secret.signatureScheme());
client.v2.rotateWebhookSecret(); // le vecchie firme smettono subito di essere valide
WebhookRetryResult retry = client.v2.retryIngestWebhook(job.jobId());
System.out.println(retry.delivered() + " after " + retry.attempts() + " attempts");
```
### Watch
Monitoraggio ricorrente delle modifiche su un URL, con notifica via email e webhook. Riferimento dell'endpoint: [Watch](/it/docs/v2-watch).
```java
Watcher watcher = client.v2.createWatcher("https://example.com/pricing",
WatchCreateOptions.builder()
.frequencyMinutes(60) // da 60 a 43200, minimo orario
.diffMode("auto") // auto, text, structured, tables, metadata
.webhookUrl("https://my.app/hooks/changes")
.notifyEmail(true)
.build());
WatcherSnapshotList history = client.v2.getWatcherSnapshots(watcher.watcherId(),
SnapshotListOptions.builder().limit(10).build());
history.snapshots().forEach(s ->
System.out.println(s.checkedAt() + " changed=" + s.hasChanges()
+ " similarity=" + s.similarity()));
client.v2.updateWatcher(watcher.watcherId(), WatcherUpdate.builder().status("paused").build());
client.v2.updateWatcher(watcher.watcherId(), WatcherUpdate.builder().webhookUrl("").build());
client.v2.deleteWatcher(watcher.watcherId()); // soft delete, idempotente
```
`listWatchers()` e `getWatcher(watcherId)` li rileggono. `updateWatcher` richiede almeno un campo e altrimenti genera `IllegalArgumentException`. Una stringa vuota esplicita per `webhookUrl` cancella il webhook, mentre lasciarlo null significa che non cambia nulla. `deleteWatcher` è una cancellazione soft: restituisce il watcher marcato come eliminato con stato `deleted`, e un watcher eliminato viene poi letto come `404`.
I diff degli snapshot contengono contenuto di pagina non attendibile. WatcherSnapshot.changes() è testo grezzo prelevato dalla pagina monitorata. Effettuane l'escape prima di renderizzarlo in una dashboard, in un'email o in un messaggio di chat.
---
## Opzioni PDF
`PdfOptions` è condiviso da `convertUrlToPdf`, `convertWebsiteToPdf`, `convertDocument`, `convertToPdf` e `PerceiveOptions.pdfOptions`.
```java
client.convertUrlToPdf("https://internal.example.com/report",
UrlToPdfOptions.builder()
.pdfOptions(PdfOptions.builder()
.pageSize("A4")
.orientation("landscape")
.margins(new PdfMargins(10.0, 10.0, 15.0, 15.0))
.scale(0.9)
.header(new PdfHeaderFooter("Quarterly Report", 15.0))
.footer(new PdfHeaderFooter("Confidential", 12.0))
.build())
.auth(new HttpBasicAuth("user", "pass"))
.cookies(List.of(BrowserCookie.builder("session", "abc123").domain("internal.example.com").build()))
.headers(Map.of("X-Tenant", "acme"))
.saveTo("report.pdf")
.build());
```
| Campo | Tipo | Descrizione |
|-------|------|-------------|
| `pageSize` | `String` | `"A4"`, `"A3"`, `"Letter"`, `"Legal"` e simili. |
| `pageWidth`, `pageHeight` | `double` | Dimensioni personalizzate. Impostati insieme, hanno la precedenza su `pageSize`. |
| `orientation` | `String` | `"portrait"` oppure `"landscape"`. |
| `margins` | `PdfMargins` | Record di `top`, `bottom`, `left`, `right`. Qualsiasi campo null viene omesso. |
| `scale` | `double` | Scala di rendering, ad esempio `0.9` per il 90 percento. |
| `grayscale` | `boolean` | Post-elabora il PDF in scala di grigi. |
| `header`, `footer` | `PdfHeaderFooter` | Record di `content` (massimo 2000 caratteri) e `height`. |
`BrowserCookie` richiede un nome e un valore più `domain` oppure `url`; quando `domain` è impostato senza `path`, l'API imposta `path` a `/` per impostazione predefinita. Non combinare `auth` con un header `Authorization` esplicito, perché l'API rifiuta il conflitto.
---
## Gestione degli errori
Ogni eccezione dell'SDK estende `EnconvertException`, che a sua volta estende `RuntimeException`, quindi nulla impone una clausola `throws` sui tuoi punti di chiamata. Cattura prima le sottoclassi specifiche.
```java
try {
client.convertUrlToPdf("https://example.com");
} catch (AuthenticationException e) {
System.err.println("Invalid or missing API key");
} catch (QuotaException e) {
System.err.println("Request refused with 402: " + e.getMessage());
} catch (RateLimitException e) {
System.err.println("Too many requests, back off and retry");
} catch (ApiException e) {
System.err.println("API error [" + e.getStatusCode() + "]: " + e.getMessage());
}
```
| Classe | Generata per | Codice di stato |
|-------|-----------|-------------|
| `AuthenticationException` | Chiave API mancante, non valida o non autorizzata | `401`, `403` |
| `QuotaException` | HTTP 402 | `402` |
| `RateLimitException` | Troppe richieste | `429` |
| `ApiException` | Qualsiasi altra risposta 4xx o 5xx | il codice effettivo |
| `EnconvertException` | Classe base, generata anche in caso di errore di trasporto, richiesta interrotta o file di input illeggibile | nessuno |
La validazione lato client (una coppia di conversione non supportata, uno schema distill mancante, un aggiornamento watcher vuoto, il numero sbagliato di output per `perceiveDirect`) genera `IllegalArgumentException` prima che venga inviata qualsiasi richiesta. La mappa dei messaggi per le risposte del server si trova nel riferimento [Codici di errore](/it/docs/error-codes).
---
## Recupero dei timeout
I rendering di URL lunghi e le conversioni di documenti di grandi dimensioni possono superare il timeout del reverse proxy anche quando la conversione stessa alla fine riesce. L'SDK gestisce il caso in modo trasparente:
1. Prima di ogni richiesta con URL singolo o upload di file, l'SDK genera un UUID e lo invia come `job_id`.
2. Se la richiesta torna con 5xx, l'SDK passa al polling di `GET /v1/convert/status/{jobId}` ogni 3 secondi.
3. Su `success` restituisce il risultato. Su `failed` genera `ApiException` con il messaggio di errore del server.
4. Il limite di tempo per il polling è di 5 minuti. Superato quello, genera `ApiException(504, "Conversion timed out")`.
Non devi scrivere codice per questo. Se una risposta riuscita omette `job_id`, l'SDK reinserisce l'id che ha generato, così `result.jobId()` è sempre utilizzabile con `getJobStatus`.
Gli invii batch dei siti web sono esclusi di proposito. convertWebsiteToPdf e convertWebsiteToScreenshot non hanno una riga per singolo job da interrogare, quindi un 5xx in quel punto significa che l'invio stesso è fallito e viene riportato direttamente. Nemmeno gli endpoint V2 usano il polling dei job: i loro flussi asincroni passano da getPerceiveBatch e getIngestJob.
---
## Configurazione
```java
Enconvert client = Enconvert.builder(System.getenv("ENCONVERT_API_KEY"))
.baseUrl("https://api.enconvert.com")
.timeout(Duration.ofSeconds(300))
.build();
```
Sono disponibili tre costruttori come scorciatoia: `new Enconvert(apiKey)`, `new Enconvert(apiKey, baseUrl)` e `new Enconvert(apiKey, baseUrl, timeout)`.
| Opzione | Tipo | Predefinito | Descrizione |
|--------|------|---------|-------------|
| `apiKey` | `String` | obbligatorio | Chiave API privata. Un valore null o vuoto genera `IllegalArgumentException`. |
| `baseUrl` | `String` | `https://api.enconvert.com` | URL base dell'API. Gli slash finali vengono rimossi. |
| `timeout` | `Duration` | 300 secondi | Applicato sia come timeout di connessione sia come timeout per singola richiesta. |
La chiave viaggia nell'header `X-API-Key`. Gli URL di download presigned vengono recuperati senza di essa, dato che sono già firmati. I tipi di chiave sono trattati in [Autenticazione](/it/docs/authentication); crea e gestisci le chiavi nella [dashboard](/it/dashboard).
Non inserire mai la chiave API direttamente nel codice. Leggila da una variabile d'ambiente o dal tuo secret manager. L'SDK è solo lato server: una chiave privata non deve finire dentro un artefatto desktop o mobile che un utente può aprire.
---
## Struttura del risultato
Ogni conversione di un singolo file o di un singolo URL restituisce lo stesso record:
```java
public record ConversionResult(
String presignedUrl,
String objectKey,
String filename,
Long fileSize,
Double conversionTimeSeconds,
String jobId) {}
```
L'URL presigned ha una durata limitata. Passa `saveTo` (oppure recupera l'URL tu stesso) e archivia i byte nel tuo bucket se ti servono oltre quella durata.
Gli altri record di risposta che toccherai più spesso:
| Record | Accessori principali |
|--------|---------------|
| `JobStatus` | `status()` (`processing`, `success`, `failed`), `presignedUrl()`, `objectKey()`, `error()` |
| `BatchStatus` | `status()`, `total()`, `completed()`, `failed()`, `inProgress()`, `zipDownloadUrl()`, `items()` |
| `PerceiveResult` | `operationId()`, `renderQuality()`, `statusCode()`, `deductions()`, `outputs()`, `structured()`, `cacheHit()`, `warnings()` |
| `V2OutputArtifact` | `url()`, `objectKey()`, `sizeBytes()`, `contentType()`, `expiresIn()` |
| `PerceiveDirectResult` | `content()`, `contentType()`, `filename()`, `renderQuality()`, `contentHash()` |
| `IngestJob` | `jobId()`, `status()`, `pagesProcessed()`, `totalChunks()`, `outputUrl()`, `webhookDelivered()` |
| `Watcher` | `watcherId()`, `status()`, `frequencyMinutes()`, `checksCount()`, `nextCheckAt()`, `lastChangeAt()` |
I campi la cui forma è definita dalla tua richiesta (`structured`, `data`, `trackFields`, `changes` degli snapshot) sono esposti come `JsonObject` di Gson e passano intatti. Le enumerazioni con valori stringa restano `String` invece di diventare costanti `enum` Java, così un valore API più recente non rompe mai la deserializzazione su una build più vecchia dell'SDK. `com.enconvert.model.v2.V2Enums` contiene ogni valore accettato come costante a prova di refuso.
---
## Sorgente e problemi
- **Maven Central:** `com.enconvert:enconvert-sdk:0.0.1`
- **GitHub:** [conversionapi/java-sdk](https://github.com/conversionapi/java-sdk)
- **Licenza:** MIT
- **Altri client:** [tutti gli SDK](/it/docs/sdks) · [riferimento degli endpoint](/it/docs/endpoints-overview) · [prezzi](/it/pricing)
---
## Domande frequenti
### Come converto i file in Java con una dipendenza Maven?
Aggiungi `com.enconvert:enconvert-sdk:0.0.1` al tuo `pom.xml` oppure al `build.gradle`, costruisci un client con `new Enconvert(System.getenv("ENCONVERT_API_KEY"))` e chiama un metodo tipizzato come `convertUrlToPdf`, `convertImage`, `convertDocument` oppure `convertToPdf`. Passa `saveTo` sul builder delle opzioni per scrivere l'output direttamente su disco invece di gestire tu stesso l'URL presigned.
### Come converto un URL in PDF in Java?
Chiama `client.convertUrlToPdf(url, UrlToPdfOptions.builder().saveTo("page.pdf").build())`. Imposta `singlePage(false)` per paginare usando `pdfOptions.pageSize` invece di produrre una singola pagina continua, e passa `auth`, `cookies` oppure `headers` per una pagina protetta da login.
### Come converto DOCX in PDF in Java?
Chiama `client.convertDocument(Path.of("report.docx"), ConvertDocumentOptions.builder().saveTo("report.pdf").build())`. Il formato di output predefinito è `pdf`, quindi imposti `outputFormat` solo quando vuoi qualcos'altro, per esempio `yaml` da un input `.json`. Per i formati senza una coppia dedicata, come EPUB o RTF, usa `convertToPdf`.
### Come converto HEIC in WebP in Java?
Chiama `client.convertImage(Path.of("photo.heic"), ConvertImageOptions.builder("webp").saveTo("photo.webp").build())`. Il formato di input viene ricavato dall'estensione del file e il formato di output è l'argomento obbligatorio del builder. `jpeg`, `png`, `svg`, `heic` e `webp` si convertono tutti tra loro, e `pdf` viene rasterizzato in `jpeg`. Su questo client non esiste un metodo di compressione sul posto.
### Come estraggo una pagina web in Markdown pulito da Java?
Ci sono due strade. `client.convertUrlToMarkdown(url, ...)` restituisce Markdown in stile GitHub Flavored con frontmatter YAML come file scaricabile. `client.v2.perceive(url, PerceiveOptions.builder().outputs(List.of("markdown")).build())` restituisce lo stesso contenuto come artefatto pronto per gli agenti, con un punteggio `renderQuality`, opzioni di estrazione e controllo della cache. Usa perceive quando una lettura difettosa deve essere rilevabile invece che silenziosa.
### Che cos'è renderQuality e perché ogni lettura ne ha uno?
`renderQuality` è un punteggio da 0.0 a 1.0 associato a ogni rendering V2. Un punteggio alto significa che la pagina è stata renderizzata in modo pulito; un punteggio basso significa che qualcosa si è messo in mezzo, per esempio una challenge anti-bot, un cookie wall, una schermata di login, una pagina di errore HTTP o uno shell SPA vuoto. Il contenuto viene comunque restituito, con `warnings()` e `deductions()` popolati, così la tua pipeline può scartare o ripetere la lettura invece di dare in pasto a un modello una pagina di challenge come se fosse l'articolo.
### Come trasformo un sito di documentazione in chunk pronti per il RAG in Java?
Chiama `client.v2.ingest(IngestOptions.builder().mode("sitemap").url("https://docs.example.com").maxPages(100).chunk(new IngestChunkOptions(512, 1)).build())`. Il job è asincrono, quindi puoi interrogare `getIngestJob(jobId)` finché lo stato non è `completed` e leggere `outputUrl()` per il JSONL, oppure impostare `webhookUrl` e verificare la firma HMAC con il secret restituito da `getWebhookSecret()`. Per documenti locali invece di un sito, usa `ingestFiles`.
### Come gestisce l'SDK le conversioni che superano il timeout del proxy?
Prima di ogni richiesta con URL singolo o upload di file genera un UUID e lo invia come `job_id`. Se la richiesta restituisce 5xx, interroga `GET /v1/convert/status/{jobId}` ogni 3 secondi finché il job non riporta `success` oppure `failed`, con un limite di 5 minuti oltre il quale genera `ApiException(504, "Conversion timed out")`. Gli invii batch di interi siti sono esclusi, perché non hanno una riga per singolo job da interrogare.
### Quale versione di Java richiede l'SDK e che cosa porta con sé?
Java 17 o versioni successive. L'HTTP passa dal `java.net.http.HttpClient` del JDK, e Gson è l'unico artefatto di terze parti sul classpath. Le risposte sono record Java, quindi uno `switch` moderno o un pattern match su di esse funziona come previsto. Il client è thread safe: tieni una sola istanza e condividila.