Templates

Los endpoints de Templates te permiten subir archivos .docx (o .pdf) reutilizables que contienen variables tipo Jinja2 ({{ nombre_cliente }}). AllSign detecta automáticamente esas variables, infiere su tipo, y las deja listas para que las uses al crear documentos individuales o chains (paquetes multi-documento).

Subir template

Sube un archivo .docx o .pdf y crea un nuevo template. El backend:

1. Valida que el archivo sea un DOCX o PDF válido (máx. 50 MB).
2. Auto-detecta todas las variables {{ ... }} en el documento (solo DOCX).
3. Infiere el tipo de cada variable (text, date, currency, etc.) a partir del nombre.
4. Almacena el archivo original en S3 para reutilizarlo.
5. Retorna la lista de variables detectadas con metadata.

El request es multipart/form-data, no JSON.

Form fields

Response — 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Contrato de arrendamiento",
  "description": null,
  "originalFilename": "contrato_arrendamiento.docx",
  "fileType": "docx",
  "variables": ["arrendador__nombre", "arrendatario__nombre", "monto_renta"],
  "variableConfig": [
    { "name": "arrendador__nombre", "label": "Nombre", "type": "text", "required": true, "role": "Arrendador" },
    { "name": "arrendatario__nombre", "label": "Nombre", "type": "text", "required": true, "role": "Arrendatario" },
    { "name": "monto_renta", "label": "Monto Renta", "type": "currency", "required": true, "role": null }
  ],
  "tags": ["legal", "renta"],
  "category": "contratos",
  "aiEditable": true,
  "createdAt": "2026-04-07T20:00:00Z"
}

curl -X POST https://api.allsign.io/v2/templates/ \
  -H "Authorization: Bearer allsign_live_sk_TU_API_KEY" \
  -F "file=@./contrato_arrendamiento.docx" \
  -F "name=Contrato de arrendamiento" \
  -F "tags=legal,renta" \
  -F "category=contratos"

Errores

Listar templates

Devuelve todos los templates activos del usuario u organización autenticados. Soporta filtros por tipo de archivo, tags, categoría y búsqueda de texto.

Query parameters

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Contrato de arrendamiento",
      "fileType": "docx",
      "tags": ["legal", "renta"],
      "category": "contratos",
      "usageCount": 12,
      "lastUsedAt": "2026-04-05T15:30:00Z",
      "createdAt": "2026-03-01T10:00:00Z"
    }
  ],
  "total": 1
}

Obtener template

Devuelve el detalle completo de un template, incluyendo variables, variableConfig, testDataSets y metadata de uso.

Path parameters

Response — 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Contrato de arrendamiento",
  "description": null,
  "originalFilename": "contrato_arrendamiento.docx",
  "fileType": "docx",
  "variables": ["arrendador__nombre", "arrendatario__nombre", "monto_renta"],
  "variableConfig": [
    { "name": "arrendador__nombre", "label": "Nombre", "type": "text", "required": true, "role": "Arrendador" }
  ],
  "tags": ["legal", "renta"],
  "category": "contratos",
  "aiEditable": true,
  "usageCount": 12,
  "lastUsedAt": "2026-04-05T15:30:00Z",
  "currentVersion": 1,
  "testDataSets": [],
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-03-01T10:00:00Z"
}

Errores

Inferencia de roles

Al subir un template DOCX, AllSign analiza los nombres de las variables para inferir automáticamente un rol de firmante por cada variable. Esto permite agrupar variables por rol en el dashboard y habilitar el auto-llenado desde contactos del CRM.

Convención __ (doble guion bajo)

La inferencia usa una convención simple: el doble guion bajo (__) separa el rol del campo.

{{ rol__campo }}

Todo lo que está antes de __ es el nombre del rol. Todo lo que está después es el nombre del campo. Las variables sin __ son variables generales del documento (sin rol).

Roles ilimitados

No hay un diccionario fijo de roles. Cualquier texto antes de __ se convierte en un rol:

{{ comprador__nombre }}         → Rol: "Comprador"
{{ empresa_contratante__rfc }}  → Rol: "Empresa Contratante"
{{ testigo_1__nombre }}         → Rol: "Testigo 1"
{{ notario__numero }}           → Rol: "Notario"

Los guiones bajos simples (_) dentro del rol se convierten en espacios y se capitalizan: parte_reveladora → "Parte Reveladora".

Inferencia de tipo

AllSign infiere el tipo de input a partir del nombre del campo (la parte después de __):

Auto-llenado con contactos

Cuando un template tiene variables con roles inferidos, el dashboard permite seleccionar un contacto del CRM para cada rol. Las variables se auto-llenan usando los customFields del contacto seleccionado, comparando por nombre exacto de variable.

Los customFields se persisten automáticamente cada vez que un firmante llena variables en un Chain, creando un ciclo de enriquecimiento progresivo.

Ejemplo completo — NDA

Un archivo DOCX de NDA con estas variables:

La empresa {{ revelador__nombre }}, con RFC {{ revelador__rfc }},
con domicilio en {{ revelador__domicilio }}, representada por
{{ revelador__representante }}, en adelante "La Parte Reveladora"...

...y {{ receptor__nombre }}, con RFC {{ receptor__rfc }}...

Firmado en {{ ciudad_firma }} el {{ fecha_firma }},
con vigencia de {{ vigencia_meses }} meses.

Produce este variableConfig:

Recomputar roles

Re-ejecuta la inferencia de roles sobre el variableConfig de un template existente. Esto es necesario para templates que se subieron antes de que la detección de roles estuviera habilitada.

Path parameters

Response — 200 OK

{
  "updated": 1,
  "variableConfig": [
    { "name": "arrendador__nombre", "label": "Nombre", "type": "text", "required": true, "role": "Arrendador" },
    { "name": "monto_renta", "label": "Monto Renta", "type": "currency", "required": true, "role": null }
  ]
}

curl -X POST https://api.allsign.io/v2/templates/550e8400-e29b-41d4-a716-446655440000/recompute-roles \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK"

Backfill de roles

Re-ejecuta la inferencia de roles sobre todos los templates activos del tenant. Operación masiva para migrar templates existentes.

Response — 200 OK

{
  "updated": 15
}

curl -X POST https://api.allsign.io/v2/templates/backfill-roles \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK"

Actualizar template

Actualiza la metadata editable de un template: nombre, descripción, tags, categoría, flag aiEditable y variableConfig. No reemplaza el archivo subido — para eso usa POST /v2/templates/{id}/duplicate y vuelve a subir.

Request body

Response — 200 OK

Devuelve el mismo payload que GET /v2/templates/{id}.

Errores

Eliminar template

Elimina un template. Por defecto realiza un soft-delete (marca el template inactivo y conserva el archivo en S3 para auditoría). Pasa ?hard=true para eliminar de forma permanente la fila y el objeto S3.

La eliminación se rechaza con 409 Conflict si el template está en uso por documentos o chains activos. Archiva o completa esos primero.

Path parameters

Query parameters

Response — 200 OK

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Contrato de arrendamiento",
  "message": "Template 'Contrato de arrendamiento' archived.",
  "softDelete": true,
  "s3Deleted": false,
  "inUseBy": {
    "documents": 0,
    "chains": 0
  }
}

Errores

{
  "detail": {
    "code": "TEMPLATE_IN_USE",
    "message": "Template is referenced by 2 active document(s) and 1 active chain(s).",
    "inUseBy": {
      "documents": 2,
      "chains": 1
    }
  }
}