Precarga de Campos

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 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.

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

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()

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:

{
  "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.

{
  "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 para conocer el flujo completo de creación de destinatarios y campos
Webhooks — suscríbete a signing_request.field.filled para reaccionar a medida que se completan los campos

Guías de Inicio

Guías avanzadas

Precarga de Campos

¿Qué propiedad necesito?

Referencia de propiedades

Creación de una solicitud de firma con campos precargados

Claves de `prefilledData` aceptadas

Lectura de los valores de los campos

Aspectos a tener en cuenta

`variable_name` es una etiqueta, no una fuente de datos

Los firmantes no pueden anular campos de solo lectura o precargados

Los campos obligatorios precargados deben resolverse antes de poder enviar

Próximos pasos

​¿Qué propiedad necesito?

​Referencia de propiedades

​Creación de una solicitud de firma con campos precargados

​Claves de prefilledData aceptadas

​Lectura de los valores de los campos

​Aspectos a tener en cuenta

​variable_name es una etiqueta, no una fuente de datos

​Los firmantes no pueden anular campos de solo lectura o precargados

​Los campos obligatorios precargados deben resolverse antes de poder enviar

​Próximos pasos

¿Qué propiedad necesito?

Referencia de propiedades

Creación de una solicitud de firma con campos precargados

Claves de `prefilledData` aceptadas

Lectura de los valores de los campos

Aspectos a tener en cuenta

`variable_name` es una etiqueta, no una fuente de datos

Los firmantes no pueden anular campos de solo lectura o precargados

Los campos obligatorios precargados deben resolverse antes de poder enviar

Próximos pasos