AllSign

The Document object

El objeto Document representa un documento en AllSign listo para firma. Este recurso contiene el archivo PDF, los participantes, la configuración de validaciones, los permisos de acceso y los campos de firma.

Attributes

  • Name
    id
    Type
    string
    Description

    Identificador único del documento (UUID v4).

  • Name
    name
    Type
    string
    Description

    Nombre del documento (obtenido de document.name).

  • Name
    documentType
    Type
    string
    Description

    Tipo de documento (ej. EDITABLE).

  • Name
    document
    Type
    object
    Description

    Objeto que contiene el archivo codificado en Base64 y su nombre original. Requerido a menos que se use templateId.

  • Name
    templateId
    Type
    string
    Description

    UUID de un template DOCX. Alternativa a document — mutuamente exclusivos.

  • Name
    templateValues
    Type
    object
    Description

    Pares clave-valor para inyectar en las variables del template. Solo se usa con templateId.

  • Name
    participants
    Type
    array
    Description

    Lista de firmantes del documento. Cada participante tiene email, nombre y opcionalmente WhatsApp.

  • Name
    fields
    Type
    array
    Description

    Campos de firma a crear junto con el documento.

  • Name
    signatureValidation
    Type
    object
    Description

    Configuración de validaciones de firma: autógrafa, FEA, eIDAS, NOM-151, biométrica, videofirma, y más.

  • Name
    config
    Type
    object
    Description

    Controla el flujo de invitaciones, el paso inicial del documento, y la expiración.

  • Name
    permissions
    Type
    object
    Description

    Define el propietario del documento.

  • Name
    folderId
    Type
    string
    Description

    ID de la carpeta donde se almacena el documento. Opcional.

  • Name
    ownerId
    Type
    string
    Description

    ID del usuario propietario del documento.

  • Name
    orgId
    Type
    string
    Description

    ID de la organización a la que pertenece.

  • Name
    createdAt
    Type
    datetime
    Description

    Fecha de creación del documento en formato ISO 8601.

  • Name
    updatedAt
    Type
    datetime
    Description

    Fecha de última actualización en formato ISO 8601.

  • Name
    signersData
    Type
    object
    Description

    Estado del flujo de firma: status general y lista de firmas individuales.

  • Name
    creditsConsumed
    Type
    integer
    Description

    Número de créditos document_signature consumidos (normalmente 1).

THE DOCUMENT OBJECT

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Contract 2024.pdf",
  "documentType": "EDITABLE",
  "createdAt": "2024-11-23T10:00:00Z",
  "updatedAt": "2024-11-23T10:00:00Z",
  "ownerId": "550e8400-e29b-41d4-a716-446655440001",
  "orgId": "550e8400-e29b-41d4-a716-446655440002",
  "activePublicUrl": false,
  "signersData": {
    "id": "cdc27f13-4d05-47d0-9690-fb69d005e7f8",
    "status": "TODOS_FIRMARON",
    "signatures": [
      {
        "id": "63db6fa9-2709-4f68-9ea7-bc640194bade",
        "status": "SIGNED",
        "signer": {
          "id": "99dc8f00-be5f-4331-ae66-db71bc2f6ccb",
          "email": "firmante@empresa.com"
        }
      }
    ]
  }
}

The status lifecycle

Every document in AllSign follows a predictable lifecycle. The signersData.status field reflects where the document is in its signing flow.

Status values

StatusDescripción¿Qué puede hacer el owner?
RECOLECTANDO_FIRMANTESEl owner está agregando firmantes y configurando el tipo de firma.Agregar/quitar firmantes, cambiar validaciones.
SELLOS_PDFEl owner está configurando los sellos (campos de firma) y verificaciones adicionales (videofirma, ID, etc.).Posicionar campos de firma, actualizar signatureValidation.
ESPERANDO_FIRMASLas invitaciones fueron enviadas. El documento está esperando que los firmantes firmen.Ver progreso, entrar en modo corrección, extender deadline.
CORRIGIENDOEl owner está editando un documento activo (modo corrección). Los firmantes ven "documento en actualización".Agregar/quitar firmantes, modificar campos.
GENERANDO_PDFEl sistema está generando el PDF final con todas las firmas.Esperar (proceso automático).
TODOS_FIRMARONTodos los firmantes completaron su firma. El documento está finalizado.Descargar PDF firmado, ver evidencias.
EXPIRADOLa fecha límite de firma pasó sin que todos firmaran.Extender el deadline para reactivar.
ANULADOEl owner anuló el documento. Todas las firmas pendientes fueron canceladas.Eliminar el documento.

Transitions

