Firma te permite añadir firmas electrónicas legalmente vinculantes a cualquier aplicación de Mocha. Guarda tu clave API de Firma como secreto, pídele a la IA de Mocha que llame a la API desde tu backend, y tus usuarios podrán enviar solicitudes de firma directamente desde tu app.
Esta guía cubre cómo integrar Firma usando las funciones de backend integradas de Mocha y el gestor de secretos. Como Mocha está impulsado por IA, la mayor parte de la integración se puede hacer indicándole a la IA las instrucciones correctas.
Requisitos previos
- Una cuenta de Firma con una clave API
- Una cuenta de Mocha (el plan gratuito incluye 1 app publicada; los planes de pago añaden más apps publicadas y dominios personalizados)
- Al menos una plantilla de Firma con campos de firma configurados
Firma usa la clave API sin modificar como valor del encabezado Authorization; no la antepongas con Bearer. Esto difiere de muchas otras API.
Paso 1: Guarda tu clave API de Firma como secreto
- Abre tu proyecto en Mocha
- Ve a Settings → Secrets
- Añade un nuevo secreto con el nombre
FIRMA_API_KEY y pega tu clave API de Firma como valor
Nunca pegues tu clave API directamente en el chat de Mocha. Usa siempre el panel de Secrets para que la clave se almacene de forma segura y nunca quede expuesta en el código del frontend.
Para obtener tu clave API, inicia sesión en el panel de Firma, ve a Settings → API Keys y copia tu clave.
Paso 2: Pídele a Mocha que construya la función de solicitud de firma
Mocha genera código de backend a partir de indicaciones en lenguaje natural. No necesitas escribir código tú mismo. En su lugar, pega la siguiente indicación en el chat de Mocha:
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.
Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
{
"name": "from the form (a descriptive name for the signing request)",
"template_id": "YOUR_TEMPLATE_ID",
"recipients": [
{
"first_name": "from the form",
"last_name": "from the form",
"email": "from the form",
"designation": "Signer",
"order": 1
}
]
}
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
YOUR_TEMPLATE_ID con el ID de una plantilla de tu panel de Firma. Puedes encontrarlo en Templates haciendo clic en una plantilla y copiando el ID de la URL.
La IA de Mocha generará la función de backend, creará el formulario de frontend y los conectará entre sí. Pruébalo en la vista previa antes de publicar.
El endpoint create-and-send crea la solicitud de firma y la envía a los destinatarios en una sola llamada. Si necesitas revisar o modificar la solicitud antes de enviarla, pídele a Mocha que use POST /signing-requests para crear primero un borrador, y luego POST /signing-requests/{id}/send por separado.
Paso 3: Sigue el estado de la firma con webhooks
Firma puede notificar a tu app cuando un documento se firma, se rechaza o expira. Para configurarlo:
- Pídele a Mocha que cree un endpoint de API en tu app que acepte solicitudes POST. Usa una indicación como esta:
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.
If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.
If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.
Always return a JSON response { "received": true }.
- Después de publicar tu app, copia la URL del webhook:
https://your-app.mocha.app/api/webhook/firma
- En el panel de Firma, ve a Configuración → Webhooks y registra esta URL
Para uso en producción, verifica siempre la firma del webhook usando tu secreto de firma de webhook de Firma. Consulta la guía de webhooks para más detalles de implementación. Firma incrustada
Para apps donde los firmantes completan documentos directamente en tu interfaz en lugar de por correo electrónico, Firma ofrece una experiencia de firma incrustable. La respuesta de create-and-send incluye un first_signer.id (el signing_request_user_id) y un first_signer.signing_link ya preparado. Pídele a Mocha que añada un iframe que cargue la URL de firma:
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:
<iframe
src="https://app.firma.dev/signing/{signing_request_user_id}"
style="width:100%;height:900px;border:0;"
allow="camera;microphone;clipboard-write"
title="Document Signing"
></iframe>
Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
- Abre tu proyecto y ve a la pestaña Custom Knowledge
- Añade lo siguiente:
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
Próximos pasos
