Embed de firma

El embed de firma presenta el proceso de una persona destinataria dentro de tu aplicación mediante EmbedSignDocument. Antes de mostrarlo, tu servidor debe comprobar que el usuario tiene derecho a acceder al documento y al destinatario seleccionados.

Secuencia del flujoCopiar link al encabezado

1. Prepara el sobre, sus PDFs, destinatarios y campos en el servidor.
2. Revisa y distribuye el sobre cuando el proceso esté autorizado para comenzar.
3. Consulta el destinatario con la clave de API y conserva su token de forma protegida.
4. Entrega al frontend únicamente el acceso correspondiente a ese destinatario.
5. Monta EmbedSignDocument desde el paquete de embed de tu framework, con ese token y el host de Digito Business.
6. Consulta el sobre en tu servidor para confirmar el resultado.

No expongas toda la respuesta del destinatario al frontend. Los IDs y tokens no sustituyen la autorización de acceso de tu aplicación.

Obtén el token del destinatarioCopiar link al encabezado

Después de distribuir el sobre, consulta GET /api/v2/envelope/recipient/{recipientId} desde tu servidor. Usa el ID real que guardaste al preparar los destinatarios y comprueba su acceso antes de realizar la consulta.

const apiToken = process.env.DIGITO_API_TOKEN;
if (!apiToken) throw new Error('Falta DIGITO_API_TOKEN');

// Antes de esta consulta, autentica al usuario y comprueba que puede
// acceder al sobre y a este destinatario dentro de tu aplicación.
const recipientId = 123; // Sustituye por el ID autorizado de tu proceso.
const response = await fetch(
  `https://business.digito.do/api/v2/envelope/recipient/${recipientId}`,
  { headers: { Authorization: apiToken } }
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);

const recipient = (await response.json()) as { id: number; token: string };
if (recipient.id !== recipientId || !recipient.token) {
  throw new Error('No se obtuvo el acceso esperado');
}

// Devuelve únicamente este token al usuario autorizado, sin registrar
// credenciales ni permitir que la respuesta quede en una caché compartida.
const accesoFirma = { token: recipient.token };

La clave de API autentica la consulta del servidor; recipient.token abre la vista del destinatario. Conserva en tu sistema la relación entre el usuario, el sobre y el destinatario. El ejemplo muestra la consulta a Business: la sesión, los permisos y el endpoint que entrega accesoFirma los implementa tu aplicación.

Si tu sistema crea documentos a partir de una plantilla, primero reutiliza la plantilla mediante la API y trabaja después con los destinatarios del documento creado.

Monta el componente de embedCopiar link al encabezado

Instala el paquete de tu framework. Este ejemplo utiliza React y recibe el token que tu servidor entregó al usuario autorizado. Los ejemplos siguen el contrato previsto de los paquetes de Digito, cuya publicación está en preparación.

import { EmbedSignDocument } from '@digitogroup/embed-react';

export function FirmaDocumento({
  token,
  confirmarResultado,
}: {
  token: string;
  confirmarResultado: () => void;
}) {
  return (
    <div style={{ height: '800px', width: '100%' }}>
      <EmbedSignDocument
        key={token}
        host="https://business.digito.do"
        token={token}
        language="es"
        onDocumentReady={() => {
          // Oculta el indicador de carga de tu aplicación.
        }}
        onDocumentCompleted={() => confirmarResultado()}
        onDocumentError={() => {
          // Muestra un error y permite consultar el estado o reintentar.
        }}
      />
    </div>
  );
}

confirmarResultado es una función de tu aplicación: debe solicitar a tu servidor la consulta del sobre asociado con esta vista. Indica siempre host="https://business.digito.do". El alto es un ejemplo de presentación; ajústalo a tu contenedor y comprueba la lectura del PDF en móvil.

Propiedades de EmbedSignDocumentCopiar link al encabezado

Las opciones de apariencia del embed incluyen css, cssVars y darkModeDisabled. El CSS interno requiere que la organización tenga habilitada esa personalización.

Callback de finalizaciónCopiar link al encabezado

onDocumentCompleted recibe datos del proceso: token, documentId y recipientId; en el flujo de sobres V2 también puede incluir envelopeId. documentId y recipientId son numéricos, mientras que envelopeId es una cadena.

No registres el token ni aceptes los identificadores del navegador como autorización. Conserva el sobre y el destinatario esperados en tu servidor. Un callback indica el progreso de esa persona; no demuestra que todos los destinatarios hayan firmado. Los callbacks pueden repetirse y la pestaña puede cerrarse antes de recibirlos: la consulta del servidor debe ser la fuente del resultado.

Autenticación al firmarCopiar link al encabezado

El firmante se autentica de nuevo con Digito ID antes de cada acción de firma. Una sesión abierta en Business, una clave de API, un token de destinatario o un token de integración no sustituye esta autenticación.

El contenedor del embed debe permitir que la persona complete el flujo de Digito ID. No bloquees las acciones de autenticación ni intentes resolverlas con una clave de API. Si el flujo requiere abrir una ventana o cambiar de página, verifica que el usuario pueda volver al documento y continuar.

Resultado y fallosCopiar link al encabezado

Un evento visual de finalización o una redirección ayuda a la interfaz, pero tu servidor debe consultar el estado real del sobre antes de actualizar el contrato en tu sistema. Comprueba status, recipients[].signingStatus y el PDF final disponible.

Muestra una forma de reabrir el proceso si la persona cierra la ventana o la autenticación se interrumpe. Para un token vencido, vuelve a consultar el estado y obtén el acceso autorizado correspondiente; no reuses ciegamente un token antiguo.

Consulta las guías de frontend y servidor para organizar la vista y sus estados. Para confirmar el resultado, utiliza el seguimiento del sobre.