Recursos · PDFgine

Subir un recurso

Los logotipos, las firmas y las fuentes se suben una sola vez y luego se referencian por ID. La solicitud es multipart; el archivo va en un campo llamado file y altText es opcional.

Solicitud

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

HTTP 201

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

El tipo se detecta a partir de los primeros bytes del archivo, no del Content-Type enviado: se rechaza un .png que en realidad sea un PDF. Se admiten PNG, JPEG, WebP, TTF y OTF, con un máximo de 10 MB por archivo.

Usarlo en un documento

Envía el ID donde la plantilla espere una imagen. El mismo campo también admite un URI data:, pero un recurso subido ocupa menos en la transferencia y se puede reutilizar.

Solicitud

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

Recursos temporales, listado y eliminación

Una imagen necesaria para un solo documento no tiene que eliminarse a mano: indica expiresInMinutes entre 1 y 10080 (siete días) y el recurso se eliminará automáticamente.

Solicitud

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

# Listado, contenido de un recurso y eliminación
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"

Fuentes y permisos de incrustación

El propio archivo de fuente indica mediante sus bits fsType qué puede hacer un documento con ella. PDFgine los lee al subirla y responde con fontEmbedding, por lo que conocerás los permisos antes de generar el documento y no después de abrirlo.

`fontEmbedding`	Qué puede hacer el documento
`installable`	Sin restricciones; se incrusta en PDF y Word.
`editable`	Se incrusta en PDF y Word.
`preview-print`	Se incrusta en el PDF. No se incrusta en Word porque un documento Word puede editarse; Word sustituye la fuente.
`restricted`	No se incrusta en ningún formato. El documento se genera igualmente y se utiliza la fuente del lector.
`bitmap-only`	Solo se permite la incrustación como mapa de bits, que el documento no puede utilizar. No se incrusta.
`unstated`	El archivo no declara ningún permiso. Se considera que admite incrustación, tal como exige la especificación OpenType.

WOFF y WOFF2 se rechazan al subirlos. No pueden incrustarse en un documento Word, por lo que la misma plantilla saldría bien en PDF y mal en Word, una diferencia que solo detectarías después de enviar el documento.

Fuentes integradas

Estas familias se incluyen con el producto; úsalas por su nombre en style.fontFamily y page.defaultFont. La misma fuente se usa en PDF, Word y el editor. Si una familia no tiene el grosor solicitado, no se rechaza: se imprime con el más cercano.

Familia	Grupo	Grosores	Sistemas de escritura
`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

Cuándo se rechaza una subida

Cada rechazo devuelve un 400 con el motivo en errors.file. Muestra esa frase a la persona que sube el archivo; ya indica qué debe hacer.

HTTP 400

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "file": ["Sube una fuente TTF u OTF para que pueda usarse en la salida Word. Los archivos WOFF y WOFF2 no pueden incrustarse en un documento Word."]
  },
  "correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}

Errores →

Los errores más habituales

El tipo se detecta por los primeros bytes, no por el nombre. Renombrar un PDF como .png no lo convierte en imagen; la subida se rechaza.
WOFF y WOFF2 se rechazan de forma intencionada. No pueden incrustarse en Word y la misma plantilla saldría bien en PDF y mal en Word; sube TTF u OTF.
La respuesta de subida incluye fontEmbedding. Si lo ignoras, descubrirás que se ha sustituido la fuente después de enviar el documento.
Un URI data: viaja con cada solicitud. Para un logotipo que aparece en todos los documentos, súbelo una vez y envía su ID.
Una imagen necesaria para un documento no requiere limpieza manual. Indica expiresInMinutes y se eliminará sola.