Requisitos previos
- Una cuenta de Firma con una clave API
- Una cuenta de v0 con un proyecto activo (el plan gratuito funciona)
- Al menos una plantilla de Firma con campos de firma configurados
Firma usa la clave API sin procesar como el valor del header
Authorization, no la prefijes con Bearer. Esto es diferente de muchas otras APIs.Paso 1: Guarda tu clave API como variable de entorno
v0 gestiona las variables de entorno mediante el panel Vars en la barra lateral del chat. Los valores se sincronizan con el proyecto de Vercel conectado, así que el mismo secreto funciona tanto en previews como en producción.- Abre tu proyecto de v0 y haz clic en la pestaña Vars en la barra lateral
- Haz clic en Add Variable
- Configura la clave como
FIRMA_API_KEYy pega tu clave API de Firma como valor - Guarda
process.env.FIRMA_API_KEY en cualquier código del lado del servidor que genere v0.
Paso 2: Crea un route handler para enviar solicitudes de firma
Pídele a v0 que cree un route handler, o agrega el archivo directamente. v0 genera código de Next.js App Router por defecto, así que los route handlers viven enapp/api/<route-name>/route.ts.
Este ejemplo crea y envía una solicitud de firma a partir de una plantilla en una sola llamada usando el endpoint create-and-send:
El endpoint
create-and-send crea la solicitud de firma y la envía a los destinatarios de forma atómica. Si necesitas revisar o modificar la solicitud antes de enviarla, usa POST /signing-requests para crear un borrador y luego POST /signing-requests/{id}/send por separado.Paso 3: Llama al route handler desde tu UI
Desde un componente de cliente, haz un POST a tu nueva ruta cuando el usuario complete el formulario:/api/send-signing-request with the template ID, signer email, first name, and last name from the form.” v0 generará el formulario, el botón y la llamada fetch juntos.
Integración de webhooks
Para hacer seguimiento de cuándo se firman los documentos, agrega un route handler para webhooks y regístralo en el panel de Firma.- Publica tu app (ver más abajo) para que la ruta sea accesible públicamente
- En el panel de Firma, bajo Configuración → Webhooks, agrega un webhook que apunte a
https://<your-app-domain>/api/webhooks/firma - Selecciona los eventos que quieres recibir. Consulta la guía de webhooks para conocer todos los tipos de eventos y la verificación de firma
Publicar en Vercel
Los proyectos de v0 se conectan automáticamente a un proyecto de Vercel. Para llevar tu app a producción:- Haz clic en Publish en la esquina superior derecha de la interfaz de v0, o conecta un proyecto de Vercel existente desde Project settings
- Las variables de entorno configuradas en el panel Vars se sincronizan con Vercel automáticamente. Para asignar valores por entorno (Production, Preview, Development), edítalas en Project → Settings → Environment Variables en el panel de Vercel
- Una vez publicada, la URL de tu webhook será
https://<project-name>.vercel.app/api/webhooks/firma. Usa esa URL al registrar el webhook en Firma
Si necesitas una clave API de Firma distinta para preview y para producción, configura
FIRMA_API_KEY por entorno en el panel de Vercel. El panel Vars de v0 escribe en todos los entornos por defecto.Firma incrustada
Para apps donde los firmantes completan los documentos dentro de tu UI en lugar de saltar al correo electrónico, Firma ofrece una experiencia de firma incrustable. La respuesta decreate-and-send incluye un first_signer.id (el signing_request_user_id) y un first_signer.signing_link ya generado. Renderízalo en un iframe:
Extra: conexión MCP para desarrollo asistido por IA
Firma ofrece un servidor MCP de documentación al que el chat de v0 puede conectarse directamente. Una vez conectado, v0 busca en la documentación de Firma mientras genera código, así usa endpoints, nombres de campos y patrones correctos. Para configurarlo:- En v0, haz clic en Add MCP en el formulario de prompt o ve a Settings → MCP Connections
- Agrega un servidor MCP personalizado con la URL:
https://docs.firma.dev/mcp - Guarda
abc123 using the email in the form” generarán código que coincide con la API actual de Firma. Esto es una ayuda en tiempo de desarrollo y no afecta tu app desplegada.
Próximos pasos
- Autenticación de la API — claves API y alcance por espacio de trabajo
- Guía de webhooks — tipos de eventos, payloads y verificación de firma
- Firma incrustada — experiencia de firma dentro de la app
- Creación de espacios de trabajo — configuraciones multiempresa para apps SaaS
- Guía de configuración completa — recorrido de integración de Firma de extremo a extremo
- Referencia de la API — documentación completa de endpoints