Editor de embed y tokens

El editor de embed permite crear y editar sobres dentro de otra aplicación mediante EmbedCreateEnvelope y EmbedUpdateEnvelope. Los sobres de la API V2 representan documentos y plantillas. Su autorización utiliza un token de integración, llamado presign token en la API. Una clave de API y un token de integración son credenciales distintas.

Crea el token en el servidorCopiar link al encabezado

curl --fail-with-body \
  'https://business.digito.do/api/v2/embedding/create-presign-token' \
  -H "Authorization: $DIGITO_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{}'

La respuesta contiene token, expiresAt y expiresIn. Usa expiresAt para gestionar el vencimiento. El contrato admite expiresIn y scope, pero no define en el esquema la unidad del primero ni un catálogo de ámbitos. El ejemplo conserva la configuración predeterminada y no inventa un ámbito.

Tu servidor debe autenticar al usuario de tu aplicación y comprobar su acceso al equipo antes de crear o entregar un token. No publiques un endpoint de emisión de tokens accesible sin autorización.

Verifica el tokenCopiar link al encabezado

curl --fail-with-body \
  'https://business.digito.do/api/v2/embedding/verify-presign-token' \
  -H "Authorization: $DIGITO_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
  "token": "token_de_integracion_de_ejemplo"
}'

{
  "success": true
}

La respuesta documentada contiene success, un booleano. No contiene una clave de API que debas extraer o reenviar al navegador.

Monta el editor de embedCopiar link al encabezado

Instala el paquete de embed de tu framework. Los ejemplos siguientes utilizan React y el contrato previsto de los paquetes de Digito, cuya publicación está en preparación. Indica siempre host="https://business.digito.do" y pasa el presignToken emitido por tu servidor.

Crea un sobreCopiar link al encabezado

type="DOCUMENT" crea un documento. externalId permite asociarlo con un proceso de tu sistema; no es una credencial ni sustituye la comprobación de permisos.

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

export function CrearSobre({
  presignToken,
  confirmarSobre,
}: {
  presignToken: string;
  confirmarSobre: (envelopeId: string) => void;
}) {
  return (
    <div style={{ height: '800px', width: '100%' }}>
      <EmbedCreateEnvelope
        host="https://business.digito.do"
        presignToken={presignToken}
        type="DOCUMENT"
        language="es"
        externalId="expediente-12345"
        onEnvelopeCreated={(data) => confirmarSobre(data.envelopeId)}
      />
    </div>
  );
}

confirmarSobre es una función de tu aplicación: debe solicitar a tu servidor la comprobación del sobre y guardar la relación con el usuario y su expediente. Para crear una plantilla reutilizable, cambia type a "TEMPLATE"; luego puedes crear documentos a partir de ella mediante la API.

Edita un sobre existenteCopiar link al encabezado

Entrega el envelopeId del borrador que el usuario puede editar, junto con un token vigente del equipo correspondiente. No aceptes un ID arbitrario sin autorización.

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

export function EditarSobre({
  presignToken,
  envelopeId,
  confirmarSobre,
}: {
  presignToken: string;
  envelopeId: string;
  confirmarSobre: (envelopeId: string) => void;
}) {
  return (
    <div style={{ height: '800px', width: '100%' }}>
      <EmbedUpdateEnvelope
        key={envelopeId}
        host="https://business.digito.do"
        presignToken={presignToken}
        envelopeId={envelopeId}
        language="es"
        externalId="expediente-12345"
        onEnvelopeUpdated={(data) => confirmarSobre(data.envelopeId)}
      />
    </div>
  );
}

Puedes preparar el borrador mediante HTTP y abrir después el editor de embed para que una persona autorizada revise sus PDFs, destinatarios y campos. Editar un borrador no firma el documento.

Propiedades del editorCopiar link al encabezado

CompartidasCopiar link al encabezado

Para crearCopiar link al encabezado

Para editarCopiar link al encabezado

Configura los controles con featuresCopiar link al encabezado

Puedes pasar una configuración parcial. Las propiedades omitidas conservan sus valores predeterminados; ocultar un control no cambia los permisos del usuario ni las reglas de firma.

<EmbedUpdateEnvelope
  host="https://business.digito.do"
  presignToken={presignToken}
  envelopeId={envelopeId}
  language="es"
  features={{
    general: { allowConfigureEnvelopeTitle: false },
    settings: { allowConfigureLanguage: false, allowConfigureTimezone: false },
    recipients: { allowApproverRole: false, allowViewerRole: false },
  }}
