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"
}

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',
  locale: 'es-MX',
  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_...',
  locale: 'es-MX',
  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

Pre-fill de variables desde el frontend (opcional)

Si usas templates con variables, puedes pre-llenarlas directamente desde el SDK sin una llamada extra al backend:

const session = AllSign.init({
  clientSecret: 'as_sess_550e8400_secret_...',
  values: {
    nombre_cliente: 'Juan Pérez',
    rfc: 'PEPJ900101ABC',
    direccion: 'Av. Insurgentes Sur 1234, CDMX'
  },
});

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

Las variables se inyectan en el documento antes de que el firmante lo vea.

Siguiente paso

• JS SDK Reference — API completa, React hook, TypeScript types
• Personalización — Branding, temas y locale
• Eventos y Callbacks — Todos los eventos y callbacks disponibles
• Errores — Qué hacer cuando algo falla: taxonomía y recuperación