Guías

Colocar automáticamente campos de firma con etiquetas de anclaje: Posicionamiento de campos basado en texto

Escrito por

Ilustración de un campo de firma con coordenadas X e Y desconocidas que se traslada a un recuadro de firma resaltado en un documento.

Si alguna vez has posicionado campos de firma calculando coordenadas x/y en un PDF, sabrás lo tedioso que resulta a gran escala. Cambias el diseño del documento y todas las coordenadas se descuadran. Añades una segunda página y tienes que recalcular los desplazamientos para la mitad de tus campos.

Las etiquetas de anclaje solucionan esto. Inserta marcadores de texto como {{SIGN_HERE}} o {{DATE}} directamente en tu plantilla PDF, y Firma.dev los detecta automáticamente y coloca los tipos de campo correctos en esas ubicaciones. Los marcadores se eliminan del documento final, por lo que los firmantes nunca los ven. Una sola llamada a la API, sin cálculos de coordenadas.

Las etiquetas de anclaje se lanzaron en la v1.11.0 y admiten todos los tipos de campo, reglas de coincidencia flexibles y hasta 100 etiquetas por solicitud de firma.

Inicio rápido

La forma más rápida de poner en marcha las etiquetas de anclaje: inserta un marcador en tu PDF y, a continuación, crea una solicitud de firma con un array anchor_tags.

Paso 1: Añade el texto {{SIGN_HERE}} en el lugar de tu PDF donde quieras que aparezca el campo de firma. Puedes hacerlo con cualquier herramienta que utilices para generar tus documentos, ya sea una plantilla de Word, una librería de PDF o un servicio de generación de documentos.

Paso 2: Crea una solicitud de firma basada en documentos con la definición de la etiqueta de anclaje:

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'NDA - Acme Corp',
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Jane',
          last_name: 'Smith',
          email: 'jane@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  }
);

const signingRequest = await response.json();
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'NDA - Acme Corp',
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Jane',
          last_name: 'Smith',
          email: 'jane@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  }
);

const signingRequest = await response.json();
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'NDA - Acme Corp',
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Jane',
          last_name: 'Smith',
          email: 'jane@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  }
);

const signingRequest = await response.json();

Firma.dev escanea el PDF en busca de {{SIGN_HERE}}, coloca un campo de firma en esa ubicación, lo asigna al destinatario y elimina el texto del marcador del documento. Así de fácil.

Ten en cuenta que las etiquetas de anclaje solo funcionan con la creación de solicitudes de firma basadas en documentos, no basadas en plantillas. Envías el PDF sin procesar y dejas que el sistema de anclaje se encargue de la colocación de los campos.

Tipos de campo admitidos

Las etiquetas de anclaje admiten todos los tipos de campo disponibles en Firma.dev. Establece la propiedad type en cada etiqueta de anclaje con uno de estos valores:

signature para campos de firma, initials para campos de iniciales, text para entrada de texto de una sola línea, textarea para entrada de texto multilínea, date para campos de fecha, checkbox para casillas de verificación, radio para grupos de botones de radio, dropdown para selectores desplegables, url para campos de URL, stamp para campos de sello y file para campos de subida de archivos.

Cada tipo representa el widget de campo correspondiente en la experiencia de firma. Una etiqueta de anclaje date crea un selector de fecha, un dropdown crea un menú desplegable, y así sucesivamente.

Opciones de coincidencia y posicionamiento

El comportamiento de coincidencia predeterminado funciona en la mayoría de los casos, pero puedes ajustar cómo Firma.dev busca y posiciona los campos creados mediante anclajes.

Distinción entre mayúsculas y minúsculas: Establece case_sensitive en true o false (el valor predeterminado es false). Con la coincidencia que no distingue entre mayúsculas y minúsculas, coincidirán tanto {{sign_here}} como {{SIGN_HERE}}.

Coincidencia de palabra completa: Establece whole_word en true para evitar coincidencias parciales. Si tu cadena de anclaje es SIGN y whole_word es false, también coincidiría con SIGNATURE o COSIGN. Establecerlo en true garantiza que solo coincida con la palabra exacta.

Orientación a apariciones específicas: Si tu PDF contiene la misma cadena de anclaje varias veces, puedes dirigirte a instancias específicas con occurrence. Establécelo en 1 para la primera coincidencia, en 2 para la segunda, y así sucesivamente. Omítelo o establece match_all en true para colocar campos en todas las apariciones.

