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 y los permisos de acceso.

Attributes

Name
id
Type
string
Description
Identificador único del documento (UUID v4).
Name
name
Type
string
Description
Nombre del documento visible en la interfaz (1-255 caracteres).
Name
document
Type
object
Description
Objeto que contiene el archivo PDF codificado en Base64 y su nombre original.
Name
participants
Type
array
Description
Lista de firmantes del documento. Cada participante tiene email, nombre y opcionalmente WhatsApp.
Name
signatureValidation
Type
object
Description
Configuración de validaciones de firma: autógrafa, FEA, eIDAS, NOM-151, biométrica.
Name
config
Type
object
Description
Controla el flujo de invitaciones y el paso inicial del documento.
Name
permissions
Type
object
Description
Define el propietario del documento y los colaboradores con permisos granulares.
Name
folderId
Type
string
Description
ID de la carpeta donde se almacena el documento. Si es vacío o no se especifica, se guarda en la raíz.
Name
createdAt
Type
datetime
Description
Fecha de creación del documento en formato ISO 8601.
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": "Contrato de Servicios 2025",
  "document": {
    "name": "contrato.pdf",
    "base64Content": "JVBERi0xLjQK..."
  },
  "participants": [
    {
      "email": "ceo@empresa.com",
      "name": "CEO Empresa",
      "whatsapp": "+525512345678"
    }
  ],
  "signatureValidation": {
    "autografa": true,
    "FEA": false,
    "eIDAS": false,
    "nom151": false,
    "biometric_signature": false,
    "confirm_name_to_finish": false
  },
  "config": {
    "sendInvitations": false,
    "sendByWhatsapp": false,
    "sendByEmail": false,
    "startAtStep": 1
  },
  "permissions": {
    "ownerEmail": "ceo@empresa.com"
  },
  "folderId": "",
  "createdAt": "2024-11-23T20:00:00Z",
  "creditsConsumed": 1
}

The `document` object

Contiene el archivo PDF y su metadata.

Name
base64Content
Type
string
Description
Contenido del PDF codificado en Base64. Máximo 50 MB decodificados. El sistema valida automáticamente que sea un PDF válido. Si envías un archivo .docx, lo subes igualmente en Base64 y el backend lo convierte a PDF antes de guardarlo, por lo que no necesitas realizar la conversión manual.
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. Se normaliza automáticamente a minúsculas y se valida el formato.
Name
name
Type
string
Description
Nombre completo del participante. Aparece en las invitaciones y en el documento firmado.
Name
whatsapp
Type
string
Description
Número de WhatsApp con código de país (ej. +525512345678). Requerido si config.sendByWhatsapp es true.
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.

Name
autografa
Type
boolean
Description
Habilita firma autógrafa (dibujo de firma). Es el método predeterminado y más común.
Name
FEA
Type
boolean
Description
Habilita Firma Electrónica Avanzada. Requiere certificado digital del firmante.
Name
eIDAS
Type
boolean
Description
Habilita validación eIDAS para cumplimiento europeo.
Name
nom151
Type
boolean
Description
Habilita Constancia de Conservación NOM-151 para cumplimiento fiscal mexicano.
Name
biometric_signature
Type
boolean
Description
Habilita captura de datos biométricos durante la firma.
Name
confirm_name_to_finish
Type
boolean
Description
Requiere que el firmante confirme su nombre antes de completar la firma.

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. Si es false, el documento se crea pero las invitaciones se envían manualmente después.
Name
sendByWhatsapp
Type
boolean
Description
Envía invitaciones por WhatsApp. Requiere que todos los participantes tengan el campo whatsapp definido.
Name
sendByEmail
Type
boolean
Description
Envía invitaciones por correo electrónico.
Name
startAtStep
Type
integer
Description
Paso inicial del documento:
- 1: Solo se sube el archivo (sin participantes configurados)
- 2: Archivo subido con participantes definidos
- 3: Listo para firma (requiere al menos un participante)

Para el setup inicial, recomendamos sendInvitations=false y startAtStep=1. Esto te permite revisar el documento y configurar campos de firma antes de notificar a los participantes.

The `permissions` object

Define quién es el propietario del documento y qué colaboradores tienen acceso.

Name
ownerEmail
Type
string
Description
Email del propietario del documento.
Comportamiento por defecto: Si omites este campo o lo envías como null, el propietario será automáticamente el usuario asociado al API key que realizó la llamada. Esto significa que no necesitas especificarlo si el creador del documento es quien debe ser el owner.
Cuándo especificarlo: Usa este campo cuando quieras que otra persona de tu organización sea el propietario del documento. El email debe corresponder a un usuario existente en tu cuenta.
Name
collaborators
Type
array
Description
Lista de colaboradores con permisos específicos sobre el documento. Cada colaborador tiene un email y un conjunto de permisos granulares (canView, canEdit, canDelete, etc.).

Ejemplo: Crear documento como owner vs. asignar a otro usuario

// Caso 1: El creador (API key owner) es el propietario
// No necesitas especificar permissions.ownerEmail
const response = await fetch('https://api.allsign.io/v2/documents', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ALLSIGN_LIVE_SK', // Este usuario será el owner
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Contrato de Servicios',
    document: { name: 'contrato.pdf', base64Content: pdfBase64 },
    participants: [{ email: 'firmante@email.com', name: 'Firmante' }],
    // permissions omitido = owner es el usuario del API key
  }),
})

// Caso 2: Asignar ownership a otro usuario de la organización
const response = await fetch('https://api.allsign.io/v2/documents', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ALLSIGN_LIVE_SK',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Contrato de Servicios',
    document: { name: 'contrato.pdf', base64Content: pdfBase64 },
    participants: [{ email: 'firmante@email.com', name: 'Firmante' }],
    permissions: {
      ownerEmail: 'legal@miempresa.com', // Este usuario será el owner
    },
  }),
})

Si especificas un ownerEmail que no corresponde a un usuario existente en tu organización, el documento se creará pero el ownership se mantendrá con el usuario del API key.

The Document object

Attributes

THE DOCUMENT OBJECT

The document object

The participants array

The signatureValidation object

The config object

The permissions object