Colocar campos automáticamente

Colocar los campos a mano está bien para un documento. Para un contrato que envía cada semana, o un documento que genera AutomaDoc, escriba en su lugar etiquetas en el documento: [[sign:Client]] donde firma el cliente, [[date:Client]] donde va la fecha. Cuando se prepara el documento, AutomaDoc encuentra cada etiqueta y coloca allí el campo. Quien usa la API y no puede editar el documento puede usar anclas: un campo colocado en relación con un texto que ya está en él.

Etiquetas de texto

Un ejemplo en Word

Escriba las etiquetas como texto normal donde deben ir los campos:

Signed for the client:

[[sign:Client]]

Name: [[name:Client]]          Date: [[date:Client]]
Company: [[company:Client]]
Purchase order: [[text:Client:PO number;optional]]

[[check:Client:Terms]] I have read and accept the terms.

Signed for the supplier:

[[sign:Supplier;w=180;h=50]]
Initials on every page: [[initials:Supplier]]

Cuando añade este documento a una solicitud, tiene dos huecos, Client y Supplier. Asigne cada hueco a un destinatario y todos los campos de ese rol irán a esa persona. Desde la API, indique autoTags: true y dé a cada destinatario su slot.

Las etiquetas funcionan igual en un archivo PDF, Word, Excel o PowerPoint, y en una plantilla de AutomaDoc: la generación no toca los corchetes, así que un documento generado a partir de una plantilla con etiquetas llega a una solicitud con sus campos listos para colocarse. Por eso las etiquetas usan [[ ]] y no las { } de los marcadores de plantilla.

Gramática

[[ kind : role ]]
[[ kind : role : label ]]
[[ kind : role ; option ; option ]]
[[ kind : role : label ; option ]]

Tipo (kind, en mayúsculas o minúsculas) indica qué es el campo:

Tipo	También se escribe	Campo
`sign`	`signature`	Firma
`initials`	`initial`	Iniciales
`name`		Nombre
`date`		Fecha de firma (se rellena automáticamente)
`text`		Texto
`check`	`checkbox`	Casilla
`company`		Empresa
`email`		Correo electrónico

Rol (role) es el hueco al que pertenece el campo: de 1 a 60 letras, dígitos, acentos o guiones bajos, en cualquier alfabeto (Client, Witness_1, 客户). Sin espacios. Las mayúsculas cuentan: Client y client son dos huecos distintos. Un # seguido de dígitos después del rol está reservado para el uso interno de AutomaDoc.

Etiqueta (label), opcional, son de 1 a 100 caracteres que el firmante ve como nombre del campo, por ejemplo [[text:Client:PO number]]. No puede contener [, ], ; ni :.

Opciones (option), cada una después de un ;, en mayúsculas o minúsculas:

Opción	Significado
`w=180`	Ancho en puntos (1 punto es 1/72 de pulgada), de 8 a 1000, con hasta dos decimales
`h=50`	Alto en puntos, de 8 a 1000
`optional`	El firmante puede dejar el campo vacío
`required`	El firmante debe rellenarlo (valor predeterminado)

Se admiten espacios y saltos de línea alrededor de cada parte, así que [[ sign : Client ]] funciona, igual que una etiqueta que pasa a una segunda línea entre dos de sus partes. Un salto de línea dentro de una palabra (en medio de Client, por ejemplo) rompe la etiqueta.

Una etiqueta tiene como máximo 200 caracteres de [[ a ]]. Si es más larga, o no tiene ]] de cierre, es texto normal y se ignora.

Dónde queda el campo

La esquina superior izquierda del campo es la esquina superior izquierda de la etiqueta. Su tamaño es el w y el h de la etiqueta o, si no, el tamaño predeterminado del campo (en puntos: firma 160 × 48, iniciales 64 × 40, casilla 14 × 14, correo electrónico 180 × 20, fecha 110 × 20, los demás campos de texto 160 × 20). Sin h, un campo nunca es más bajo que el texto de la etiqueta. Un campo que se saldría de la página se desplaza dentro de ella.

