Certalya - The authority for digital trust

Integrar firma electronica en tu aplicacion puede parecer complejo, pero con la API adecuada y una guia clara, puedes tener un flujo de firma funcionando en cuestion de horas. En este articulo te mostramos como hacerlo paso a paso.

Arquitectura de la integracion

La integracion tipica de firma electronica sigue una arquitectura cliente-servidor donde:

Tu aplicacion (Frontend)
        |
        v
Tu servidor (Backend)
        |
        v
  API Certalya
        |
        v
  Servicio de Firma
  (HSM cualificado)

Paso 1: Obtener credenciales de API

El primer paso es registrarte en el portal de desarrolladores y obtener tus credenciales:

# Variables de entorno necesarias
CERTALYA_API_KEY=tu_api_key_aqui
CERTALYA_API_SECRET=tu_api_secret_aqui
CERTALYA_ENVIRONMENT=sandbox # o 'production'

Paso 2: Instalar el SDK

Ofrecemos SDKs para los lenguajes mas populares:

# Node.js / JavaScript

npm install @certalya/sdk

# Python

pip install certalya

# Java

<dependency> <groupId>com.certalya</groupId> <artifactId>sdk</artifactId> </dependency>

# PHP

composer require certalya/sdk

Paso 3: Crear una solicitud de firma

El flujo basico para solicitar una firma es el siguiente:

// Ejemplo en JavaScript/Node.js
const Certalya = require('@certalya/sdk');

const client = new Certalya({
  apiKey: process.env.CERTALYA_API_KEY,
  apiSecret: process.env.CERTALYA_API_SECRET,
  environment: 'sandbox'
});

// Crear solicitud de firma
const signatureRequest = await client.signatures.create({
  document: {
    name: 'contrato.pdf',
    content: documentBase64, // PDF en base64
  },
  signers: [
    {
      name: 'Juan Garcia',
      email: 'juan@ejemplo.com',
      phone: '+34600000000',
      signatureType: 'advanced', // o 'qualified'
    }
  ],
  callbackUrl: 'https://tu-app.com/webhook/firma',
  redirectUrl: 'https://tu-app.com/firma-completada',
});

console.log('ID de solicitud:', signatureRequest.id);
console.log('URL de firma:', signatureRequest.signingUrl);

Paso 4: Redirigir al firmante

Una vez creada la solicitud, debes redirigir al firmante a la URL de firma. Puedes hacerlo de varias formas:

Opcion A: Redireccion completa

// Redirigir al usuario a la pagina de firma
window.location.href = signatureRequest.signingUrl;

Opcion B: Embebido en iframe

<iframe
  src={signatureRequest.signingUrl}
  width="100%"
  height="600"
  frameBorder="0"
/>

Opcion C: Componente React

import { SignatureWidget } from '@certalya/react';

function MiComponente() {
  return (
    <SignatureWidget
      requestId={signatureRequest.id}
      onComplete={(result) => {
        console.log('Firma completada:', result);
      }}
      onError={(error) => {
        console.error('Error:', error);
      }}
    />
  );
}

Paso 5: Recibir el webhook

Cuando el firmante complete el proceso, recibiras una notificacion en tu callback URL:

// Ejemplo de webhook handler en Express.js
app.post('/webhook/firma', async (req, res) => {
  const { event, data } = req.body;

  // Verificar firma del webhook
  const isValid = client.webhooks.verify(
    req.headers['x-certalya-signature'],
    req.body
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  switch (event) {
    case 'signature.completed':
      // Descargar documento firmado
      const signedDoc = await client.signatures.download(data.requestId);
      // Guardar en tu sistema...
      break;

    case 'signature.rejected':
      // Manejar rechazo...
      break;

    case 'signature.expired':
      // Manejar expiracion...
      break;
  }

  res.status(200).send('OK');
});

Opciones avanzadas

Multiples firmantes

Puedes configurar flujos con multiples firmantes, ya sea en paralelo o secuencial:

const signatureRequest = await client.signatures.create({
  document: { /* ... */ },
  signers: [
    { name: 'Firmante 1', email: 'f1@ejemplo.com', order: 1 },
    { name: 'Firmante 2', email: 'f2@ejemplo.com', order: 2 },
    { name: 'Firmante 3', email: 'f3@ejemplo.com', order: 2 }, // paralelo con F2
  ],
  workflow: 'sequential', // o 'parallel'
});

Campos de firma posicionados

Especifica donde debe aparecer la firma en el documento:

const signatureRequest = await client.signatures.create({
  document: { /* ... */ },
  signers: [{
    name: 'Juan Garcia',
    email: 'juan@ejemplo.com',
    signatureFields: [{
      page: 3,
      x: 100,
      y: 500,
      width: 200,
      height: 50,
    }]
  }],
});

Buenas practicas

Siempre verifica los webhooks: Nunca proceses un webhook sin verificar su firma.
Implementa reintentos: Los webhooks pueden fallar; implementa logica de reintento.
Usa el entorno sandbox: Prueba exhaustivamente antes de pasar a produccion.
Almacena los IDs: Guarda siempre el ID de la solicitud para poder consultarla despues.
Maneja errores: Implementa manejo de errores robusto para todos los casos edge.

Soporte y recursos

Si tienes dudas durante la integracion, puedes:

Consultar la documentacion completa en docs.certalya.com
Revisar los ejemplos de codigo en GitHub
Contactar con nuestro equipo de soporte tecnico
Unirte a nuestra comunidad de desarrolladores en Discord

Integracion de firma electronica en tu aplicacion: guia tecnica