Variable Fill API

Los endpoints de Variable Fill permiten detectar y asignar variables en documentos con templates DOCX. El flujo consta de dos pasos opcionales:

B5 (Detect): Lee el DOCX y clasifica todas las variables {{ variable }} encontradas
B6 (Assign): Persiste la asignación de cada variable a un rol o a valor fijo del dueño

Estas operaciones son opcionales. Muchos integradores solo usan POST /add-signer con roleName: el auto-vinculado de variables ocurre del lado del servidor (AllSign reclama las variables sin asignar cuyo nombre coincide con el del rol). No se envía una lista de variables en el body. B5 y B6 ofrecen más control granular cuando lo necesites.

POST/v2/documents/{id}/detect-variables

Detect variables (B5)

Lee los archivos DOCX fuente del documento y retorna la lista de variables {{ variable }} detectadas con su clasificación (rol, sender, sin asignar) y un mapa de ocurrencias por PDF.

Cuándo usarlo:

El dueño carga un DOCX y quiere ver qué variables hay
Detectas variables antes de asignarlas manualmente en la UI
Documentos compound: necesitas saber qué variables hay en cada PDF

Importante: B5 solo detecta y clasifica — no crea filas en DocumentVariable. Eso lo hace B6.

Request

Detectar variables

POST

/v2/documents/{id}/detect-variables

curl -X POST "https://api.allsign.io/v2/documents/doc-uuid-123/detect-variables" \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK"

Parameters

Name
document_id
Type
string
Description
UUID del documento. Extraído de la URL.

Response (200 OK)

{
  "documentId": "doc-uuid-123",
  "docxSource": "compound_pdfs",
  "variables": [
    {
      "name": "arrendador__nombre",
      "label": "Nombre",
      "assignment": "role",
      "suggestedRoleName": "Arrendador",
      "type": "text",
      "pdfOccurrences": [
        {
          "pdfId": "pdf-uuid-1",
          "position": 1,
          "pdfName": "Contrato.pdf",
          "occurrenceCount": 1
        }
      ],
      "multiPdfConflict": false
    },
    {
      "name": "sender__fecha_inicio",
      "label": "Fecha Inicio",
      "assignment": "sender",
      "suggestedRoleName": null,
      "type": "date",
      "pdfOccurrences": [
        {
          "pdfId": "pdf-uuid-1",
          "position": 1,
          "pdfName": "Contrato.pdf",
          "occurrenceCount": 1
        }
      ],
      "multiPdfConflict": false
    },
    {
      "name": "testigo__nombre",
      "label": "Nombre",
      "assignment": "unassigned",
      "suggestedRoleName": null,
      "type": "text",
      "pdfOccurrences": [
        {
          "pdfId": "pdf-uuid-1",
          "position": 1,
          "pdfName": "Contrato.pdf",
          "occurrenceCount": 2
        }
      ],
      "multiPdfConflict": false
    }
  ],
  "total": 3,
  "pdfsScanned": 1
}

Response fields

Name
documentId
Type
string
Description
El UUID del documento consultado.
Name
docxSource
Type
string
Description
De dónde se leyó el DOCX: source_docx_s3_key (doc-level legacy), template_s3_key (doc-level moderno), o compound_pdfs (múltiples PDFs).
Name
variables
Type
array
Description
Lista de variables detectadas con su clasificación y ubicación por PDF.
Name
variables[].name
Type
string
Description
Nombre interno exacto tal como aparece en el DOCX (ej. arrendador__nombre).
Name
variables[].label
Type
string
Description
Etiqueta legible derivada del nombre. Para variables rol__campo, solo la parte del campo se titulariza (ej. arrendador__nombre → "Nombre", sender__fecha_inicio → "Fecha Inicio"). Para nombres sin __, se titulariza el nombre completo.
Name
variables[].assignment
Type
string
Description
Clasificación automática: role (prefijo role__), sender (prefijo sender__), o unassigned (sin prefijo).
Name
variables[].suggestedRoleName
Type
string | null
Description
Para assignment: role, el nombre del rol inferido (ej. "Arrendador"). Para otros tipos, null.
Name
variables[].type
Type
string
Description
Tipo de campo inferido por heurística. Solo devuelve uno de: text, date, currency, number, textarea. Valores como rfc o curp no se auto-detectan en B5 (pero sí puedes asignarlos manualmente en B6).
Name
variables[].pdfOccurrences
Type
array
Description
En documentos compound (múltiples PDFs), dónde aparece esta variable.
Name
variables[].multiPdfConflict
Type
boolean
Description
true cuando la variable aparece en 2+ PDFs SIN prefijo de rol. La UI debe preguntar al dueño si es un valor compartido o separado por PDF.
Name
total
Type
number
Description
Cantidad total de variables únicas detectadas.
Name
pdfsScanned
Type
number
Description
Cantidad de PDFs/fuentes DOCX analizados.

Error responses

Name
404 Not Found
Type
E1300_NOT_FOUND
Description
Document not found or not accessible to this API key.
Name
422 Unprocessable Entity
Type
E1200_VALIDATION_ERROR
Description
Document has no DOCX source (PDF-only documents are not supported).

POST/v2/documents/{id}/assign-variables

Assign variables (B6)

