Templates

Si mandas el mismo documento cambiando unos cuantos datos, no hace falta que lo generes y lo subas cada vez. Regístralo como template una sola vez, y a partir de ahí mandas nada más los valores: Firmame arma el PDF.

El ciclo

Los cuatro tipos

Un solo endpoint —POST /developers/template/save— los atiende a todos. Lo que cambia es template_type y cómo va codificado el archivo.

HTML

Marca cada hueco con la clase y un id:

<p>
  <span class="signmage-template-field" id="arrendatario">(aquí va el valor)</span>
  es el arrendatario de este contrato.
</p>

Las tablas dinámicas usan class="signmage-template-table" con su propio id.

await services.saveTemplate({
  template_type: 'html',
  template_name: 'contrato-arrendamiento',
  template_data: Buffer.from(html).toString('base64'),
});

PDF con AcroForm

Si ya tienes un PDF con formulario, no hay que marcar nada — Firmame lee los campos que el formulario declara, con su tipo y sus valores permitidos.

await services.saveTemplate({
  template_type: 'pdf',
  template_name: 'solicitud',
  url_doc: 'https://ejemplo.com/solicitud-con-formulario.pdf',
});

url_doc evita el sobrecosto de Base64, que en un PDF grande no es menor.

pdfmake

await services.saveTemplate({
  template_type: 'pdfmake',
  template_name: 'pagare',
  template_data: {
    content: [
      'El suscrito {{nombre}} se obliga a pagar el día {{fecha}}.',
    ],
  },
});

Ojo: en pdfmake el template_data va como objeto JSON crudo, no en Base64.

DOCX

Marca cada hueco con uno de los dos mecanismos nativos de Word — Firmame usa el nombre que le des al campo como identificador del placeholder, igual que el id en HTML:

• Campos de correspondencia: pestaña Correspondencia → Insertar campo combinado, o Insertar → Elementos rápidos → Campo → MergeField para escribir el nombre a mano sin necesitar una lista de datos. En el documento se ven como «nombre_del_campo».
• Controles de contenido:
  1. Activa la pestaña Programador: Archivo → Opciones → Personalizar cinta de opciones y marca la casilla «Programador».
  2. En Programador → Controles, inserta un control de contenido de texto sin formato o de texto enriquecido en el punto donde va el valor.
  3. Con el control seleccionado, abre Propiedades y escribe el nombre del campo en Etiqueta (Tag) — ese es el identificador que Firmame lee.

await services.saveTemplate({
  template_type: 'docx',
  template_name: 'carta-oferta',
  template_data: fs.readFileSync('carta.docx').toString('base64'),
});

Qué te devuelve

Los placeholders que encontró, con el valor vacío.

{
  "template_title": "contrato-arrendamiento",
  "fields": [{ "id": "arrendatario", "value": "" }],
  "tables": [{ "id": "conceptos", "rows": [] }]
}

Esa misma forma es la que devuelves al generar el documento.

Generar un documento

Es el POST /developers/json de siempre, con template en lugar de url_doc:

await services.request({
  template: {
    title: 'contrato-arrendamiento',
    name: 'Contrato — Ana Ruiz',
  },
  fields: [
    { id: 'arrendatario', value: 'Ana Ruiz' },
    { id: 'monto', value: '$12,500.00' },
  ],
  stickers: [ /* … */ ],
});

Como es el mismo endpoint, puedes combinarlo con todo lo demás: stickers, flujo, expediente, QR.

Consultar los templates de tu cuenta

const templates = await services.listTemplates();
const fields = await services.getTemplateFields('contrato-arrendamiento');

Útil para construir un formulario en tu propia interfaz sin tener los nombres de los campos escritos a mano.

Referencia