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: multipart/form-data" \
  -F "title=Contrato de servicios" \
  -F "file=@contrato.pdf" \
  -F 'signers=[{"name": "Juan Pérez", "email": "juan@empresa.com"}]' \
  -F 'signature_validations={"autografa": true}'

Respuesta:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Contrato de servicios",
  "status": "PENDIENTE",
  "signers": [
    {
      "signature_id": "9a8b7c6d-5e4f-3210-fedc-ba0987654321",
      "name": "Juan Pérez",
      "email": "juan@empresa.com",
      "status": "PENDING"
    }
  ]
}

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?session={SESSION_ID}",
    "cancel_url": "https://tuapp.com/cancelado"
  }'

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 el modal se cierra. 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)

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/embed.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:

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 la return URL

Si solo necesitas saber que se firmó (sin recibir el PDF server-side), la success_url que configuraste en el Paso 1 recibe query params con el resultado:

https://tuapp.com/firmado?session=as_sess_550e8400&status=completed&document_id=550e8400&signer=juan@empresa.com

Esto es suficiente para flujos simples. Para producción, recomendamos webhooks.

Verificación end-to-end

Tu integración está completa cuando:

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

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:

allsign.inline('#firma-container', {
  clientSecret: 'as_sess_550e8400_secret_...',
  values: {
    nombre_cliente: 'Juan Pérez',
    rfc: 'PEPJ900101ABC',
    direccion: 'Av. Insurgentes Sur 1234, CDMX'
  },
});

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