Marcadores
Un marcador es un valor con nombre que tu plantilla de factura puede insertar: el nombre del destinatario, el número de factura, el total, o algo que definas tú, como un número de pedido de compra.
Los marcadores son lo que hace que una misma plantilla sirva para todas las
facturas: escribes #ph("recipient_name") una vez y cada PDF generado lleva su
propio destinatario.
Se usan dentro de los dos fragmentos Typst que controlas tú: el bloque post factura y el pie de página.
Leer un marcador
Indica #ph("payment_concept") al realizar el pago.
ph("clave") devuelve el valor de esa clave, o una cadena vacía si la
factura no tiene valor para ella. Eso hace muy fácil proteger el contenido
opcional, de forma que el bloque entero desaparece en lugar de dejar una etiqueta
suelta:
#if ph("purchase_order") != "" [
*Pedido de compra:* #ph("purchase_order")
]
{{clave}}Las plantillas antiguas pueden contener {{recipient_name}} escrito directamente
en el texto. Esa forma sigue funcionando (se sustituye antes de generar el PDF),
pero no puede expresar "omite esto cuando esté vacío": un {{clave}} sin valor
deja el texto literal en la factura. Es preferible #ph("clave").
Marcadores integrados
Están siempre disponibles y se resuelven a partir de los datos congelados de la propia factura, así que muestran lo que era cierto cuando se creó, nunca los datos actuales de la empresa o del cliente. Las fechas y los importes se formatean en el idioma de la factura.
El documento
| Clave | Valor |
|---|---|
invoice_id | La referencia del documento, por ejemplo 2026/0007 (una proforma o un borrador llevan su propia referencia). |
invoice_uuid | El identificador interno del documento. |
invoice_created_at | La fecha del documento: la de emisión en una factura emitida, la de creación en una proforma o un borrador. |
invoice_document_label | El nombre del documento en su idioma: Factura, Factura rectificativa, Proforma, Borrador de factura. |
invoice_issue_label | La etiqueta de esa fecha: Emitida en una factura emitida, Creada en una proforma o un borrador. |
invoice_due | La fecha de vencimiento del pago. Actualmente coincide con invoice_created_at. |
invoice_total | El total, formateado, sin divisa, por ejemplo 1.234,56. |
invoice_total_with_currency | El total seguido del código de divisa, por ejemplo 1.234,56 EUR. |
currency_code | El código de divisa ISO-4217 de la factura, por ejemplo EUR. |
Tu empresa (el emisor)
| Clave | Valor |
|---|---|
company_name | Denominación legal. |
company_friendly_name | Nombre comercial, si se ha configurado. |
company_display_name | El nombre comercial si existe; si no, la denominación legal. |
company_email | Email de contacto. |
company_phone | Teléfono de contacto. |
company_fiscal_id | Número de identificación fiscal. |
company_address_lines | Dirección, una línea por salto de línea. |
company_address_lines_inline | La misma dirección unida con comas. |
company_address_zipcode | Código postal. |
company_address_city | Ciudad. |
company_address_state | Provincia. |
company_address_country | Nombre del país. |
El destinatario
| Clave | Valor |
|---|---|
recipient_name | Nombre. |
recipient_fiscal_id | Número de identificación fiscal. |
recipient_email | Email de contacto. |
recipient_phone | Teléfono de contacto. |
recipient_address_lines | Dirección, una línea por salto de línea. |
recipient_address_lines_inline | La misma dirección unida con comas. |
recipient_address_zipcode | Código postal. |
recipient_address_city | Ciudad. |
recipient_address_state | Provincia. |
recipient_address_country | Nombre del país. |
Pago
| Clave | Valor |
|---|---|
payment_recipient | A quién pagar: la denominación legal de tu empresa. |
payment_concept | Qué indicar al pagar: la referencia del documento. |
Marcadores personalizados
Cuando el valor no se puede deducir de la factura (un número de pedido, un periodo facturado, un código de proyecto), declaras un marcador personalizado y lo rellenas al crear la factura.
Una declaración tiene cuatro partes:
| Campo | Significado |
|---|---|
| Clave | El nombre que lees en la plantilla, como en #ph("purchase_order"). |
| Etiqueta | Lo que ve en el formulario quien crea la factura. Obligatoria. |
| Obligatorio | Si está activo, la factura no se puede crear hasta que el campo tenga valor. |
| Valor por defecto | Rellena el campo previamente, y se puede editar en cada factura. |
Una clave no puede ser una de las integradas de la lista anterior, ni declararse dos veces en el mismo sitio.
Declarar un marcador personalizado
- Para toda la empresa: en la tarjeta Configuración de facturas de la página Empresa. Se ofrecen en todas las facturas.
- Por destinatario: en la plantilla de factura personalizada del formulario de un cliente. Se ofrecen solo en las facturas a ese cliente.
Al crear una factura, ambos conjuntos se combinan: las declaraciones de la empresa más las del destinatario. Si las dos declaran la misma clave, gana la del destinatario, así que un cliente puede tener otra etiqueta, otro valor por defecto u otra obligatoriedad para la misma clave.
Rellenarlo al crear la factura
En cuanto eliges destinatario en el formulario de factura, aparece un campo por cada declaración combinada, con su etiqueta y relleno con su valor por defecto. Los campos obligatorios se validan antes de poder crear la factura.
Los valores quedan entonces congelados en esa factura, junto con los propios fragmentos de la plantilla. Editar o eliminar una declaración más adelante nunca cambia una factura que ya existe; y una factura antigua, anterior a la declaración, simplemente resuelve esa clave como cadena vacía, de modo que un bloque protegido desaparece en lugar de romperse.