Posicionamiento por desplazamiento: Ajusta con precisión la ubicación del campo respecto al texto de anclaje utilizando offset_x y offset_y. Puedes especificar los desplazamientos en porcentajes (relativos a las dimensiones de la página) o en píxeles. Esto resulta útil cuando deseas que el campo se posicione ligeramente por debajo o a la derecha del marcador, en lugar de justo encima de él.

Gestión adecuada de anclajes ausentes: Establece ignore_if_not_present en true si la cadena de anclaje podría no existir en todos los documentos. Sin esto, un anclaje faltante devuelve un error. Con esto habilitado, Firma.dev omite esa etiqueta de forma silenciosa y procesa el resto.

Configuración avanzada

Aquí tienes un ejemplo más completo que combina varias etiquetas de anclaje con diferentes tipos de campo, dimensiones personalizadas y desplazamientos de posicionamiento:

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'Employment Agreement',
      anchor_tags: [
        {
          anchor_string: '{{EMPLOYEE_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true,
          width: 30,
          height: 8,
          offset_y: 2
        },
        {
          anchor_string: '{{EMPLOYEE_DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          required: true
        },
        {
          anchor_string: '{{EMPLOYEE_INITIALS}}',
          type: 'initials',
          recipient_id: 'temp_1',
          required: true,
          match_all: true
        },
        {
          anchor_string: '{{MANAGER_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_2',
          required: true
        },
        {
          anchor_string: '{{BENEFITS_OPT_IN}}',
          type: 'checkbox',
          recipient_id: 'temp_1',
          required: false,
          ignore_if_not_present: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Sarah',
          last_name: 'Chen',
          email: 'sarah@example.com',
          designation: 'Signer',
          order: 1
        },
        {
          id: 'temp_2',
          first_name: 'Mike',
          last_name: 'Torres',
          email: 'mike@example.com',
          designation: 'Signer',
          order: 2
        }
      ]
    })
  }
);
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'Employment Agreement',
      anchor_tags: [
        {
          anchor_string: '{{EMPLOYEE_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true,
          width: 30,
          height: 8,
          offset_y: 2
        },
        {
          anchor_string: '{{EMPLOYEE_DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          required: true
        },
        {
          anchor_string: '{{EMPLOYEE_INITIALS}}',
          type: 'initials',
          recipient_id: 'temp_1',
          required: true,
          match_all: true
        },
        {
          anchor_string: '{{MANAGER_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_2',
          required: true
        },
        {
          anchor_string: '{{BENEFITS_OPT_IN}}',
          type: 'checkbox',
          recipient_id: 'temp_1',
          required: false,
          ignore_if_not_present: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Sarah',
          last_name: 'Chen',
          email: 'sarah@example.com',
          designation: 'Signer',
          order: 1
        },
        {
          id: 'temp_2',
          first_name: 'Mike',
          last_name: 'Torres',
          email: 'mike@example.com',
          designation: 'Signer',
          order: 2
        }
      ]
    })
  }
);
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'Employment Agreement',
      anchor_tags: [
        {
          anchor_string: '{{EMPLOYEE_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true,
          width: 30,
          height: 8,
          offset_y: 2
        },
        {
          anchor_string: '{{EMPLOYEE_DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          required: true
        },
        {
          anchor_string: '{{EMPLOYEE_INITIALS}}',
          type: 'initials',
          recipient_id: 'temp_1',
          required: true,
          match_all: true
        },
        {
          anchor_string: '{{MANAGER_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_2',
          required: true
        },
        {
          anchor_string: '{{BENEFITS_OPT_IN}}',
          type: 'checkbox',
          recipient_id: 'temp_1',
          required: false,
          ignore_if_not_present: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Sarah',
          last_name: 'Chen',
          email: 'sarah@example.com',
          designation: 'Signer',
          order: 1
        },
        {
          id: 'temp_2',
          first_name: 'Mike',
          last_name: 'Torres',
          email: 'mike@example.com',
          designation: 'Signer',
          order: 2
        }
      ]
    })
  }
);

Hay algunos detalles a tener en cuenta en este ejemplo. La etiqueta {{EMPLOYEE_INITIALS}} utiliza match_all: true, por lo que si el PDF tiene marcadores de iniciales en las páginas 1, 5 y 12, las tres recibirán campos. La casilla de verificación {{BENEFITS_OPT_IN}} utiliza ignore_if_not_present: true porque no todas las versiones del contrato de trabajo incluyen esa sección. Y el offset_y: 2 en el campo de firma lo desplaza ligeramente hacia abajo respecto a la posición del texto de anclaje.