/>

GeneralCopiar link al encabezado

Desactiva un paso solo si el sobre ya contiene lo necesario para continuar. Por ejemplo, no ocultes la carga de PDFs al crear un sobre vacío que todavía necesita archivos.

Configuración del sobreCopiar link al encabezado

Todas las propiedades siguientes de settings tienen valor predeterminado true. Usa settings: null para ocultar la sección completa.

Archivos y adjuntosCopiar link al encabezado

actions.allowAttachments permite añadir adjuntos y tiene valor predeterminado true. En envelopeItems, las siguientes propiedades también son true de forma predeterminada. Usa envelopeItems: null para impedir modificaciones de los archivos desde la vista.

DestinatariosCopiar link al encabezado

Usa recipients: null para impedir modificaciones de destinatarios desde la vista. Digito Business aplica sus reglas de firma cualificada incluso si una opción solicita habilitar un control incompatible.

El editor utiliza el orden secuencial del flujo de firma cualificada. Una opción de features no permite saltarse este requisito.

Oculta secciones completasCopiar link al encabezado

Este ejemplo conserva la edición de campos de un borrador preparado, pero oculta la configuración del sobre y las modificaciones de archivos y destinatarios.

<EmbedUpdateEnvelope
  host="https://business.digito.do"
  presignToken={presignToken}
  envelopeId={envelopeId}
  language="es"
  features={{
    settings: null,
    envelopeItems: null,
    recipients: null,
  }}
/>

Callbacks y continuación del procesoCopiar link al encabezado

onEnvelopeCreated y onEnvelopeUpdated reciben:

En un recorrido completo, onEnvelopeCreated permite pasar del creador al editor: conserva envelopeId, confirma el recurso desde tu servidor y monta EmbedUpdateEnvelope con ese ID. Tras onEnvelopeUpdated, consulta de nuevo el sobre antes de actualizar el estado de tu expediente.

Ejemplo de creación y ediciónCopiar link al encabezado

El componente siguiente pasa del creador al editor después de comprobar el sobre. confirmarSobre debe consultar tu servidor y rechazar la operación si el sobre no pertenece al proceso autorizado. Este callback y la sesión del usuario los implementa tu aplicación.

import { useState } from 'react';
import { EmbedCreateEnvelope, EmbedUpdateEnvelope } from '@digitogroup/embed-react';

export function GestorDeSobres({
  presignToken,
  confirmarSobre,
}: {
  presignToken: string;
  confirmarSobre: (envelopeId: string) => Promise<void>;
}) {
  const [envelopeId, setEnvelopeId] = useState<string | null>(null);
  const [estado, setEstado] = useState<'crear' | 'editar' | 'guardado'>('crear');
  const [error, setError] = useState<string | null>(null);

  async function guardar(id: string, siguiente: 'editar' | 'guardado') {
    try {
      await confirmarSobre(id);
      setEnvelopeId(id);
      setEstado(siguiente);
      setError(null);
    } catch {
      setError('No se pudo confirmar el sobre. Consulta su estado antes de continuar.');
    }
  }

  if (estado === 'guardado') return <p>El servidor confirmó los cambios del sobre.</p>;

  return (
    <div>
      {error && <p role="alert">{error}</p>}
      <div style={{ height: '800px', width: '100%' }}>
        {estado === 'editar' && envelopeId ? (
          <EmbedUpdateEnvelope
            key={envelopeId}
            host="https://business.digito.do"
            presignToken={presignToken}
            envelopeId={envelopeId}
            language="es"
            onEnvelopeUpdated={(data) => { void guardar(data.envelopeId, 'guardado'); }}
          />
        ) : (
          <EmbedCreateEnvelope
            host="https://business.digito.do"
            presignToken={presignToken}
            type="DOCUMENT"
            language="es"
            externalId="expediente-12345"
            onEnvelopeCreated={(data) => { void guardar(data.envelopeId, 'editar'); }}
          />
        )}
      </div>
    </div>
  );
}

El ejemplo termina al guardar el borrador. Distribuirlo o autorizar una firma son acciones posteriores del proceso, con sus propias comprobaciones.

Si el editor se cierra, guarda el identificador del borrador para retomarlo sin crear otro sobre. Comprueba expiresAt antes de abrirlo de nuevo y emite otro token si hace falta. No reutilices el token de otro usuario ni uno vencido. Los callbacks no sustituyen la autorización ni la consulta del servidor.

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.

Referencia de tokens · Embed de firma · Paquetes de embed por framework.