No todas las transiciones de status son libres. Cada cambio de estado tiene un endpoint específico que ejecuta la lógica de negocio correspondiente (validaciones, créditos, notificaciones, etc.).

TransiciónEndpointDescripción
RECOLECTANDO_FIRMANTES → SELLOS_PDFPATCH /v2/documents/{id} con {"status": "SELLOS_PDF"}Avanza a la configuración de sellos.
SELLOS_PDF → ESPERANDO_FIRMASPOST /v2/documents/{id}/start-signingInicia el proceso de firma — cobra créditos y envía invitaciones.
ESPERANDO_FIRMAS → CORRIGIENDOPOST /v2/documents/{id}/enter-correctionEntra en modo corrección para editar el documento activo.
CORRIGIENDO → ESPERANDO_FIRMASPOST /v2/documents/{id}/exit-correctionSale del modo corrección — firmantes pueden continuar.
ESPERANDO_FIRMAS → EXPIRADOAutomáticoOcurre cuando se cumple expiresAt.
EXPIRADO → ESPERANDO_FIRMASPOST /v2/documents/{id}/extendReactiva un documento expirado con nueva fecha límite.
ESPERANDO_FIRMAS → TODOS_FIRMARONAutomáticoOcurre cuando el último firmante completa su firma.
ESPERANDO_FIRMAS → ANULADOPOST /v2/documents/{id}/voidAnula el documento — cancela todas las firmas pendientes.
CORRIGIENDO → ANULADOPOST /v2/documents/{id}/voidAnula el documento desde modo corrección.
GENERANDO_PDF → ANULADOPOST /v2/documents/{id}/voidAnula el documento durante generación de PDF.

¿Por qué no puedo cambiar el status directamente? Cada transición tiene lógica de negocio asociada: start-signing cobra créditos, enter-correction bloquea a los firmantes, etc. Permitir cambios de status arbitrarios rompería estas garantías. Solo RECOLECTANDO_FIRMANTES → SELLOS_PDF está disponible via PATCH porque es una transición de configuración sin efectos secundarios.

Voiding (Anulación)

El endpoint POST /v2/documents/{id}/void permite al owner anular un documento que tiene firmas en progreso. Al anular:

  1. El status cambia a ANULADO (estado terminal)
  2. Todas las firmas pendientes se marcan como CANCELLED
  3. Las firmas ya completadas se preservan en el audit trail (pero el documento no tiene validez legal)
  4. Se registra un evento document.voided con metadata del motivo y firmas canceladas

Estados que se pueden anular: ESPERANDO_FIRMAS, CORRIGIENDO, GENERANDO_PDF, RECOLECTANDO_FIRMANTES

Estados que NO se pueden anular: TODOS_FIRMARON (legalmente vinculante), EXPIRADO, ANULADO (ya anulado)

Deletion rules

No todos los documentos se pueden eliminar. Las reglas de eliminación protegen documentos con valor legal o procesos activos.

Status¿Eliminable?Motivo
RECOLECTANDO_FIRMANTES✅Draft — sin firmas iniciadas.
SELLOS_PDF✅Draft — configurando campos.
EXPIRADO✅Venció sin completarse.
ANULADO✅Anulado — no tiene firmas completadas.
ESPERANDO_FIRMAS❌Firmas en progreso. Debe anularse primero (POST /void).
CORRIGIENDO❌En corrección. Debe anularse primero.
GENERANDO_PDF❌PDF en generación. Debe anularse primero.
TODOS_FIRMARON❌Legalmente vinculante — no se puede eliminar nunca.

Flujo recomendado para eliminar un documento con firmas en progreso:

  1. Anular el documento: POST /v2/documents/{id}/void
  2. Eliminar: DELETE /v2/documents/{id} o DELETE /v2/documents/bulk

Permisos de eliminación (dashboard):

  • Owner/Admin del tenant: pueden eliminar cualquier documento de su workspace
  • Member: solo puede eliminar documentos que creó
  • Viewer: no puede eliminar documentos

The document object

Contiene el archivo y su metadata. Este es el único campo requerido al crear un documento.

  • Name
    base64Content
    Type
    string
    Description

    Contenido del archivo codificado en Base64. Máximo 50 MB decodificados. Soporta PDF y DOCX (se convierte a PDF automáticamente).

  • Name
    name
    Type
    string
    Description

    Nombre original del archivo con extensión (ej. contrato.pdf). Se usa para identificar el archivo en descargas y notificaciones.

The participants array

