Contratos

Los contratos son documentos legales que requieren firmas electrónicas de múltiples participantes. Esta página te muestra ejemplos completos para implementar diferentes flujos de firma usando la API de AllSign.

Setup inicial: crear documento con Base64 (POST /v2/documents)

Este es el flujo base que usamos en AllSign para subir un PDF, convertirlo a Base64 y dejar el documento listo para continuar con configuraciones más avanzadas. Replica exactamente lo que hace nuestro endpoint /api/v2/documents/create del panel (proxy al backend FastAPI) @/Users/israelortiz/www/allsign/allsign-svelte-4/src/routes/api/v2/documents/create/+server.ts#63-330.

Convierte el PDF a Base64 (máx. 50 MB decodificados).
Envía el JSON a /v2/documents con el archivo y la configuración mínima: el usuario creador queda como primer participante, la validación predeterminada es firma autógrafa y no se envían invitaciones hasta que decidas avanzar.

POST

/v2/documents

PDF_BASE64=$(base64 -i ./contrato.pdf)

curl -X POST "https://api.allsign.io/v2/documents" \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contrato de Servicios 2025",
    "document": {
      "name": "contrato.pdf",
      "base64Content": "'$PDF_BASE64'"
    },
    "participants": [
      {
        "email": "ceo@empresa.com",
        "name": "CEO Empresa"
      }
    ],
    "signatureValidation": {
      "autografa": true,
      "FEA": false,
      "eIDAS": false,
      "nom151": false
    },
    "config": {
      "sendInvitations": false,
      "sendByWhatsapp": false,
      "sendByEmail": false,
      "startAtStep": 1
    },
    "permissions": {
      "ownerEmail": "ceo@empresa.com"
    }
  }'

Campos requeridos

Name
name
Type
string
Description
Nombre del documento (1-255 caracteres).
Name
document.base64Content
Type
string
Description
Contenido del PDF codificado en Base64 (máx. 50 MB decodificados).
Name
document.name
Type
string
Description
Nombre original del archivo con extensión (ej. contrato.pdf).

Campos opcionales recomendados en el setup inicial

Name
participants
Type
array
Description
Para el setup mínimo usamos al creador como primer participante. Puedes añadir más emails desde los endpoints de configuración posteriores.
Name
signatureValidation
Type
object
Description
Habilita/deshabilita validaciones avanzadas; aquí solo dejamos autografa=true.
Name
config
Type
object
Description
Controla envíos automáticos. En el setup inicial todo va en false para revisar el documento antes de notificar.
Name
permissions.ownerEmail
Type
string
Description
Define al owner del documento (por defecto el usuario autenticado).

Respuesta exitosa

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Contrato de Servicios 2025",
  "creditsConsumed": 1,
  "createdAt": "2024-11-23T20:00:00Z"
}

Descargar documento firmado

Una vez completado el proceso de firma, descarga el documento final con todas las firmas aplicadas.

GET

/v1/documents/{document_id}/download

# Usar el document_id del paso anterior
DOCUMENT_ID="doc_abc123xyz789"

curl -X GET "https://api.enterprise.allsign.io/v1/documents/${DOCUMENT_ID}/download" \
  -H "apiKey: TU_API_KEY_AQUI" \
  -H "onBehalfOfEmail: email_a_impersonificar@correo.com" \
  --output "contrato_firmado.pdf"

Respuesta exitosa

El endpoint retorna directamente el archivo PDF con todas las firmas aplicadas. El archivo incluye:

Todas las firmas electrónicas de los participantes
Certificados digitales de validación
Timestamps de cada firma
Metadatos de trazabilidad legal

Colocar campos de firma por texto de referencia

Posiciona campos de firma en ubicaciones específicas usando texto existente en el documento como referencia (anchorString).

POST

/api/documents/{document_id}/add-signature-field

# Usar el document_id del paso anterior
DOCUMENT_ID="doc_abc123xyz789"

curl -X POST "https://api.enterprise.allsign.io/api/documents/${DOCUMENT_ID}/add-signature-field" \
  -H "apiKey: TU_API_KEY_AQUI" \
  -H "onBehalfOfEmail: email_a_impersonificar@correo.com" \
  -H "Content-Type: application/json" \
  -d '{
    "signature_fields": [
      {
        "signer_email": "cliente@empresa.com",
        "anchor_string": "Firma del Cliente:",
        "field_type": "signature",
        "offset_x": 10,
        "offset_y": -20,
        "width": 200,
        "height": 50
      },
      {
        "signer_email": "proveedor@servicios.com",
        "anchor_string": "Firma del Proveedor:",
        "field_type": "signature", 
        "offset_x": 10,
        "offset_y": -20,
        "width": 200,
        "height": 50
      }
    ]
  }'