Las dimensiones (width y height) siguen el mismo sistema de coordenadas basado en porcentajes utilizado por los campos posicionados manualmente. Las etiquetas de anclaje y los campos manuales funcionan juntos, por lo que puedes usar anclajes para la mayor parte de tus campos y seguir añadiendo campos basados en coordenadas manuales en la misma solicitud para casos especiales.

Migración desde otras plataformas

Si vas a migrar desde otro proveedor de firma electrónica que utiliza la colocación de campos basada en texto, los conceptos se asignan de forma directa. La sintaxis de las cadenas de anclaje y los nombres de las propiedades difieren, pero el mecanismo subyacente es el mismo: insertar un marcador, definir el tipo de campo y dejar que la API gestione la colocación.

Desde Auto-Place de DocuSign: DocuSign utiliza anchorString, anchorXOffset, anchorYOffset y tipos específicos de pestañas como signHereTabs. En Firma.dev, esto se convierte en anchor_string, offset_x, offset_y y el campo universal type. El parámetro anchorIgnoreIfNotPresent de DocuSign se corresponde con ignore_if_not_present. El parámetro anchorCaseSensitive de DocuSign se corresponde con case_sensitive. La principal diferencia estructural es que Firma.dev utiliza un único array anchor_tags con una propiedad type, en lugar de arrays separados para cada tipo de pestaña.

Desde Smart Anchors de Yousign: El concepto de Yousign de "anclajes inteligentes" con detección del tipo de campo se traduce directamente. Las opciones de coincidencia y posicionamiento son comparables, aunque los nombres de las propiedades utilizan la convención snake_case de Firma.dev.

El límite es de 100 etiquetas de anclaje por solicitud de firma, lo que cubre cómodamente la mayoría de los flujos de trabajo documentales. Si procesas documentos que realmente necesitan más de 100 campos, considera dividirlos en varias solicitudes de firma o utilizar una combinación de etiquetas de anclaje y definiciones de campos basadas en plantillas.

Referencia de la API

El array anchor_tags está disponible en el endpoint de creación de solicitudes de firma basadas en documentos (POST /signing-requests). Cada elemento del array es un objeto AnchorTag con aproximadamente 25 propiedades configurables.

Las propiedades clave:

anchor_string (obligatorio) es el marcador de texto que se buscará en el PDF. type (obligatorio) es el tipo de campo que se va a crear. recipient_id asigna el campo a un destinatario específico mediante su ID o ID temporal. required marca el campo como obligatorio u opcional. offset_x y offset_y ajustan la posición del campo respecto a la ubicación del anclaje. width y height establecen dimensiones de campo personalizadas. case_sensitive controla si la coincidencia distingue entre mayúsculas y minúsculas. whole_word evita coincidencias parciales de cadenas. occurrence apunta a una instancia específica cuando el anclaje aparece varias veces. match_all coloca campos en cada aparición. ignore_if_not_present omite la etiqueta sin error si no se encuentra el texto de anclaje en el documento.

Para ver el esquema completo con todas las propiedades y sus tipos, consulta el registro de cambios de la API para la v1.11.0.

Próximos pasos

Las etiquetas de anclaje se combinan a la perfección con la generación programática de documentos. Si tu aplicación genera contratos, acuerdos de confidencialidad (NDA) o documentos de incorporación a partir de plantillas, puedes insertar cadenas de anclaje durante la generación y dejar que Firma.dev gestione la colocación de campos automáticamente en cada solicitud.

Comienza con Firma.dev gratis, sin necesidad de tarjeta de crédito.

  1. Encabezado

Imagen de fondo

¿Listo para añadir firmas electrónicas a tu aplicación?

Comienza gratis. No se requiere tarjeta de crédito. Paga solo 0,049 € por sobre cuando estés listo para empezar.

Imagen de fondo

¿Listo para añadir firmas electrónicas a tu aplicación?

Comienza gratis. No se requiere tarjeta de crédito. Paga solo 0,049 € por sobre cuando estés listo para empezar.

Imagen de fondo

¿Listo para añadir firmas electrónicas a tu aplicación?

Comienza gratis. No se requiere tarjeta de crédito. Paga solo 0,049 € por sobre cuando estés listo para empezar.