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)

¿Quieres probar sin afectar producción? Usa test_mode: true en la llamada API. Los documentos se generan con marca de agua, no consumen créditos y el flujo funciona idéntico.

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.

POST

/v2/documents

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",
    "document": {
      "base64Content": "'$(base64 -i contrato.pdf)'"
    },
    "participants": [
      { "name": "Juan Pérez", "email": "juan@empresa.com" }
    ],
    "signatureValidation": { "autografa": true }
  }'

Respuesta:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Contrato de servicios",
  "status": "PENDIENTE",
  "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.

POST

/v2/signing-sessions

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?session={SESSION_ID}",
    "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",
    "name": "Contrato de servicios"
  },
  "signer": {
    "email": "juan@empresa.com",
    "name": "Juan Pérez"
  },
  "expires_at": "2026-04-10T15:45:00+00:00"
}

El client_secret es lo único que tu frontend necesita. Es efímero (15 min), single-use y no expone tu secret key. Pásalo al frontend — el SDK se encarga del resto.

También funciona con documentos ya firmados — el widget se monta en modo lectura, permitiendo que el usuario vea el documento y sus firmas sin poder modificarlo.


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 el modal se cierra. Cero configuración de layout.

Frontend — Modal

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)

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) => { /* ... */ },
});

session.slider({
  position: 'right',  // 'left' o 'right'
  width: 600,
});

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

Para WordPress, Webflow o cualquier sitio estático:

<div
  data-allsign-session="as_sess_550e8400_secret_..."
  data-allsign-mode="inline"
  data-allsign-locale="es-MX"
  style="width: 100%; height: 600px;">
</div>
<script src="https://js.allsign.io/v1.js" async></script>

El script detecta los atributos data-allsign-* y monta automáticamente. Cero JavaScript.

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:

POST

/tu-servidor/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:

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

Los callbacks del SDK son para feedback instantáneo al usuario. Los webhooks son la fuente de verdad para tu backend. Siempre confirma el estado del documento via webhook antes de tomar acciones críticas (liberar pago, activar servicio, etc.).

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