Persiste la asignación de cada variable a un rol, a un valor fijo del dueño, o la deja sin asignar. Crea las filas DocumentVariable que después llenarán los firmantes durante el flujo de firma.

Cuándo usarlo:

Después de B5 (detect), asignas las variables detectadas
Al crear el documento, ya sabes qué variables llenarán los firmantes
Necesitas sender-fixed variables: roleId=null, value="2026-01-15"

Idempotente: Re-llamar con el mismo payload actualiza filas existentes en lugar de crear duplicadas.

Request

Asignar variables

POST

/v2/documents/{id}/assign-variables

curl -X POST "https://api.allsign.io/v2/documents/doc-uuid-123/assign-variables" \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK" \
  -H "Content-Type: application/json" \
  -d '{
    "assignments": [
      {
        "variableName": "arrendador__nombre",
        "roleId": "role-uuid-1",
        "label": "Nombre del arrendador",
        "type": "text",
        "required": true
      },
      {
        "variableName": "sender__fecha_inicio",
        "roleId": null,
        "label": "Fecha de inicio",
        "value": "2026-01-15",
        "type": "date",
        "required": false
      },
      {
        "variableName": "testigo__nombre",
        "roleName": "Testigo",
        "label": "Nombre del testigo",
        "type": "text",
        "required": true
      }
    ]
  }'

Request body

Name
assignments
Type
array
Description
Lista de asignaciones de variables. Cada elemento debe tener variableName + uno de: roleId, value, o roleName.
Name
assignments[].variableName
Type
string
Description
Nombre exacto de la variable detectada (ej. arrendador__nombre).
Name
assignments[].roleId
Type
string
Description
UUID del rol que llenará esta variable. Obtenido de una llamada anterior a GET /documents/{id} o POST /add-signer. Mutuamente exclusivo con value (no ambos).
Name
assignments[].roleName
Type
string
Description
Nombre del rol a crear o reutilizar (ej. "Arrendador"). Si no existe, se crea. Alternativa a roleId.
Name
assignments[].value
Type
string
Description
Valor fijo que el dueño proporciona (ej. "2026-01-15"). Solo se usa con roleId=null. El variable nunca lo ven los firmantes.
Name
assignments[].type
Type
string
Description
Tipo de variable: text, date, number, rfc, etc. Por defecto, text.
Name
assignments[].required
Type
boolean
Description
¿Es requerido que el firmante llene esta variable? Por defecto, true.
Name
assignments[].scopePdfId
Type
string
Description
Para documentos compound: si la variable tiene el mismo nombre en múltiples PDFs pero son conceptos distintos, set scopePdfId para que cada PDF tenga su propia variable. Por defecto, null (valor compartido).
Name
assignments[].validation
Type
object
Description
Reglas de validación (p.ej. regex, longitud mín/máx). Ejemplo: {"pattern": "^[A-Z0-9]{10}$"} para RFC.

Response (200 OK)

{
  "documentId": "doc-uuid-123",
  "created": 2,
  "updated": 1,
  "chipsCreated": 3,
  "total": 3,
  "variables": [
    {
      "id": "var-uuid-1",
      "variableName": "arrendador__nombre",
      "roleId": "role-uuid-1",
      "label": "Nombre del arrendador",
      "type": "text",
      "required": true,
      "value": null,
      "action": "created"
    },
    {
      "id": "var-uuid-2",
      "variableName": "sender__fecha_inicio",
      "roleId": null,
      "label": "Fecha de inicio",
      "type": "date",
      "required": false,
      "value": "2026-01-15",
      "action": "created"
    },
    {
      "id": "var-uuid-3",
      "variableName": "testigo__nombre",
      "roleId": "role-uuid-2",
      "label": "Nombre del testigo",
      "type": "text",
      "required": true,
      "value": null,
      "action": "updated"
    }
  ]
}

Response fields

Name
documentId
Type
string
Description
El UUID del documento.
Name
created
Type
number
Description
Cantidad de variables nuevas creadas (no existían antes).
Name
updated
Type
number
Description
Cantidad de variables existentes que se actualizaron.
Name
chipsCreated
Type
number
Description
Cantidad de chips (overlays) creados en los PDFs para marcar dónde llenar variables.
Name
total
Type
number
Description
Cantidad total de variables procesadas en este request.
Name
variables
Type
array
Description
Lista completa de variables asignadas con su estado.
Name
variables[].action
Type
string
Description
created (nueva) o updated (modificada).

Error responses

Name
404 Not Found
Type
E1300_NOT_FOUND
Description
Document not found.
Name
409 Conflict
Type
E1200_VALIDATION_ERROR
Description
Document is in a terminal state (TODOS_FIRMARON, ANULADO, EXPIRADO) or locked in LLENANDO_DATOS/ESPERANDO_FIRMAS. Use POST /enter-correction first.
Name
422 Unprocessable Entity
Type
E1200_VALIDATION_ERROR
Description
Referenced roleId does not belong to this document, or the variable assignment is invalid.

Integration flow

Para un ejemplo end-to-end con un .docx descargable (crear → detectar → asignar → firmantes → invitar), ve el Quickstart de Variables y roles. El flujo completo y los edge cases están en la guía Variables y roles.