> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Precarga de Campos
> Rellena previamente los campos de las solicitudes de firma con texto estático o datos del destinatario, y comprende qué propiedad controla realmente el valor.
Firma te permite mostrarle a un firmante un valor antes de que abra el documento — ya sea un texto fijo que tú elijas, o un valor extraído automáticamente de los propios datos del destinatario (su correo electrónico, nombre, empresa, etc). Esta guía cubre las propiedades que controlan ese comportamiento y las que solo parecen hacerlo.
**Problema conocido en la especificación:** el [esquema de campo](/api-reference/v01.33.00/signing-requests/create-signing-request) documenta una propiedad de nivel superior `prefilled_data` con una enumeración de atributos del destinatario. **El servidor la ignora silenciosamente — no tiene ningún efecto.** La única propiedad que realmente autocompleta un campo con datos del destinatario es `format_rules.prefilledData` (camelCase, anidada dentro de `format_rules`), descrita más abajo. Si has probado `prefilled_data` y el campo volvió vacío, esta es la razón. La corrección de la especificación se está siguiendo por separado; mientras tanto, usa `format_rules.prefilledData`.
## ¿Qué propiedad necesito?
* **El firmante debe escribir su propio valor, y tú no necesitas tocarlo** — no configures `read_only`. Simplemente posiciona el campo normalmente.
* **Quieres un valor fijo que nadie pueda editar** (un número de contrato, un nombre de departamento, cualquier cosa que ya conozcas) — configura `read_only: true` y `read_only_value: "..."`.
* **Quieres mostrar y bloquear los propios datos de perfil del destinatario** (su correo electrónico, nombre, empresa, etc.) — configura `read_only: true` y `format_rules: { prefilledData: "..." }`.
* **Solo necesitas una etiqueta para identificar el campo más tarde** (para tu propio control interno, o para hacer coincidir un campo al actualizar una solicitud de firma basada en una plantilla) — eso es `variable_name`. Nunca establece ni cambia lo que ve el firmante.
* **Estás leyendo un campo de vuelta** (después de su creación, o después de la firma) y quieres el valor que realmente hay — lee `value` en la respuesta de la API.
## Referencia de propiedades
| Propiedad | Dónde vive | Qué hace | ¿Establece el valor mostrado? |
| :--------------------------- | :----------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------- |
| `format_rules.prefilledData` | Anidada dentro de `format_rules` en el campo | La clave de atributo del destinatario desde la cual autocompletar. Configura esta propiedad con una clave reconocida y el campo se completa con los datos del destinatario asignado en el momento del envío. Claves reconocidas: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, o una clave `custom_fields` del destinatario. Cuando está configurada, el sistema también exige que el atributo correspondiente esté presente en el destinatario antes de permitir el envío. | Sí — el mecanismo principal de precarga |
| `read_only_value` | Propiedad de campo de nivel superior (solicitud) | Texto estático que proporcionas al momento de crear el campo. **No se puede combinar con `prefilledData`** — la API devuelve 400 si ambos están configurados en el mismo campo. Cuando una plantilla ya tiene una regla `prefilledData`, `read_only_value` en el campo por solicitud sobrescribe la regla de la plantilla durante la fusión. | Sí — siempre gana cuando está presente |
| `variable_name` | Propiedad de campo de nivel superior (solicitud y respuesta) | Una etiqueta definida por el desarrollador para el campo. Se usa como **clave de fusión de plantilla** (respaldo después de `template_field_id` al crear una solicitud de firma a partir de una plantilla) y como **accesor de API** para buscar campos en las respuestas de `GET /signing-requests/{id}/fields`. No interviene en la resolución de la precarga — de eso se encarga `format_rules.prefilledData`. | No |
| `value` (solo en respuesta) | Propiedad de campo de nivel superior, respuestas GET | El valor real resuelto/capturado del campo — desde `read_only_value`, desde la resolución de precarga, o desde lo que ingresó el firmante. `final_value` es un alias en desuso para los mismos datos. | N/D — de solo lectura, calculado |
`read_only` en sí mismo es solo un interruptor booleano: debe ser `true` para que `read_only_value` o `format_rules.prefilledData` surtan efecto. Un campo con `read_only: false` ignora ambos.
## Creación de una solicitud de firma con campos precargados
Este ejemplo crea y envía un documento con dos campos bloqueados: una referencia de contrato estática, y el correo electrónico del destinatario extraído de su propio registro de destinatario.
```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Employment Contract",
"document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
"recipients": [
{
"first_name": "Alice",
"last_name": "Johnson",
"email": "alice@example.com",
"designation": "Signer"
}
],
"fields": [
{
"type": "text",
"recipient_id": "temp_1",
"page_number": 1,
"position": { "x": 10, "y": 10, "width": 40, "height": 4 },
"read_only": true,
"read_only_value": "Contract #12345 - Acme Corporation"
},
{
"type": "text",
"recipient_id": "temp_1",
"page_number": 1,
"position": { "x": 10, "y": 18, "width": 40, "height": 4 },
"read_only": true,
"format_rules": { "prefilledData": "email" }
}
]
}'
```
```javascript Node.js theme={null}
const response = await fetch(
'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
{
method: 'POST',
headers: {
'Authorization': process.env.FIRMA_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Employment Contract',
document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
recipients: [
{
first_name: 'Alice',
last_name: 'Johnson',
email: 'alice@example.com',
designation: 'Signer'
}
],
fields: [
{
type: 'text',
recipient_id: 'temp_1',
page_number: 1,
position: { x: 10, y: 10, width: 40, height: 4 },
read_only: true,
read_only_value: 'Contract #12345 - Acme Corporation'
},
{
type: 'text',
recipient_id: 'temp_1',
page_number: 1,
position: { x: 10, y: 18, width: 40, height: 4 },
read_only: true,
format_rules: { prefilledData: 'email' }
}
]
})
}
)
const result = await response.json()
```
```python Python theme={null}
import os
import requests
response = requests.post(
'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
headers={
'Authorization': os.environ['FIRMA_API_KEY'],
'Content-Type': 'application/json'
},
json={
'name': 'Employment Contract',
'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
'recipients': [
{
'first_name': 'Alice',
'last_name': 'Johnson',
'email': 'alice@example.com',
'designation': 'Signer'
}
],
'fields': [
{
'type': 'text',
'recipient_id': 'temp_1',
'page_number': 1,
'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
'read_only': True,
'read_only_value': 'Contract #12345 - Acme Corporation'
},
{
'type': 'text',
'recipient_id': 'temp_1',
'page_number': 1,
'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
'read_only': True,
'format_rules': {'prefilledData': 'email'}
}
]
}
)
result = response.json()
```
`recipient_id` usa un id temporal (`temp_1`) aquí porque el destinatario está definido en la misma solicitud (creación basada en documento). Si estás agregando campos a una solicitud de firma existente o a una creada a partir de una plantilla, usa en su lugar el UUID real del destinatario.
## Claves de `prefilledData` aceptadas
`format_rules.prefilledData` acepta estos atributos del destinatario:
`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`
También puedes hacer referencia a cualquier clave presente en el objeto `custom_fields` de un destinatario (la coincidencia no distingue mayúsculas de minúsculas) — configura esa clave al crear el destinatario, y luego haz referencia a ella de la misma manera:
```json theme={null}
{
"type": "text",
"recipient_id": "temp_1",
"page_number": 1,
"position": { "x": 10, "y": 26, "width": 40, "height": 4 },
"read_only": true,
"format_rules": { "prefilledData": "employee_id" }
}
```
## Lectura de los valores de los campos
Cuando haces un GET de una solicitud de firma o listas sus campos, cada campo incluye una propiedad `value` — el valor real resuelto, ya sea que provenga de `read_only_value`, de datos precargados del destinatario, o de lo que escribió el firmante. `final_value` todavía aparece en las respuestas, pero es un alias en desuso; prefiere `value` en las integraciones nuevas.
```json theme={null}
{
"id": "field-uuid",
"type": "text",
"read_only": true,
"format_rules": { "prefilledData": "email" },
"value": "alice@example.com"
}
```
El `value` de un campo precargado puede ser `null` hasta que se envíe la solicitud de firma — la resolución contra los datos del destinatario ocurre en el momento del envío, no en el momento de creación del campo.
## Aspectos a tener en cuenta
### `variable_name` es una etiqueta, no una fuente de datos
`variable_name` es una etiqueta orientada a la interfaz de usuario y un mecanismo de coincidencia usado al fusionar campos de una plantilla en una solicitud de firma — nunca se lee como la fuente de un valor mostrado. Establecer `variable_name: "email"` en un campo **no** precarga nada; para eso todavía necesitas `format_rules.prefilledData`. Trata `variable_name` puramente como un identificador que eliges para tu propia referencia.
### Los firmantes no pueden anular campos de solo lectura o precargados
Si tu integración renderiza su propia interfaz de firma y envía los valores de los campos directamente, cualquier valor enviado para un campo `read_only` o precargado es rechazado del lado del servidor en lugar de aceptado silenciosamente — el envío del firmante se ignora para ese campo, y el intento se registra como un evento de seguridad. No dependas únicamente de ocultar estos campos del lado del cliente; el servidor lo aplica de forma independiente.
### Los campos obligatorios precargados deben resolverse antes de poder enviar
Si un campo es a la vez `required` y precargado (o de solo lectura), la llamada `/send` de la solicitud de firma valida que realmente se haya resuelto un valor — desde `read_only_value`, desde datos del destinatario, o desde `custom_fields`. Si no se resuelve nada (por ejemplo, `prefilledData` hace referencia a una clave de `custom_fields` que el destinatario no tiene), el envío falla en la validación en lugar de enviar un documento con un campo obligatorio en blanco.
## Próximos pasos
* [Envío de una Solicitud de Firma](/guides/sending-signing-request) para conocer el flujo completo de creación de destinatarios y campos
* [Webhooks](/guides/webhooks) — suscríbete a `signing_request.field.filled` para reaccionar a medida que se completan los campos