> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Mocha

> Añade firmas electrónicas legalmente vinculantes a cualquier app de Mocha usando funciones de backend generadas por IA y la API de Firma.

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](https://app.firma.dev) 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

<Note>
  Firma usa la clave API sin modificar como valor del encabezado `Authorization`; no la antepongas con `Bearer`. Esto difiere de muchas otras API.
</Note>

## Paso 1: Guarda tu clave API de Firma como secreto

1. Abre tu proyecto en Mocha
2. Ve a **Settings → Secrets**
3. 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](https://app.firma.dev), 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:

```text theme={null}
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.
```

Reemplaza `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.

<Note>
  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.
</Note>

## 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:

1. Pídele a Mocha que cree un endpoint de API en tu app que acepte solicitudes POST. Usa una indicación como esta:

```text theme={null}
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 }.
```

2. Después de publicar tu app, copia la URL del webhook: `https://your-app.mocha.app/api/webhook/firma`
3. En el panel de Firma, ve a **Configuración → Webhooks** y registra esta URL

<Warning>
  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](/es/guides/webhooks) para más detalles de implementación.
</Warning>

Consulta la [guía de webhooks](/es/guides/webhooks) para conocer todos los tipos de eventos y detalles de los payloads.

## 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:

```text theme={null}
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.
```

Consulta la [guía de firma incrustada](/es/guides/embeddable-signing) para instrucciones completas de configuración y mejores prácticas de seguridad.

## Extra: usa Custom Knowledge para mejores resultados de IA

La función Custom Knowledge de Mocha te permite darle a la IA contexto persistente sobre tu proyecto. Añadir aquí los detalles de la API de Firma ayuda a Mocha a generar código más preciso cuando le pides que construya funciones de firma.

1. Abre tu proyecto y ve a la pestaña **Custom Knowledge**
2. Añade lo siguiente:

```text theme={null}
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
```

Esto es opcional pero recomendado. Significa que cada vez que le pidas a Mocha que construya o modifique una función de firma, la IA ya sabrá cómo funciona Firma.

## Próximos pasos

* [Autenticación de la API](/es/guides/authentication) — claves API y alcance por espacio de trabajo
* [Guía de webhooks](/es/guides/webhooks) — tipos de eventos, payloads y verificación de firmas
* [Firma incrustada](/es/guides/embeddable-signing) — experiencia de firma dentro de la app
* [Creación de espacios de trabajo](/es/guides/creating-workspaces) — configuraciones multiempresa para apps SaaS
* [Guía de configuración completa](/es/guides/complete-setup-guide) — recorrido completo de integración con Firma
* [Referencia de la API](/api-reference) — documentación completa de los endpoints