La mayoría de los productos que necesitan una firma mandan a sus usuarios a otro sitio a conseguirla. Llega un correo, un enlace abre una página que no se parece en nada a su producto, el usuario firma allí y encuentra el camino de vuelta como puede, y su sistema se entera de que ha pasado algo solo cuando alguien lo comprueba. Funciona, y es justo donde se rompen todos los flujos. Desde hoy deja de ser la única opción: la API de GingerDocs y el SDK de incrustación ya están disponibles, con la documentación en app.gingerdocs.com/docs y los dos paquetes del SDK en npm.
Esta es la versión corta de lo que puede construir con ellos, en el orden en que lo construiría.
Tres pasos: crear la sesión, montar el marco, reaccionar a los eventos
El modelo es deliberadamente pequeño. Su servidor pide a nuestra API una sesión de incrustación: una URL de vida corta ligada a un documento y a un firmante, o a uno de sus usuarios y a un espacio de trabajo. Su página entrega esa URL al SDK, que enmarca la experiencia de firma en nuestro origen y fija el origen y el identificador de sesión en ambos extremos. Su código escucha entonces eventos tipados y actúa en consecuencia.
Su clave secreta nunca llega a un navegador. No es una directriz que tenga que seguir; el diseño la hace innecesaria, porque lo único que la página ve en algún momento es la URL de la sesión, que caduca por sí sola y puede revocarse desde su servidor en cualquier momento.
- Cree una sesión en su servidor con una clave secreta: un único POST que indica el documento y el origen de la página que lo va a enmarcar.
- Monte el marco con el SDK: cuatro líneas en su página, o un componente en React.
- Reaccione a los eventos: ready, viewed, signed, completed, declined y los eventos de documento de una sesión de espacio de trabajo. Para todo lo que se complete fuera del marco, la fuente de verdad es su endpoint de webhook o la API de eventos.
El código
En el servidor, una sola llamada crea la sesión. La respuesta trae la URL para la página y un identificador que usted pasa junto a ella para que el SDK acepte mensajes únicamente de esa sesión.
const res = await fetch('https://api.gingerdocs.com/api/v1/embed_sessions', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GINGERDOCS_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
kind: 'signing',
document_id: documentId,
host_origin: 'https://app.example.com',
}),
})
const { id, url } = await res.json()En la página, el SDK monta el marco en cualquier elemento y le entrega los eventos. Cuando una sesión caduca, cree una nueva y recargue el marco en el mismo sitio; el firmante nunca pierde el punto en el que estaba.
import { mount } from '@gingerdocs/embed'
const embed = mount('#signing', { url, sessionId: id })
embed.on('ready', () => hideLoader())
embed.on('completed', () => showConfirmation())
embed.on('session_expired', async () => {
const fresh = await refetchSession()
embed.reload(fresh.url, { sessionId: fresh.id })
})Si usa React, es un componente con un único manejador para todos los eventos, que puede pasarse en línea sin problema. React es opcional: el paquete principal no depende de ningún framework, así que las cuatro líneas anteriores funcionan tal cual en Vue, Angular, Svelte o una página HTML sin más.
import { GingerDocsEmbed } from '@gingerdocs/react'
<GingerDocsEmbed
url={session.url}
sessionId={session.id}
onEvent={event => event.type === 'completed' && showConfirmation()}
/>Constrúyalo gratis, en modo de prueba
El Developer Mode y las claves de prueba están disponibles en todos los planes, incluido el gratuito. Todo lo que aparece en este artículo funciona en el entorno de prueba: ningún correo de ningún tipo sale de nuestros servidores, el PDF resultante lleva una marca de agua que lo señala como no vinculante legalmente, y los documentos de prueba se eliminan a los 90 días. Un endpoint de prueba puede incluso simular la firma, de modo que su CI puede comprobar que un documento llega a COMPLETED sin que ningún humano haga clic en nada.
Cambie a una clave activa cuando esté listo. Las llamadas son idénticas.
Su nombre en el certificado
Todo documento completado termina con un certificado de finalización: el número de referencia, el código de verificación y la cronología y la dirección IP de cada firmante. Cuando es usted quien entrega el enlace de firma, o quien acredita la identidad de un firmante a través de una sesión incrustada, el certificado nombra a su entidad legal como parte verificadora. Eso es lo que acepta en los Integrator Terms al activar el Developer Mode, y es la versión honesta del registro: dice quién respondió por el firmante.
Cualquiera que tenga el PDF puede seguir contrastándolo con nuestros registros en la página de verificación, sin necesidad de cuenta.
Webhooks y un registro de eventos de 90 días
Cada cambio de estado emite un evento. Registre un endpoint de webhook y cada uno le llegará como un POST firmado, con reintentos y un registro de entregas que puede consultar en Configuración → Desarrollador. Si aun así se le escapa uno, porque su endpoint estuvo caído durante una hora, sigue ahí: todos los eventos permanecen legibles a través de la API durante 90 días.
El marco informa de lo que ocurre dentro de él; su webhook informa de lo que ocurre en cualquier parte. Construya sobre el segundo y use el primero para la persona que está delante de la pantalla.
Código abierto, dos paquetes
El SDK es lo bastante pequeño como para leerlo de una sentada, y esa es la idea. @gingerdocs/embed no depende de ningún framework, pesa menos de 1,5 KB comprimido con gzip y no tiene dependencias; @gingerdocs/react lo envuelve en un componente. Ambos tienen licencia MIT y viven en GitHub en gingerdocs/embed-sdk y gingerdocs/embed-react-sdk, donde los gestores de incidencias están abiertos.
Un SDK legible es lo que convierte la afirmación de seguridad de más arriba en algo que puede comprobar en lugar de algo que acepta por confianza.
Precios, y por dónde empezar
Construya gratis con claves de prueba. Pase a producción con el plan Developer: 100 $ al año por todo lo que incluye Pro, las mismas 1.000 subidas de documentos al mes y claves de API activas. Los detalles están en la página de precios.
Empiece por la guía de inicio rápido: de una cuenta recién creada a un documento firmado en cuatro llamadas, desde su terminal, en unos diez minutos. La página para desarrolladores tiene la visión general, y la referencia de la API está ahí para cuando necesite cada campo.