Quickstart: Embedded Signing

Tu primera firma embebida en 4 pasos. Al final de esta guía, tendrás un documento firmable dentro de tu propia aplicación.

Requisitos previos

• Una API key de AllSign — necesitas tu secret key (allsign_live_sk_xxx). Es la única credencial que manejarás. El frontend nunca ve la secret key — recibe un client_secret efímero (15 min) que tu backend genera a partir de la secret key.
• Un proyecto web con frontend (React, Vue, Angular, vanilla JS)

Paso 1: Crea el documento (si aún no lo tienes)

Si ya tienes un document_id (porque lo creaste antes, o quieres montar el widget para un documento ya existente), salta al Paso 2.

curl -X POST "https://api.allsign.io/v2/documents" \
  -H "Authorization: Bearer allsign_live_sk_TU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contrato de servicios",
    "documents": [
      {
        "name": "Contrato de servicios",
        "base64Content": "'$(base64 -i contrato.pdf)'",
        "fileType": "pdf"
      }
    ],
    "participants": [
      { "name": "Juan Pérez", "email": "juan@empresa.com" }
    ],
    "signatureValidation": { "autografa": true }
  }'

Respuesta:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Contrato de servicios",
  "pdfHash": "sha256:9f8a7b6c5d4e3f2a...",
  "creditsConsumed": 1,
  "createdAt": "2026-04-23T12:00:00Z"
}

Autógrafa o firma simple

El widget toma el modo de firma del documento; no hay nada que configurar en el SDK.

• Firma autógrafa ("signatureValidation": { "autografa": true }): el firmante dibuja su firma en los campos que colocaste. Antes de crear la sesión, coloca al menos un campo para ese firmante con POST /v2/documents/{id}/signature-fields; sin campo, POST /v2/signing-sessions responde 409 SIGNER_HAS_NO_SIGNATURE_FIELDS.
• Firma simple ("signatureValidation": { "simple": true }): el firmante lee el documento dentro del widget y lo acepta con el botón «Acepto firmar». No necesita campos de firma.

En los dos modos, los pasos de verificación que actives en signatureValidation (e.firma con FEA, verificación de identidad) corren dentro del widget antes de la firma, y tu app recibe los mismos eventos: onReady, onSuccess y onExit.

Paso 2: Genera una Signing Session con el document_id

Con el document_id del paso anterior (o de cualquier documento existente), genera una Signing Session. Esto devuelve el client_secret que tu frontend necesita para montar el widget.

curl -X POST "https://api.allsign.io/v2/signing-sessions" \
  -H "Authorization: Bearer allsign_live_sk_TU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "550e8400-e29b-41d4-a716-446655440000",
    "signer_email": "juan@empresa.com",
    "success_url": "https://tuapp.com/firmado",
    "cancel_url": "https://tuapp.com/cancelado",
    "allowed_origins": ["https://tuapp.com"]
  }'

Respuesta:

{
  "id": "as_sess_550e8400-e29b-41d4-a716-446655440000",
  "client_secret": "as_sess_550e8400_secret_9f8a7b6c5d4e3f2a1b0c",
  "status": "pending",
  "document": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Contrato de servicios"
  },
  "signer": {
    "email": "juan@empresa.com",
    "name": "Juan Pérez"
  },
  "expires_at": "2026-04-10T15:45:00+00:00"
}

Las variables se llenan automáticamente en el documento — el firmante solo ve el documento final listo para firmar.

---

## Paso 3: Monta el widget en tu frontend

Instala el SDK y monta la experiencia de firma.

### Instalar el SDK

```bash
npm install @allsign/embedded

Opción A: Modal (la más fácil — 4 líneas)

Abre un overlay sobre tu aplicación. El firmante firma y, al terminar, ve la vista post-firma dentro del mismo overlay — el modal no se cierra solo (se cierra cuando el firmante toca "Cerrar"; ver abajo). Cero configuración de layout.

import { AllSign } from '@allsign/embedded';

// El client_secret viene de tu backend (Paso 2). Es la única credencial
// que el frontend necesita — efímero (15 min), single-use, scoped a una
// sola session.
const session = AllSign.init({
  clientSecret: 'as_sess_550e8400_secret_9f8a7b6c5d4e3f2a1b0c',
  onSuccess: (result) => {
    console.log('Firmado:', result.signatureId);
    // Actualiza tu UI
  },
  onExit: (metadata) => {
    console.log('Cerrado:', metadata.reason);
    // 'completed', 'cancelled', 'expired', 'error'
  },
});

// Abre el modal
session.modal();

Opción B: Inline (dentro de tu layout)

Monta el widget dentro de un div que tú controlas. Ideal para flujos donde la firma es parte de una página más grande.

const session = AllSign.init({
  clientSecret: 'as_sess_550e8400_secret_...',
  onSuccess: (result) => { /* ... */ },
});

session.inline('#firma-container');

<div id="firma-container" style="width: 100%; height: 600px;"></div>

Opción C: Slider (panel lateral — en roadmap)

Abre un panel lateral. El firmante firma sin perder el contexto de lo que estaba haciendo en tu app.

const session = AllSign.init({
  clientSecret: 'as_sess_550e8400_secret_...',
  onSuccess: (result) => { /* ... */ },
});

// position/width se ignoran por ahora; se monta como modal
session.slider({
  position: 'right',  // 'left' o 'right' (aún no aplica)
  width: 600,         // (aún no aplica)
});

Opción D: Sin JS — solo HTML (no-code) — en roadmap

Paso 4: Confirma via webhook (fuente de verdad)

Los callbacks del SDK (onSuccess, onExit) son para tu UI. Para acciones críticas en tu backend, usa webhooks:

app.post('/webhooks/allsign', (req, res) => {
  const event = req.body.event;

  if (event === 'signer.signed') {
    const { signer, progress } = req.body.data;
    console.log(`${signer.name} firmó — ${progress.completed}/${progress.total}`);
  }

  if (event === 'document.completed') {
    // Todos firmaron — descarga el PDF final
    const pdfUrl = req.body.pdf.s3_presigned_url;
    downloadAndStore(pdfUrl);
  }

  res.status(200).json({ received: true });
});

¿No quieres configurar webhooks?

Usa el callback onSuccess del SDK para saber que se firmó, y luego llama a POST /v2/signing-sessions/{id}/verify desde tu backend para obtener la evidencia legal. Si configuraste success_url al crear la sesión, la recibirás como metadata en el callback para redirigir al usuario cuando tú decidas:

onSuccess: (result) => {
  // result.success_url = 'https://tuapp.com/firmado' (si la configuraste)
  // El sessionId viene del objeto session creado en AllSign.init(), no de result
  await verifyOnBackend(session.sessionId);
  window.location.href = result.success_url || '/dashboard';
}

Verificación end-to-end

Tu integración está completa cuando:

1. El widget se carga dentro de tu aplicación (callback onReady)
2. El firmante firma sin salir de tu sitio (callback onSuccess)
3. Tu servidor confirma via POST /verify o webhook signer.signed

Variables del template

Si usas templates con variables, llénalas desde tu backend al crear el documento. La opción values del SDK no tiene efecto en 0.3.x: se acepta y se ignora, así que no pre-llena nada en el widget.

Siguiente paso

• JS SDK Reference — API completa, React hook, TypeScript types
• Personalización — Qué se puede personalizar hoy y qué está planeado
• Eventos y Callbacks — Todos los eventos y callbacks disponibles
• Errores — Qué hacer cuando algo falla: taxonomía y recuperación