# 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](https://docs.uninvoice.app/es/templates/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") 
 ] 
```

La forma `{{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.

![La sección Campos personalizados del formulario de factura, con un campo por cada marcador declarado (un Period obligatorio y un Purchase order), cada uno mostrando su clave como texto de ayuda.](https://docs.uninvoice.app/es/assets/images/invoice-custom-fields-fcee6ef7bb6b741040d69b5001298dc0.png)

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.