Por tanto, deje espacio a la derecha y debajo de cada etiqueta: un campo de firma baja 48 puntos (unos 1,7 cm) desde la parte superior de su etiqueta.

Cuando algo está mal

Un [[…]] que no sigue la gramática nunca se interpreta a ciegas: se queda en la página como texto, no se crea ningún campo y se avisa al remitente, con la etiqueta tal como está escrita (las 50 primeras por documento). Las causas habituales son un rol que falta, un espacio dentro del rol, un tipo u opción desconocidos, o un tamaño fuera del intervalo de 8 a 1000.

Otros límites:

se leen como máximo 500 etiquetas por página, y 500 por documento; a partir de ahí, las demás se ignoran con un aviso;
solo se busca el texto que el PDF contiene realmente: una página escaneada es una imagen, y las etiquetas que contiene no se encuentran;
una etiqueta cuyo rol no se asignó a ningún destinatario no crea ningún campo. A un firmante que se queda sin ningún campo no se le puede enviar la solicitud.

Volver a aplicar las etiquetas sustituye los campos creados a partir de etiquetas. Los campos que usted colocó a mano se mantienen.

Anclas desde la API

Un ancla coloca un campo en relación con un texto que ya está en el documento, como “Client signature:”. Sirve para documentos que usted no puede editar. Las anclas forman parte de POST /api/v1/envelopes (consulte la API de solicitudes de firma). Aquí la solicitud se envía como multipart/form-data: este JSON en una parte llamada envelope y el PDF en una parte llamada contract.

{
  "title": "Service agreement",
  "documents": [{ "file": "contract" }],
  "recipients": [
    { "key": "client", "role": "signer", "name": "Ana Lim", "email": "ana@example.com" }
  ],
  "anchors": [
    { "anchor": "Client signature:", "recipient": "client", "type": "signature", "offsetY": 14 },
    { "anchor": "Date:", "occurrence": 2, "recipient": "client", "type": "date_signed", "offsetX": 30, "offsetY": -2 }
  ],
  "send": true
}

Propiedad
`anchor`	El texto que se busca, de 1 a 200 caracteres. Obligatorio.
`recipient`	La `key` de un destinatario de la misma solicitud. Obligatorio.
`type`	`signature`, `initials`, `name`, `date_signed`, `text`, `checkbox`, `company` o `email`. Obligatorio.
`occurrence`	`"all"` (el valor predeterminado) o un número: la 1.ª, 2.ª… coincidencia en toda la solicitud.
`offsetX`, `offsetY`	Puntos desde la esquina superior izquierda del texto encontrado, de -2000 a 2000. Los valores positivos van hacia la derecha y hacia abajo. Predeterminado: 0.
`w`, `h`	Tamaño en puntos, de 8 a 1000. Predeterminado: el tamaño del tipo de campo.
`required`	`true` de forma predeterminada.
`label`	Se muestra al firmante como nombre del campo.

Una solicitud puede contener hasta 50 anclas.

Cómo se busca el texto

De forma exacta y distinguiendo mayúsculas y minúsculas: Signature: no coincide con signature: ni con Signature.
Cualquier serie de espacios, tabulaciones o saltos de línea del ancla coincide con cualquier serie de ellos en el documento, ya que el texto de un PDF no conserva un espaciado fiable. Los espacios al principio o al final del ancla se ignoran.
Las coincidencias nunca se solapan.
Las apariciones se cuentan en toda la solicitud en orden de lectura: los documentos en su orden y después página por página, de arriba abajo y de izquierda a derecha. "occurrence": 2 es la segunda coincidencia en cualquier parte de la solicitud, no la segunda de cada página.
Como máximo 200 coincidencias por ancla. Más se considera un error: escriba un ancla más larga.

Un ancla que no coincide con nada no crea ningún campo, y el documento registra un aviso anchor_not_found. Como con las etiquetas, el campo de un ancla que se saldría de la página se desplaza dentro de ella, y un firmante que se queda sin ningún campo impide que se envíe la solicitud: GET /api/v1/envelopes/:id indica entonces el motivo en sendError.

Puede combinar en una misma solicitud campos por coordenadas, etiquetas (autoTags) y anclas, hasta 500 campos en total.