Plugin de Firma
Firma documentos PDF y Word con una firma visible y un sello digital
El plugin Signer coloca una firma visible en un documento y, por defecto, lo sella con una firma digital que un lector de PDF puede verificar. Firma archivos PDF y Word (.docx). La firma visible es siempre una imagen PNG: dibujada, escrita o cargada por el firmante.
| Superficie | Usarlo cuando |
|---|---|
DocumentSigner (C#) | Firma en el servidor, sin que intervenga el navegador |
Drop-in widget (doconutSigner.js) | Quieres una pantalla lista para cargar, firmar y descargar en tu página |
HTTP endpoints (?sign=open|run|download) | Construyes tu propia UI de firma contra un contrato de servidor documentado |
Cada firma se coloca una sola vez, en una página. El nombre del firmante, el motivo y la ubicación pueden acompañarla.
Instalar el paquete
Instala el plugin Signer estable más reciente:
dotnet add package Doconut.NET8.SignerPara fijar el plugin a la versión que describe esta documentación, pasa la versión por separado:
dotnet add package Doconut.NET8.Signer --version 26.10.0Mantén el paquete Signer en la misma versión que Doconut.NET8. El ID del paquete es Doconut.NET8.Signer; .<version> aparece solo en el nombre de archivo .nupkg descargado.
El archivo de licencia del plugin, Doconut.Viewer.Signer.lic, se coloca en la misma carpeta que Doconut.Viewer.lic; se lee junto con la licencia del visor.
Plataformas. El plugin se ejecuta dondequiera que Doconut.NET8 se ejecute: Windows y Linux basado en glibc en x64 (no Alpine ni otras distribuciones basadas en musl). En Linux, instala la biblioteca de configuración de fuentes antes de que se abra el primer documento:
apt-get update && apt-get install -y libfontconfig1En RHEL, Fedora y distribuciones similares, el paquete es fontconfig. Sin él, la apertura de un documento falla con The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.
Registrar el plugin
Como cualquier plugin Doconut, Signer se registra con AddPlugin<TPlugin>() dentro de AddDoconut():
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Eso es todo lo que necesita la fachada C#. El widget y sus endpoints HTTP son una opción separada, AddSignerWidget() (ver Widget integrado).
El plugin necesita una licencia que otorgue la capacidad Signer. Sin ella, AddDoconut() lanza una excepción al iniciar, antes de que la aplicación sirva una solicitud:
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.Lanza una excepción por falta de licencia, un archivo legado TRIAL, una licencia sin Signer, y una licencia de pago usada fuera de su ventana de versión. Se aceptan licencias temporales Demo/NFR. Consulte Configuración de Licencia para saber cómo se cargan las licencias.
Licenciamiento y marca de agua
| Estado de licencia | Inicio | Firma certificada | Firma visual |
|---|---|---|---|
Licencia de pago que otorga Signer, certificado configurado | Inicia | Sellado con tu certificado, limpio (watermarked: false) | Limpio |
Licencia de pago que otorga Signer, sin certificado | Inicia | Rechazado: No signing certificate configured. | Limpio |
| Licencia de pago, certificado expirado o aún no válido | Inicia (con el widget habilitado, se registra una advertencia) | Rechazado: The signing certificate expired on yyyy-MM-dd. | Limpio |
| Licencia temporal Demo/NFR, activa o expirada | Inicia | Sellado con el certificado de demostración incorporado, con marca de agua (watermarked: true) | Con marca de agua |
Sin licencia, un archivo legado TRIAL, una licencia sin Signer, o una licencia de pago fuera de su ventana de versión | AddDoconut() lanza una excepción | — | — |
La regla es la misma para la fachada C# y el widget: la salida lleva marca de agua cuando la licencia no es una licencia de visor de pago o es temporal. Con una licencia temporal el plugin siempre firma con su certificado de demostración incorporado, y cualquier certificado que configures no se utiliza.
El certificado de demostración produce un sello genuino, pero los lectores de PDF no lo confían. Se puede crear y probar una integración de extremo a extremo con una licencia de evaluación; para obtener una salida limpia y confiable necesitas tanto una licencia de pago como tu propio certificado de firma.
Uso desde C#
DocumentSigner está registrado por AddDoconut() y resuelto mediante inyección de dependencias. Su constructor es interno, así que nunca lo new. Resolverlo sin AddPlugin<SignerPlugin>() lanza No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
using Doconut;
using Doconut.Core.Models.Signing;
public sealed class ContractSigning
{
private readonly DocumentSigner _signer;
public ContractSigning(DocumentSigner signer) => _signer = signer;
public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
{
var request = new SignRequest(
new VisibleSignature(SignatureKind.Drawn, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
SignerName: "Ada Lovelace",
Reason: "I approve this document",
Location: "London, UK");
// Mode predeterminado a Certified (visible signature \u002B digital seal); WordOutput predeterminado a Pdf.
SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
using (result.Stream)
using (var output = new MemoryStream())
{
await result.Stream.CopyToAsync(output, ct);
return output.ToArray();
}
}
}SignAsync toma el flujo de origen, su extensión (".pdf" o ".docx"), la solicitud y el certificado para esta llamada. La fachada no lee SignerWidgetOptions.SigningCertificate; esa configuración es para el widget. Pase null bajo una licencia de demostración, o en modo Visual.
SignResult contiene el documento firmado como un flujo buscable, más su Extension (".pdf" o ".docx") para que pueda nombrar el archivo. Usted posee el flujo: dispóngalo cuando haya terminado.
Una firma Visual estampa solo la imagen y no necesita certificado:
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");
var request = new SignRequest(
new VisibleSignature(SignatureKind.Image, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
Mode: SignatureMode.Visual);
SignResult result = await signer.SignAsync(stream, ".pdf", request, ct: ct);Una fuente Word se firma a PDF a menos que solicite salida Word. Nombre el resultado de result.Extension:
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");
var request = new SignRequest(
new VisibleSignature(SignatureKind.Drawn, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
WordOutput: WordOutput.Docx);
SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension; // \u0022.docx\u0022SignAsync lanza una excepción en lugar de devolver cuando la llamada no puede tener éxito:
| Excepción | Mensaje | Cuándo |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Modo certificado, una licencia de pago, y no se pasó certificado |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Modo certificado con un certificado fuera de su ventana de validez |
ArgumentException | The sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page. | Bytes PNG vacíos, o una ubicación que no es válida |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | Cualquier otro tipo de origen |
Modos de firma, salida Word y certificados
Modos de firma
SignRequest.Mode elige si la firma está sellada.
| Modo | Qué produce | Certificado | Verificable |
|---|---|---|---|
SignatureMode.Certified (default) | La firma visible más un sello digital | Requerido bajo una licencia de pago | Sí |
SignatureMode.Visual | Solo la firma visible | Nunca necesario | No: es una imagen |
Utilice Certified cuando la firma debe ser comprobable: aprobaciones, contratos, cualquier cosa que un verificador necesite revisar para la identidad e integridad. Utilice Visual cuando solo necesita la apariencia de una firma, o no tiene certificado. Una licencia temporal marca ambas con una marca de agua.
Los sellos PDF son firmas PKCS#7 desacopladas (adbe.pkcs7.detached) con SHA-256, para claves RSA o ECDSA. Transportan los certificados del emisor encontrados en su PFX, de modo que un lector que confíe en su raíz pueda construir la cadena. Los sellos nativos de Word son firmas de paquetes OOXML y transportan solo el certificado del firmante.
Documentos Word
Para una fuente .docx, SignRequest.WordOutput elige la salida. Se ignora para fuentes PDF, que siempre generan un PDF.
| Salida | Qué ocurre | Soporte del verificador |
|---|---|---|
WordOutput.Pdf (predeterminado) | El documento se convierte a PDF, luego se firma y sella | Amplio: un PDF firmado se verifica en todas partes |
WordOutput.Docx | El documento permanece en Word: la imagen de la firma se inserta en él, más una firma de paquete OOXML | Limitado: no todos los visores muestran firmas de paquetes OOXML |
Mantenga PDF a menos que el destinatario necesite un archivo Word editable y acepte el soporte limitado del verificador.
Configuración del certificado
Para sellar con su propia identidad, proporcione al complemento un archivo PFX (PKCS#12) que incluya la clave privada. Para el widget, establezca SignerWidgetOptions.SigningCertificate; para la fachada C#, pase el certificado a SignAsync. Proporcione ya sea los bytes o una ruta, más la contraseña:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = "/secure/signing.pfx",
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});El certificado se mantiene solo en memoria. Nunca se registra, se devuelve a un cliente ni se persiste, y la contraseña nunca aparece en una línea de registro o en un mensaje de error.
Requisitos:
- Un paquete PFX / PKCS#12 con su clave privada. Un archivo solo de clave pública (
.cer,.crt) no puede firmar. Exporte la cadena del emisor con él, de modo que los sellos PDF puedan llevarla. - La contraseña correcta.
- Dentro de su ventana de validez. Un certificado expirado o aún no válido no detiene la aplicación: se registra como Advertencia al iniciar, y las firmas Certificadas se rechazan hasta que se reemplace. Las firmas Visuales no se ven afectadas.
- Emitido para firma de documentos: un uso de clave con firma digital o no repudio, y un uso extendido de clave, si está presente, que permita la firma de documentos, protección de correo electrónico o autenticación de cliente. Un certificado emitido para otra cosa, como un certificado de servidor TLS, aún firma, pero se registra como Advertencia y los lectores PDF marcan la firma.
- Los tokens de hardware, tarjetas inteligentes, HSM y el almacén de certificados de Windows no son compatibles. Exporte el certificado, con su clave privada y cadena, a un PFX.
Cree un PFX a partir de un certificado y su clave privada con OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# La contraseña de exportación que se le solicita es SigningCertificate.Password.Exporte uno desde el almacén de certificados de Windows: abra certmgr.msc y encuentre el certificado (su ícono muestra una llave cuando la clave privada está presente). Haga clic derecho, elija Todas las tareas → Exportar…, seleccione Sí, exportar la clave privada, elija Intercambio de información personal – PKCS #12 (.PFX), y establezca una contraseña.
Comprobaciones al iniciar
Cuando el widget está habilitado, el certificado en SignerWidgetOptions.SigningCertificate se verifica una vez, dentro de AddDoconut(), de modo que un PFX mal configurado falla al iniciar en lugar de en la primera firma. Tres problemas generan un InvalidOperationException:
| Mensaje | Solución |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Corrija PfxPath; asegúrese de que el archivo esté desplegado y sea legible por la cuenta de la aplicación |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Verifique la contraseña; asegúrese de que el archivo sea un .pfx real, no un .cer o .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Exporte nuevamente el PFX con la clave privada |
De lo contrario, el host escribe una línea en el registro al iniciar. Información cuando el certificado está listo:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.Una Advertencia cuando está expirado, aún no es válido, o no está emitido para firma de documentos:
Doconut Signer: the signing certificate '{subject}' expired on yyyy-MM-dd. Certified signatures will be refused until it is replaced.
Doconut Signer: the signing certificate '{subject}' is not valid before yyyy-MM-dd. Certified signatures will be refused until then.
Doconut Signer: the signing certificate '{subject}' is not issued for document signing (its key usage excludes it). PDF readers will flag these signatures.Y Información cuando no hay certificado configurado:
Doconut Signer: no signing certificate configured — output uses the built-in demo certificate and is watermarked. Set SignerWidgetOptions.SigningCertificate to sign with your own certificate.Esa última línea es la misma bajo cualquier licencia. Con una licencia paga el certificado de demostración nunca se usa: sin certificado, solo funcionan las firmas Visuales.
La fachada C# no se verifica al iniciar. El certificado que pasa a SignAsync se lee cuando firma, por lo que una ruta o contraseña incorrecta falla esa llamada.
Widget incrustable
Habilitar los endpoints
Los endpoints ?sign=open|run|download del widget están desactivados por defecto. Habilítelos junto al registro del plugin:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // por defecto
widget.MaxSignatureImageKb = 512; // por defecto
// widget.SigningCertificate: ver configuración del certificado; dejarlo null para la firma de demostración (con marca de agua)
});
});AddSignerWidget() sin argumentos habilita el widget con los valores predeterminados. No otorga la firma por sí mismo: necesita AddPlugin<SignerPlugin>(), o AddDoconut() lanza:
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.Sin AddSignerWidget(), cada solicitud ?sign= responde 404. El script sigue sirviéndose, por lo que el widget se carga y dibuja su zona de arrastre, luego informa Signing is not enabled on this server. en su primera solicitud.
Incrustarlo
UseDoconutResources() sirve el script en {ResourcesPath}/js/doconutSigner.js (por defecto /doconut-res/js/doconutSigner.js). Es un único archivo autónomo sin dependencias:
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
const handle = Doconut.signer('#host', { basePath: '/doconut' });
</script>Doconut.signer(selectorOrElement, options) acepta un selector CSS o un elemento, lanza una excepción si no se encuentra el montaje, y devuelve un manejador.
El firmante sube un archivo PDF o .docx, crea una firma (Dibujar en un lienzo, Escribir un nombre con una fuente de firma, o Imagen desde un PNG, JPG o GIF), la arrastra y redimensiona sobre la página, y firma y descarga el resultado. El widget siempre envía la firma como PNG; una imagen subida se convierte en el navegador a PNG que se ajusta a 520×160.
Opciones
| Opción | Tipo | Predeterminado | Notas |
|---|---|---|---|
basePath | string | '/doconut' | Dónde se sirven los endpoints ?sign= y las imágenes de vista previa |
resPath | string | '/doconut-res' | Reservado; el widget incluye su propio CSS |
maxUploadMb | number | 25 | Solo verificación del lado del cliente, por lo que un archivo demasiado grande falla rápidamente. El límite del servidor es MaxUploadMb en AddSignerWidget |
maxSignatureKb | number | 512 | Límite del lado del cliente para el modo Imagen. Manténgalo igual al MaxSignatureImageKb del servidor |
previewWidth | number | 560 | Ancho en píxeles de la vista previa de la página |
licenseUrl | string | null | null | Convierte el aviso de marca de agua de demostración en un enlace a esta URL |
signatureMode | string | 'certified' | Tipo de firma inicial: 'certified' o 'visual'. Cualquier otro valor se convierte en 'certified' |
showSignatureModeToggle | boolean | true | Muestra la opción Firma digital / Solo visual. Con false, el widget firma con signatureMode |
wordOutput | string | 'pdf' | Salida inicial para fuentes .docx: 'pdf' o 'docx'. Cualquier otro valor se convierte en 'pdf' |
showOutputFormatToggle | boolean | true | Muestra la opción PDF / Word, solo para fuentes .docx. Con false, el widget usa wordOutput |
labels | object | {} | Sobrescribe cualquier subconjunto de las cadenas en inglés |
Ocultar un interruptor no desactiva la función; fija el valor. Dos configuraciones comunes:
// Ambos interruptores mostrados, firma digital por defecto: un firmante de autoservicio completo.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Solo visual, sin interruptor: un sello simple sin firma digital ofrecida.
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Retrollamadas
| Retrollamada | Se dispara cuando | Carga útil |
|---|---|---|
onReady | Una vez, al montar (no de nuevo en reset()) | — |
onSourceLoaded | El archivo se abre y se muestra su vista previa | { file: { token, name, pages, ext } } |
onSigned | La firma tiene éxito | { downloadToken, downloadName, watermarked } |
onDownload | Al hacer clic en Descargar cada vez | { downloadName, downloadToken } |
onError | Un paso de abrir, firmar o descargar falla, o un archivo en modo Imagen es demasiado grande | { message } |
Una retrollamada que lanza una excepción es capturada y registrada; nunca interrumpe el flujo del widget.
Manejo imperativo
| Método | Comportamiento |
|---|---|
reset() | Regresa a la pantalla de caída y borra el flujo actual. No dispara onReady de nuevo. No hace nada después de destroy() |
loadFile(file) | Inicia el flujo con un File. No hace nada a menos que el widget esté en su pantalla de caída; llama a reset() primero si es necesario |
destroy() | Elimina los listeners, vacía el montaje y congela la instancia |
const signerWidget = Doconut.signer('#host', {
basePath: '/doconut',
onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());Etiquetas
Cada cadena tiene un valor predeterminado en inglés; labels sobrescribe cualquier subconjunto y el resto permanece en inglés. Los fragmentos que cambian en tiempo de ejecución usan {placeholders}, como uploading: 'Uploading {name}…' y pages: '{n} pages'.
| Clave | Valor predeterminado en inglés |
|---|---|
dropPrompt | Drag & drop a PDF or Word file here |
dropHint | PDF or Word (.docx) |
chooseFile | Choose file |
signatureHeading | Your signature |
modeDraw / modeType / modeImage | Draw / Type / Image |
metaSummary | Signature details (optional) |
metaSignerName / metaReason / metaLocation | Signer name / Reason / Location |
signatureType | Signature type |
modeCertified / modeVisual | Digital signature / Visual only |
modeVisualNote | No certificate — a visible mark only, not cryptographically verifiable. |
outputFormat | Output format |
outputPdf / outputWord | PDF / Word (.docx) |
signAction | Sign document |
download | Download |
demoNotice | Demo — signed with the Doconut demo certificate; output is watermarked. |
signingNotEnabled | Signing is not enabled on this server. |
page / pages | 1 page / {n} pages |
Otras claves cubren el paso de colocación, la pantalla de error, el formulario enlazado del aviso de demostración (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) y los anuncios aria-live.
Cuando open o run responden 404 sin error JSON, el widget muestra signingNotEnabled. Un error JSON del servidor siempre prevalece, por lo que mensajes como una carga vencida permanecen visibles.
Tematización
El widget agrega la clase dsw a su elemento de montaje y lee sus colores, radio y fuentes de las propiedades personalizadas de CSS, de modo que puedes tematizarlo sin tocar sus internos:
#host.dsw {
--dsw-accent: #b0522b; /* enlaces, foco, modo activo */
--dsw-bg: #fffaf3;
--dsw-fg: #3b2a1a;
--dsw-muted: #8a7a68;
--dsw-border: #e0cbb0;
--dsw-radius: 14px;
--dsw-font: Georgia, "Times New Roman", serif;
--dsw-signature-font: "Segoe Script", "Brush Script MT", cursive; /* el modo Type */
}Valores predeterminados: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, una fuente de UI del sistema y una fuente cursiva para firmas.
Construye tu propio frontend
El widget es un cliente para este contrato HTTP. Las tres rutas se encuentran bajo la ruta donde UseDoconut() está montado (normalmente /doconut), y responden 404 hasta que se llama a AddSignerWidget(). Los errores llevan un cuerpo JSON, { "error": "..." }, excepto donde la tabla indica "solo estado". Un valor desconocido de ?sign= responde 400.
| Ruta | Propósito | Respuesta exitosa |
|---|---|---|
POST ?sign=open (multipart, one file) | Cargar un PDF o .docx y abrirlo para vista previa | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON body) | Firmar el archivo cargado | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Transmitir el archivo firmado | 200 — el archivo, Content-Disposition: attachment, Cache-Control: no-store |
ext en la respuesta open incluye el punto inicial (".docx"). La vista previa de la página usa la ruta estándar de imagen del visor, {basePath}?token={token}&page={n}&thumb=1&width={px}; la página mostrada se convierte en placement.page.
El cuerpo run:
{
"token": "GUID-from-open",
"signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
"placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
"meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
"wordOutput": "pdf",
"mode": "certified"
}| Campo | Notas |
|---|---|
token | El token de open |
signature.kind | Drawn, Typed o Image, sin distinción de mayúsculas; cualquier otro valor se convierte en Drawn. Solo una pista: la carga siempre es un PNG |
signature.payload | Un PNG base64 puro, sin prefijo data:. Debe ser un PNG real y no mayor que MaxSignatureImageKb una vez decodificado |
placement.page | Basado en 1 |
placement.x / y / w / h | 0..1 normalizado desde la esquina superior izquierda, con x + w ≤ 1 y y + h ≤ 1 |
meta.signerName / reason / location | Opcional. Cada uno se recorta, un valor en blanco se descarta, y cada uno se corta a 256 caracteres |
wordOutput | pdf (por defecto) o docx; ignorado para fuentes PDF. Cualquier otro valor se convierte en pdf |
mode | certified (por defecto) o visual. Cualquier otro valor se convierte en certified |
downloadName sigue la salida: <source>-signed.pdf o <source>-signed.docx, y download envía el Content-Type correspondiente.
El origen cargado y el resultado firmado se conservan cada uno durante 30 minutos. Después de eso, run y download responden 404 y el archivo debe abrirse de nuevo. Todos los tokens son GUIDs.
| Ruta | Estado | Cuándo | Cuerpo |
|---|---|---|---|
| cualquiera | 404 | El widget no está habilitado | solo estado |
| cualquiera | 405 | Verbo incorrecto (open y run necesitan POST, download necesita GET) | solo estado |
open | 400 | No es una carga multipart | Expected a multipart file upload. |
open | 400 | No hay archivo, o está vacío | No file uploaded. |
open | 400 | Cualquier cosa distinta de .pdf o .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | La carga supera MaxUploadMb | File is too large. |
run | 400 | El cuerpo no es JSON válido, o está vacío | Malformed request. / Empty request. |
run | 400 | Falta el token o no es un GUID | Invalid token. |
run | 404 | La carga expiró o nunca se abrió | Upload expired — please re-open the file. |
run | 400 | Sin firma, o sin colocación | No signature supplied. / No placement supplied. |
run | 400 | La carga no es base64, está vacía, es demasiado grande, o no es un PNG | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | La colocación está fuera de la página | The signature or its placement is invalid. |
run | 400 | Modo certificado, una licencia paga y sin certificado | No signing certificate configured. |
run | 400 | Modo certificado con un certificado fuera de su ventana de validez | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Procesamiento falló | Un mensaje sanitizado |
download | 400 | Falta el token o no es un GUID | solo estado |
download | 404 | Token desconocido o expirado | solo estado |
Un recorrido completo con fetch:
// file: el File a firmar; pngBase64: la firma como un PNG base64 puro, sin prefijo data:
// por ejemplo canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 1. open: subir el archivo
const form = new FormData();
form.append('file', file, file.name);
const opened = await (await fetch(base + '?sign=open', { method: 'POST', body: form })).json();
// 2. run: firmarlo
const signed = await (await fetch(base + '?sign=run', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
token: opened.token,
signature: { kind: 'Drawn', payload: pngBase64 },
placement: { page: 1, x: 0.58, y: 0.80, w: 0.32, h: 0.12 },
meta: { signerName: 'Ada Lovelace', reason: 'I approve', location: 'London, UK' },
wordOutput: 'pdf',
mode: 'certified'
})
})).json();
// 3. download: obtener el archivo firmado
const blob = await (await fetch(base + '?sign=download&token=' + encodeURIComponent(signed.downloadToken))).blob();
const link = document.createElement('a');
link.href = URL.createObjectURL(blob);
link.download = signed.downloadName;
link.click();
URL.revokeObjectURL(link.href);
}Los puntos finales son same-origin: esta versión no tiene soporte CORS. Sirve tu UI y el script del widget desde el mismo origen que Doconut, o haz reverse‑proxy de ambos caminos /doconut (la ruta del middleware y la ruta de los recursos) bajo el origen de tu UI.
En producción
-
Instala el plugin junto al paquete central, en la misma versión:
dotnet add package Doconut.NET8.Signer. -
Añade el archivo de licencia. Coloca
Doconut.Viewer.Signer.licen la misma carpeta queDoconut.Viewer.lic. -
Obtén tu certificado como un PFX con su clave privada y cadena de emisores, de una autoridad certificadora o de la PKI propia de tu organización. Para probar primero, usa una licencia de demostración (el certificado de demo incorporado, con marca de agua) o un PFX autofirmado.
-
Lee el certificado desde la configuración, de modo que cambiarlo nunca requiera una modificación de código:
json"DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }csharpvar signerSettings = builder.Configuration.GetSection("DoconutSigner"); builder.Services.AddDoconut(options => { options.LicensePath = "Doconut.Viewer.lic"; options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]), Password = signerSettings["Password"] ?? "", }); });Mantén el
.pfxfuera dewwwroot, y mantén la contraseña fuera deappsettings.json: secretos de usuario en desarrollo (dotnet user-secrets set "DoconutSigner:Password" "<password>"), una variable de entorno (DoconutSigner__Password) o una bóveda en producción. -
Revisa el registro de inicio. Debería mostrar
using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Una advertencia, en cambio, significa que el certificado está expirado, aún no es válido, o no está emitido para la firma de documentos.
Confía en los lectores PDF. Un lector muestra la firma como válida cuando confía en la raíz del certificado. Con la PKI de tu organización, eso se cumple en cada máquina que confía en tu raíz, que suele ser cada máquina dentro de la organización. Los certificados que Adobe confía en cualquier máquina (la Adobe Approved Trust List) son, según sabemos, emitidos con la clave privada en un token de hardware o HSM, lo cual este plugin no puede usar: solo firma desde un PFX. Confirma con tu proveedor de certificados antes de depender de ese tipo de confianza.
Granjas web
El widget mantiene cada carga y su resultado en memoria en el nodo que sirvió open. Detrás de un balanceador de carga sin sesiones persistentes, una solicitud posterior de run, download o de vista previa puede llegar a otro nodo y no encontrar la carga. Registra el almacén de widget compartido y cifrado una sola vez, después de AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // una carpeta que cada nodo puede leer y escribir
store.FarmKey = farmKey; // al menos 32 bytes, idéntico en cada nodo
// store.Ttl = TimeSpan.FromMinutes(30); // cuánto tiempo se mantiene una carga (el predeterminado)
});- Un solo servidor no necesita nada: sin esta llamada se utiliza el almacén en memoria.
- Las cargas y resultados están cifrados en reposo en el recurso compartido (AES-256, encrypt-then-MAC), y cada archivo está vinculado a su token, de modo que un token nunca puede leer el archivo de otro.
FarmKeydebe tener al menos 32 bytes y ser idéntico en cada nodo. Cárgalo desde un almacén de secretos; nunca lo codifiques directamente. El registro lanza unArgumentExceptioncuandoRootPathfalta oFarmKeyes más corto que 32 bytes.- Apunta
RootPatha la misma ubicación compartida que usa el visor distribuido, y proporciona a cada nodo el mismo certificado de firma.
Referencia de API
La fachada y las opciones del widget están en el espacio de nombres Doconut; los tipos de solicitud y resultado están en Doconut.Core.Models.Signing. SignerPlugin está en Doconut.Plugins.Signer.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Resuelto mediante inyección de dependencias; el constructor es interno. sourceExtension es ".pdf" o ".docx". Con una licencia paga cert se utiliza y la salida es limpia; con una licencia temporal se usa el certificado de demostración incorporado, cert se ignora, y la salida lleva marca de agua.
SignRequest
public sealed record SignRequest(
VisibleSignature Signature,
SignaturePlacement Placement,
string? SignerName = null,
string? Reason = null,
string? Location = null,
WordOutput WordOutput = WordOutput.Pdf,
SignatureMode Mode = SignatureMode.Certified)
{
public bool IsValid { get; } // Signature.IsValid && Placement.IsValid
}Una firma visible colocada una vez, más metadatos opcionales del firmante.
VisibleSignature y SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes no está vacío
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes es un PNG para cada tipo. Una firma dibujada o escrita es transparente; una imagen cargada conserva la transparencia que tenía, por lo que un JPG opaco permanece opaco. Kind es solo una pista.
SignaturePlacement
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
public bool IsValid { get; } // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}Page es basado en 1; X, Y, W y H son 0..1 normalizados desde la esquina superior izquierda.
SignatureMode y WordOutput
public enum SignatureMode { Certified, Visual } // Certified es el predeterminado
public enum WordOutput { Pdf, Docx } // Pdf es el predeterminado; ignorado para fuentes PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);El documento firmado como un flujo buscable, y su extensión con el punto (".pdf" o ".docx").
SigningCertificate
public sealed class SigningCertificate
{
public byte[]? PfxBytes { get; init; }
public string? PfxPath { get; init; }
public string Password { get; init; } = "";
public bool HasMaterial { get; } // PfxBytes no está vacío, o PfxPath no está en blanco
}Establezca PfxBytes o PfxPath, más Password.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}Establezca a través de DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), que devuelve el DoconutOptions para que las llamadas puedan encadenarse. Un SigningCertificate nulo significa el certificado de demostración bajo una licencia temporal, y firmas Visuales solo bajo una licencia paga.
Solución de problemas
| Síntoma | Causa | Solución |
|---|---|---|
AddDoconut() lanza The Signer plugin is registered via AddPlugin but no active license grants Signer. | Sin licencia, un archivo TRIAL, una licencia sin Signer, o una licencia paga fuera de su ventana de versión | Instale una licencia que conceda Signer, o elimine AddPlugin<SignerPlugin>() |
AddDoconut() lanza AddSignerWidget() was called but the Signer plugin is not registered. | El widget está habilitado sin su complemento | Agregue options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() lanza Doconut Signer: the certificate file was not found at '{path}'. | PfxPath apunta a un archivo que falta | Corrija la ruta; despliegue el archivo donde la cuenta de la aplicación pueda leerlo |
AddDoconut() lanza Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Contraseña incorrecta, o no es un archivo PKCS#12 | Verifique la contraseña; use un .pfx real |
AddDoconut() lanza Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | El PFX se exportó sin su clave privada | Expórtelo nuevamente con la clave privada |
Resolviendo DocumentSigner lanza No IDocumentSigner is registered. | SignerPlugin no está registrado | Agregue AddPlugin<SignerPlugin>() dentro de AddDoconut() |
| La salida lleva marca de agua | La licencia es temporal (Demo/NFR) | Use una licencia paga que conceda Signer |
run responde 400 No signing certificate configured. | Una licencia paga, modo Certificado, y sin certificado | Configure SigningCertificate, o firme en modo Visual |
run responde 400 The signing certificate expired on yyyy-MM-dd. | El certificado está desactualizado | Reemplacelo; las firmas Visuales siguen funcionando mientras tanto |
| El registro indica que la salida "usa el certificado de demostración incorporado", pero una licencia paga rechaza firmas Certificadas | Esa línea se escribe siempre que no se configura un certificado, sea cual sea la licencia | Configure SigningCertificate |
El widget se carga pero dice Signing is not enabled on this server. | AddSignerWidget() no fue llamado, o basePath no coincide donde UseDoconut() está montado | Llame a AddSignerWidget(); corrija basePath |
run responde 400 The signature image must be a PNG., Signature image is not valid base64. o Signature image is too large. | Una UI personalizada envió una URL data:, un JPG, o más de MaxSignatureImageKb | Envíe un PNG base64 puro dentro del límite |
open responde 413 File is too large. | La carga supera MaxUploadMb | Eleve MaxUploadMb en AddSignerWidget; el maxUploadMb del widget es solo una verificación del lado del cliente |
run o download responde 404 Upload expired — please re-open the file. | El intervalo de 30 minutos expiró, o un nodo de la granja web no tiene la carga | Abra el archivo de nuevo; en una granja, registre AddDoconutDistributedWidgets |
Un .docx firmado no muestra firma en algunos visores | La salida de Word lleva una firma de paquete OOXML, que muchos visores no muestran | Firme a PDF, el predeterminado |
| Los lectores de PDF indican que la identidad del firmante es desconocida | El lector no confía en la raíz del certificado (el certificado de demostración nunca es confiable) | Use un certificado de una raíz que sus lectores confíen |
| El widget falla cuando la UI está en otro origen | Los endpoints no tienen soporte CORS | Sirva la UI desde el mismo origen, o haga reverse-proxy de las rutas Doconut |
| El tema no se aplica | El selector apunta a un elemento dentro del montaje | Apunte al propio montaje: #host.dsw o #host |
¿Fue útil esta página?