Risorse · PDFgine

Caricare una risorsa

Loghi, firme e font vengono caricati una volta e poi richiamati tramite ID. La richiesta è multipart: il file va nel campo file e altText è facoltativo.

Richiesta

curl -X POST https://api.pdfgine.com/api/v1/assets \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -F "file=@logo.png" \
  -F "altText=Logo aziendale"

HTTP 201

{
  "assetId": "ast_985f87e2b22d486db2d6d8bacd29288e",
  "fileName": "logo.png",
  "contentType": "image/png",
  "length": 20184,
  "altText": "Logo aziendale",
  "createdAt": "2026-09-26T15:29:44.8420041+00:00",
  "expiresAt": null,
  "fontEmbedding": null
}

Il tipo viene letto dai primi byte del file, non dal Content-Type inviato: un .png che in realtà è un PDF viene rifiutato. Sono accettati PNG, JPEG, WebP, TTF e OTF, fino a 10 MB per file.

Usarla in un documento

Invia l'ID dove il modello si aspetta un'immagine. Lo stesso campo accetta anche un URI data:, ma una risorsa caricata riduce i dati trasmessi ed è riutilizzabile.

Richiesta

curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "data": { "logo": "ast_985f87e2b22d486db2d6d8bacd29288e" }
      }'

Risorse temporanee, elenco ed eliminazione

Un'immagine necessaria per un solo documento non va eliminata a mano: imposta expiresInMinutes tra 1 e 10080 (sette giorni) e la risorsa si rimuove da sola.

Richiesta

curl -X POST https://api.pdfgine.com/api/v1/assets \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -F "file=@signature.png" \
  -F "expiresInMinutes=60"

# Elenco, contenuto di una risorsa ed eliminazione
curl https://api.pdfgine.com/api/v1/assets -H "X-PDFgine-Key: $PDFGINE_KEY"
curl https://api.pdfgine.com/api/v1/assets/ast_985f87e2b22d486db2d6d8bacd29288e/content \
  -H "X-PDFgine-Key: $PDFGINE_KEY" -o logo.png
curl -X DELETE https://api.pdfgine.com/api/v1/assets/ast_985f87e2b22d486db2d6d8bacd29288e \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

Font e permessi di incorporamento

Un file di font dichiara nei propri bit fsType cosa può farne un documento. PDFgine li legge al caricamento e risponde con fontEmbedding, così conosci il risultato prima di produrre il documento anziché dopo averlo aperto.

`fontEmbedding`	Cosa può fare il documento
`installable`	Nessuna restrizione; incorporato sia in PDF sia in Word.
`editable`	Incorporato sia in PDF sia in Word.
`preview-print`	Incorporato nel PDF. Non incorporato in Word, perché un documento Word è modificabile; Word sostituisce il font.
`restricted`	Non incorporato in alcun formato. Il documento viene comunque prodotto usando un font disponibile al lettore.
`bitmap-only`	È consentito solo l'incorporamento bitmap, non utilizzabile in un documento. Non incorporato.
`unstated`	Il file non dichiara permessi. Viene considerato incorporabile, come richiesto dalla specifica OpenType.

WOFF e WOFF2 vengono rifiutati al caricamento. Non possono essere incorporati in un documento Word e lo stesso modello risulterebbe corretto in PDF e sbagliato in Word: una differenza che noteresti solo dopo aver inviato il documento.

Font integrati

Queste famiglie sono incluse nel prodotto: usale per nome in style.fontFamily e page.defaultFont. Lo stesso carattere va nel PDF, in Word e nell'editor. Un peso mancante non viene rifiutato: viene usato il carattere più vicino.

Famiglia	Gruppo	Pesi	Sistemi di scrittura
`Inter`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Roboto`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Montserrat`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, cyrillic, vietnamese
`Poppins`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin
`DM Sans`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin
`Nunito`	`sans`	200, 300, 400, 500, 600, 700, 800, 900	latin, cyrillic, vietnamese
`Manrope`	`sans`	200, 300, 400, 500, 600, 700, 800	latin, greek, cyrillic, vietnamese
`Noto Sans`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Plus Jakarta Sans`	`sans`	200, 300, 400, 500, 600, 700, 800	latin, vietnamese
`Work Sans`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, vietnamese
`Roboto Condensed`	`condensed`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Oswald`	`condensed`	200, 300, 400, 500, 600, 700	latin, latin-ext, cyrillic, vietnamese
`Noto Serif`	`serif`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`EB Garamond`	`serif`	400, 500, 600, 700, 800	latin, latin-ext, greek, cyrillic, vietnamese
`Newsreader`	`serif`	200, 300, 400, 500, 600, 700, 800	latin, vietnamese
`Literata`	`serif`	200, 300, 400, 500, 600, 700, 800, 900	latin, greek, cyrillic, vietnamese
`Tinos`	`serif`	400, 700	latin, latin-ext, greek, cyrillic, vietnamese
`Rokkitt`	`serif`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, vietnamese
`Inconsolata`	`mono`	200, 300, 400, 500, 600, 700, 800, 900	latin, vietnamese
`Noto Sans Mono`	`mono`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Arial`	`system`	400, 700
`Georgia`	`system`	400, 700

Quando un caricamento viene rifiutato

Ogni rifiuto restituisce 400 con il motivo in errors.file. Mostra quella frase a chi carica il file: indica già cosa fare.

HTTP 400

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "file": ["Carica un font TTF o OTF per usarlo nell'output Word. I file WOFF e WOFF2 non possono essere incorporati in un documento Word."]
  },
  "correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}

Errori →

Gli errori più comuni

Il tipo viene letto dai primi byte, non dal nome del file. Rinominare un PDF in .png non lo rende un'immagine: il caricamento viene rifiutato.
WOFF e WOFF2 vengono rifiutati volutamente. Non possono essere incorporati in Word e lo stesso modello sarebbe corretto in PDF e sbagliato in Word: carica TTF o OTF.
Il caricamento risponde con fontEmbedding. Ignorarlo significa scoprire che il font è stato sostituito solo dopo l'invio del documento.
Un URI data: viaggia con ogni richiesta. Per un logo presente in ogni documento, caricalo una volta e invia l'ID.
Un'immagine per un solo documento non va eliminata a mano. Imposta expiresInMinutes e si rimuove da sola.