Formatos de datos

Aquí encontrarás la estructura con la que deben llegar tus datos. PDFgine no imprime el valor enviado tal cual; aplica el formato declarado en la plantilla, en el idioma del documento.

En una frase: los datos llegan sin formato y PDFgine les da formato. Si envías un valor ya formateado, el documento se leerá correctamente en un idioma y mal en el otro.

Tipo de campo	Cómo enviarlo	Entrada de ejemplo	Salida
`date`	ISO 8601. YYYY-MM-DD para un día sin hora; una marca de tiempo completa cuando importe la hora. No lo conviertas a un formato local.	`"2026-09-06"`	`6/9/2026`
`number`	Un número JSON. Sin separadores de miles, espacios ni comillas; el separador decimal es un punto.	`24000`	`24.000,00`
`currency`	Envía el importe como un número sin formato. La moneda no debe incluirse en él; se configura en el formato de columna como código ISO 4217.	`24000`	`24.000,00 USD`
`percent`	Una proporción sobre cien, sin formato: envía 18 para indicar el 18%. El documento añade el signo.	`18`	`18,00%`
`string`	Se imprime tal como llega. No envíes una fecha, un importe ni una proporción como cadena de texto; se pierde el formato.	`"Northwind Trading Ltd."`	`Northwind Trading Ltd.`
`boolean`	JSON true/false. Es lo que leen los bloques condicionales.	`true`	Determina la condición; nunca se imprime como texto

Un formato se declara en tres lugares: el campo "format" de una columna de tabla y de una fila de resumen, "dataRules.formatter" de un elemento que imprime un único valor y las funciones format_date y format_money del texto que combina varios campos.

Datos y plantilla

{
  "issueDate": "2026-09-06",
  "currency": "USD",
  "lineItems": [
    { "name": "Sitio web corporativo", "quantity": 1, "unitPrice": 24000, "total": 24000 }
  ]
}

// En la plantilla:
// columna de tabla:   "format": { "kind": "currency", "currency": "USD", "decimals": 2 }
// columna de fecha:    "format": { "kind": "date", "dateStyle": "short" }
// elemento de texto:   "{{ referenceNo }} · {{ format_date issueDate }}"

El IBAN, el teléfono y los números fiscales también llegan en formato canónico: IBAN sin espacios, teléfono en E.164 (+442071838750). La agrupación es un formato de presentación y no pertenece a los datos.

El nombre con el que se recibe el documento

El documento descargado se llama "{document type} - {counterparty} - {reference no}". Las tres partes proceden de los datos que envías: document.title, customer y referenceNo. Se omite lo que falte y, si ninguna parte permite generar un nombre utilizable, el documento usa su identificador, por ejemplo quote-doc_94812af2.pdf.

Cabecera de respuesta

Content-Disposition: attachment;
  filename="Quote - Müller og Søn ApS - QUO-2026-0042.pdf";
  filename*=UTF-8''Quote%20-%20M%C3%BCller%20og%20S%C3%B8n%20ApS%20-%20QUO-2026-0042.pdf

El nombre se escribe dos veces en la misma cabecera. El campo extendido conserva el idioma del documento; el clásico contiene una versión ASCII legible para los clientes que no pueden leer el extendido. Se eliminan los caracteres que ningún sistema de archivos acepta (barra, barra inversa, dos puntos, asterisco, interrogación, comillas, menor que, mayor que, barra vertical), junto con los caracteres de control, y se limita la longitud del nombre para que funcione en todos los sistemas de archivos.

Imágenes

Una imagen de la plantilla puede vincularse a un campo de datos y recibir su origen con la solicitud. Se admiten dos formas: el ID de un recurso subido (ast_…, para logotipos, sellos y firmas repetidos: se sube una vez y solo viaja el ID) y una imagen en línea (data:image/png;base64,…, para imágenes de un solo uso). Si el campo falta o está vacío, se usa la imagen de la plantilla; si contiene un valor inutilizable, se rechaza la solicitud con 422 y la respuesta indica el campo.

Solicitud

{
  "templateCode": "invoice",
  "format": "pdf",
  "data": {
    "logo": "ast_9f1c7b1f0f6b4f5f9f0a0d1e2c3b4a59",
    "signature": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Límites: una imagen en línea debe ser PNG, JPEG o WebP, máximo 2 MB por imagen y 6 MB entre todas las imágenes del documento. Un recurso subido admite hasta 10 MB. Para imágenes temporales, indica expiresInMinutes al subir el recurso (1 minuto–7 días); los recursos caducados se eliminan automáticamente.

Recursos

Los logotipos, las firmas y las fuentes se suben una sola vez y se referencian por ID. Su página explica la subida, los límites y los permisos de cada fuente.

Recursos →

Los errores más habituales

Un valor ya formateado se imprime tal como llega. "1.234,56" se lee bien en un idioma y mal en otro, y ningún formato posterior puede arreglarlo.
Una fecha debe estar en ISO 8601. Un formato local llega como texto: no se formatea, no se ordena ni se traduce.
La moneda no debe incluirse en el importe. Envía el número y deja que el formato de la columna añada el código ISO.
Una proporción se envía sobre cien: 18 para indicar el 18%. Si envías 0.18, se imprime cero coma dieciocho por ciento.
Una condición lee un booleano JSON. La cadena "false" es texto no vacío y cuenta como presente.