Lista de firmantes del documento. Cada elemento representa a una persona que debe firmar.

  • Name
    email
    Type
    string
    Description

    Correo electrónico del participante (formato email validado, auto-normalizado a minúsculas).

  • Name
    name
    Type
    string
    Description

    Nombre completo del participante (1-255 caracteres).

  • Name
    whatsapp
    Type
    string
    Description

    Número de WhatsApp con código de país (ej. +525512345678). Opcional. Cuando sendInvitations es true, la API detecta automáticamente si enviar por email o WhatsApp según la información de contacto del participante.

  • Name
    invitedBy
    Type
    string
    Description

    Email del usuario que invitó a este participante. Se asigna automáticamente si no se especifica.

No se permiten participantes duplicados. Si envías el mismo email dos veces, el sistema responde con 422 Unprocessable Entity.

The signatureValidation object

Controla qué tipos de validación se aplican a las firmas del documento.

Core flags

  • Name
    autografa
    Type
    boolean
    Description

    Habilita firma autógrafa (dibujo de firma). Es el método predeterminado.

  • Name
    FEA
    Type
    boolean
    Description

    Habilita Firma Electrónica Avanzada. Requiere certificado digital del firmante. Case-insensitive: acepta FEA o fea.

  • Name
    eIDAS
    Type
    boolean
    Description

    Habilita validación eIDAS para cumplimiento europeo. Case-insensitive: acepta eIDAS, EIDAS o eidas.

  • Name
    nom151
    Type
    boolean
    Description

    Habilita Constancia de Conservación NOM-151 para cumplimiento fiscal mexicano.

  • Name
    confirm_name_to_finish
    Type
    boolean
    Description

    Requiere que el firmante confirme su nombre antes de completar la firma.

  • Name
    id_scan
    Type
    boolean
    Description

    Escaneo de identificación (INE, pasaporte, etc.) como paso standalone.

  • Name
    videofirma
    Type
    boolean
    Description

    Grabación en video del firmante durante el proceso de firma.

  • Name
    ai_verification
    Type
    boolean
    Description

    Flag legacy de verificación AI. Preferir los flags modulares individuales listados abajo.

Modular verification flags

Flags granulares para control individual sobre el pipeline de verificación AI.

  • Name
    document_scan
    Type
    boolean
    Description

    Clasificación de documentos con AI + extracción OCR (GPT-4o). Identifica tipo de documento y extrae datos relevantes.

  • Name
    name_verification
    Type
    boolean
    Description

    Extracción MRZ + verificación cruzada de nombre (FastMRZ, determinístico).

  • Name
    selfie_capture
    Type
    boolean
    Description

    Captura de selfie y verificación de que es una cara real (sin comparación biométrica). Requerido si biometric_face_match está habilitado.

  • Name
    biometric_face_match
    Type
    boolean
    Description

    Selfie + comparación biométrica ArcFace contra la foto del ID. Requiere selfie_capture habilitado.

  • Name
    deep_fake_shield
    Type
    boolean
    Description

    Detección anti-fraude ML de deepfakes.

  • Name
    anti_spoof_shield
    Type
    boolean
    Description

    Detección de ataques de presentación (fotos impresas, replay de pantalla).

  • Name
    id_reuse_policy
    Type
    string
    Description

    Controla si se reutiliza la verificación de identidad previa de un firmante. auto omite el escaneo si ya existe una verificación previa; always_new siempre solicita captura nueva.

Si omites signatureValidation completamente, se aplican los valores por defecto: solo autografa=true, el resto en false.

The config object

Controla el comportamiento del flujo de firma.

  • Name
    sendInvitations
    Type
    boolean
    Description

    Si es true, envía invitaciones automáticamente a los participantes al crear el documento. La API detecta el mejor canal (email o WhatsApp) por cada participante según su información de contacto.

  • Name
    startAtStep
    Type
    integer
    Description

    Paso inicial del documento (1-3):

    • 1: Solo se sube el archivo (sin participantes configurados)
    • 2: Archivo subido con participantes definidos
    • 3: Listo para firma (requiere al menos un participante)
  • Name
    expiresAt
    Type
    datetime
    Description

    Fecha límite opcional de firma (ISO 8601). Si se establece, el documento transiciona a EXPIRADO pasada esta fecha. Puede extenderse después con POST /v2/documents/{id}/extend.

  • Name
    expirationReminders
    Type
    array
    Description

    Días antes de la expiración para enviar recordatorios (ej. [1, 3, 7]). Cada valor debe estar entre 1 y 365. Máximo 10 entradas. Se ignora si expiresAt no está definido.

The permissions object

Controla la propiedad del documento. El comportamiento de ownerEmail depende del tipo de API key (auth_mode):

auth_modeownerEmailOwner del documento
api_keyOpcionalUsuario del API key (personal)
delegatedOpcionalUsuario delegado (acting_user_id)
appRequeridoEl usuario especificado en ownerEmail