Parámetros requeridos

Name
signer_email
Type
string
Description
Email del firmante que debe completar este campo de firma.
Name
anchor_string
Type
string
Description
Texto exacto que existe en el PDF para usar como punto de referencia.
Name
field_type
Type
string
Description
Tipo de campo. Para firmas usar "signature".

Parámetros opcionales

Name
offset_x
Type
integer
Description
Desplazamiento horizontal en píxeles desde el anchor_string. Positivo = derecha, negativo = izquierda.
Name
offset_y
Type
integer
Description
Desplazamiento vertical en píxeles desde el anchor_string. Positivo = abajo, negativo = arriba.
Name
width
Type
integer
Description
Ancho del campo de firma en píxeles. Por defecto: 200.
Name
height
Type
integer
Description
Alto del campo de firma en píxeles. Por defecto: 50.

Cómo funciona anchorString

El anchor_string busca texto exacto en el PDF:

"Firma del Cliente:" → Encuentra este texto en el documento
offset_x: 10 → Mueve el campo 10px a la derecha del texto
offset_y: -20 → Mueve el campo 20px arriba del texto

Respuesta exitosa

{
  "fields_added": 2,
  "document_id": "doc_abc123xyz789",
  "signature_fields": [
    {
      "field_id": "field_abc123",
      "signer_email": "cliente@empresa.com",
      "anchor_string": "Firma del Cliente:",
      "position": {
        "page": 2,
        "x": 150,
        "y": 680
      },
      "status": "placed"
    },
    {
      "field_id": "field_def456",
      "signer_email": "proveedor@servicios.com", 
      "anchor_string": "Firma del Proveedor:",
      "position": {
        "page": 3,
        "x": 150,
        "y": 680
      },
      "status": "placed"
    }
  ]
}

Campos al calce en todas las páginas

Coloca automáticamente campos de firma al pie de cada página del documento.

POST

/api/documents/{document_id}/add-signature-fields

curl -X POST "https://api.enterprise.allsign.io/api/documents/{document_id}/add-signature-fields" \
  -H "apiKey: TU_API_KEY_AQUI" \
  -H "onBehalfOfEmail: email_a_impersonificar@correo.com" \
  -H "Content-Type: application/json" \
  -d '{
    "signature_fields": [
      {
        "signer_email": "cliente@empresa.com",
        "field_type": "signature",
        "position": "footer",
        "all_pages": true,
        "x_position": 100,
        "y_position": 50
      },
      {
        "signer_email": "proveedor@servicios.com",
        "field_type": "signature",
        "position": "footer", 
        "all_pages": true,
        "x_position": 300,
        "y_position": 50
      }
    ]
  }'

Campos múltiples en posiciones específicas

Coloca varios campos de firma en ubicaciones exactas usando coordenadas específicas en el documento.

POST

/api/documents/{document_id}/add-signature-fields

curl -X POST "https://api.enterprise.allsign.io/api/documents/{document_id}/add-signature-fields" \
  -H "apiKey: TU_API_KEY_AQUI" \
  -H "onBehalfOfEmail: email_a_impersonificar@correo.com" \
  -H "Content-Type: application/json" \
  -d '{
    "signature_fields": [
      {
        "signer_email": "cliente@empresa.com",
        "field_type": "signature",
        "page": 1,
        "x_position": 100,
        "y_position": 650,
        "width": 200,
        "height": 50
      },
      {
        "signer_email": "proveedor@servicios.com",
        "field_type": "signature",
        "page": 2,
        "x_position": 100,
        "y_position": 650,
        "width": 200,
        "height": 50
      }
    ]
  }'

Firma automática de todos los campos

Firma automáticamente todos los campos de un documento una vez completados por los firmantes.

POST

/v1/documents/{document_id}/sign-all-fields

curl -X POST "https://api.enterprise.allsign.io/v1/documents/{document_id}/sign-all-fields" \
  -H "apiKey: TU_API_KEY_AQUI" \
  -H "onBehalfOfEmail: email_a_impersonificar@correo.com" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_sign": true,
    "notify_completion": true,
    "completion_message": "Documento firmado automáticamente"
  }'

Flujo completo recomendado

Crear documento con /v1/documents/create_document_base64
Descargar documento con /v1/documents/{document_id}/download
Configurar campos con /api/documents/{document_id}/add-signature-field o /api/documents/{document_id}/add-signature-fields
Firma automática con /v1/documents/{document_id}/sign-all-fields
Monitorear estado con webhooks

Configurar webhooks para notificaciones