App-mode keys: Si tu API key es de tipo app (multi-usuario), debes especificar ownerEmail. La API responde 422 si no lo envías. Esto previene asignar ownership ambiguo en contextos multi-tenant.

¿Quién puede ver un documento?

AllSign determina el acceso a un documento evaluando estas condiciones en orden:

#CondiciónAcceso¿Cómo se configura?
1Es el owner del documentoCompleto (leer, editar, eliminar)Automático al crear, o via ownerEmail
2Es miembro del tenant con rol admin u ownerVer todos los docs del tenantDashboard → Equipo → Roles
3Es miembro del tenant con permiso documents:view_allVer (solo lectura)Dashboard → Equipo → Permisos
4Es firmante (participant)Acceso de firmaSe configura en el array participants
5Ninguna de las anteriores❌ Denegado—

Los firmantes obtienen acceso automáticamente. Cuando agregas a alguien como participant, el backend crea un registro de acceso (HasAccess) para ese usuario. Cuando el firmante inicia sesión en AllSign (o se le crea una cuenta guest), verá el documento listado en su panel. No necesitas configurar permisos adicionales.

Atributos

  • Name
    ownerEmail
    Type
    string
    Description

    Email del propietario del documento. El owner tiene acceso completo y no puede ser removido del documento. Debe ser miembro de tu tenant.

    • auth_mode=app → Requerido. La API responde 422 Unprocessable Entity si no se especifica.
    • auth_mode=api_key → Opcional. Default: usuario del API key.
    • auth_mode=delegated → Opcional. Default: usuario delegado.

    Caso de uso típico: Un sistema automatizado (ej. tu backend) crea documentos a nombre de un usuario del equipo legal usando su email.

Escenarios

Delegación de ownership

Un sistema automatizado crea documentos a nombre de un miembro del equipo. El ownerEmail transfiere la propiedad.

Delegación — ownership por API

{
  "permissions": {
    "ownerEmail": "gerente.regional@empresa.com"
  },
  "participants": [
    {"email": "cliente@externo.com", "name": "Pedro Páramo"}
  ],
  "config": {
    "sendInvitations": true,
    "startAtStep": 3
  }
}

Sin permisos (API key personal — escenario más común)

Con API keys de tipo api_key o delegated, no necesitas enviar permissions. El owner se asigna automáticamente.

Sin permissions — owner automático (api_key / delegated)

{
  "document": {
    "name": "Contrato.pdf",
    "content": "base64..."
  },
  "participants": [
    {"email": "firmante@empresa.com", "name": "Juan Pérez"}
  ]
}

En este ejemplo, firmante@empresa.com podrá ver y firmar el documento cuando inicie sesión. El owner del doc será el usuario que posee el API key utilizado.

App-mode — ownerEmail requerido

Cuando tu API key tiene auth_mode=app, siempre debes especificar ownerEmail. Si lo omites, la API responde 422.

App-mode — ownerEmail obligatorio

{
  "permissions": {
    "ownerEmail": "gerente@empresa.com"
  },
  "document": {
    "name": "Contrato.pdf",
    "base64Content": "JVBERi0xLjQ..."
  },
  "participants": [
    {"email": "cliente@externo.com", "name": "Pedro Páramo"}
  ],
  "config": {
    "sendInvitations": true,
    "startAtStep": 3
  }
}

The fields array

Campos de firma que se crean junto con el documento. Esto evita la necesidad de una llamada separada.

  • Name
    participantEmail
    Type
    string
    Description

    Email del participante que debe completar este campo.

  • Name
    pageNumber
    Type
    integer
    Description

    Número de página donde colocar el campo (1-indexed). Default: 1.

  • Name
    pageNumbers
    Type
    array
    Description

    Lista específica de páginas donde poner el campo. Conflicta con includeInAllPages.

  • Name
    position
    Type
    object
    Description

    Coordenadas del campo: {"x": 100, "y": 650}.

  • Name
    anchorString
    Type
    string
    Description

    Texto en el PDF para usar como referencia de posición.

  • Name
    includeInAllPages
    Type
    boolean
    Description

    Si true, el campo aparece en todas las páginas.

  • Name
    excludeFromPages
    Type
    array
    Description

    Páginas a excluir cuando includeInAllPages=true (1-indexed).

  • Name
    height
    Type
    number
    Description

    Alto del campo de firma en puntos. El ancho se calcula automáticamente con ratio 2:1.

{
  "fields": [
    {
      "participantEmail": "firmante@empresa.com",
      "pageNumber": 2,
      "position": {"x": 100, "y": 650},
      "height": 100
    }
  ]
}

Was this page helpful?