Desarrolladores y API

Se aplica a: anota, todos los planes Roles requeridos: Administrador o superior para crear y revocar claves de API y para gestionar Integraciones Referencias regulatorias: ninguna

Descripción general

Esta página es para quien quiere conectar anota con otras herramientas o crear formularios sin el editor visual. anota tiene una API REST para tus propios scripts y sistemas, y un conector MCP que permite que un asistente de IA como Claude o ChatGPT trabaje con tus formularios (consulta Conectar Claude y ChatGPT (MCP)). Los dos usan las mismas claves de API y pueden crear, editar, clonar, publicar y eliminar formularios (con su lógica condicional), leer y gestionar respuestas, y agregar webhooks que envían cada respuesta nueva a tu propio sistema.

Los ejemplos usan el espacio de trabajo de Café Aurora. Mariana, la dueña, crea una clave para un pequeño script que sincroniza los pedidos de catering, lista sus formularios con ella, agrega un webhook al formulario Solicitud de pedido de catering y revoca la clave cuando termina la prueba.

Conceptos clave

Clave de API: un secreto que permite que un programa actúe sobre tu espacio de trabajo. Empieza con anota_sk_ seguido de 40 caracteres. anota muestra la clave completa una sola vez, cuando la creas.
Token Bearer: la forma de enviar la clave en cada solicitud, en el encabezado Authorization: Bearer anota_sk_….
Endpoint: una dirección de la API, como GET /api/v1/forms (listar tus formularios). Todos los endpoints empiezan con https://anota.cloud/api/v1.
Webhook: una dirección web tuya a la que anota llama con las respuestas cada vez que un formulario recibe un envío. Los webhooks se gestionan con la API o el conector MCP; no hay una pantalla para ellos en la aplicación.
Secreto de firma: un valor que empieza con whsec_ y que anota te da al agregar un webhook. Tu sistema lo usa para comprobar que una llamada realmente viene de anota.
Conexión (página Integraciones): un vínculo entre tu espacio de trabajo y un CRM, para que los formularios creen registros ahí. Es distinta de los webhooks.

Tarea 1 — Crear una clave de API

Requisitos previos

El rol de Administrador o Propietario en el espacio de trabajo (consulta Roles y permisos). Con un rol inferior, el enlace API no aparece y la página muestra un mensaje de acceso denegado.

Paso a paso

Haz clic en API en la barra superior. Se abre la página Claves de API: "Conecta anota con Claude y otras integraciones. Cada clave da acceso a los formularios y respuestas de tu espacio de trabajo."

La página lista tus claves debajo de Crear una clave nueva.
En Crear una clave nueva, escribe un nombre que diga para qué es la clave, aquí "Sincronización de pedidos de catering". El nombre es solo para ti, de hasta 200 caracteres.

Usa una clave por herramienta, así puedes revocar una sin detener las demás.
Haz clic en Crear clave (o presiona Enter). El botón está desactivado hasta que escribes un nombre.

El botón dice Creando… mientras anota genera la clave.
El panel Tu nueva clave muestra la clave completa. Haz clic en Copiar (cambia a ¡Copiada!) y pega la clave ahora en tu gestor de contraseñas o en la configuración de tu herramienta: "Guárdala en un lugar seguro ahora: por seguridad no volveremos a mostrarla."

En esta captura la clave está oculta. En tu pantalla aparece completa, esta única vez.
La clave aparece en la tabla con su Nombre, la fecha en Creada y Último uso en Nunca. Las fechas y horas se muestran en la zona horaria de tu navegador.

La columna Clave siempre muestra el mismo anota_sk_…, nunca una parte de la clave real. Distingue tus claves por el nombre.

Resultado

La clave funciona de inmediato, para la API REST y para el conector MCP. Cuando sales de la página o la recargas, la clave completa desaparece para siempre: anota guarda solo una huella de ella. Si la pierdes, crea una clave nueva y revoca la anterior.

Tarea 2 — Hacer tu primera solicitud

Requisitos previos

La clave de la tarea 1 y una terminal con curl (incluido en macOS, Linux y Windows 10 o posterior).

Paso a paso

Lista tus formularios con GET /api/v1/forms. Reemplaza anota_sk_… por tu clave:
```
curl https://anota.cloud/api/v1/forms \
  --header "Authorization: Bearer anota_sk_…"
```
anota responde 200 OK con tus formularios en JSON, del actualizado más recientemente al más antiguo (aquí recortado al primer formulario):
```
{
  "count": 5,
  "forms": [
    {
      "id": "01a0dfe1-616d-7d31-86af-65ed9100c9d9",
      "title": "Inscripción al taller de barismo",
      "slug": "barista-workshop-registration",
      "status": "Published",
      "submissionCount": 5,
      "publicUrl": "https://anota.cloud/f/tecolotl/barista-workshop-registration",
      "updatedAt": "2026-09-27T17:55:03.4992506"
    }
  ]
}
```
El id es lo que necesitan los demás endpoints, por ejemplo GET /api/v1/forms/{formId} para el formulario completo o GET /api/v1/forms/{formId}/submissions para sus respuestas. La lista incluye borradores y formularios publicados, no los archivados ni los que están en la papelera. Los nombres de los campos y valores como "Published" están en inglés, sea cual sea el idioma de tu cuenta.

Sin el encabezado, o con una clave revocada, anota responde 401 Unauthorized con el cuerpo vacío.
De vuelta en la página Claves de API, Último uso muestra ahora cuándo se usó la clave.

Una forma rápida de ver si una herramienta todavía usa una clave antes de revocarla.

Resultado

Tu programa ya se comunica con tu espacio de trabajo. Último uso se actualiza como máximo cada cinco minutos, así que puede ir unos minutos atrás de la última llamada. La lista completa de endpoints y sus campos está en la referencia de la API (tarea 5).

Tarea 3 — Enviar las respuestas nuevas a tu sistema con un webhook

Un webhook hace que anota llame a tu sistema cada vez que un formulario recibe una respuesta, así no tienes que pedirle a la API las respuestas nuevas. Los webhooks se agregan con la API (o pidiéndoselo a Claude, con add_webhook); la página Integraciones no los gestiona.

Requisitos previos

Una clave de API (tarea 1) y el id del formulario (tarea 2).
Una dirección en tu servidor que acepte solicitudes POST por HTTPS y sea accesible desde internet. anota rechaza las direcciones http:// y las que apuntan a una red privada o interna (como localhost o 192.168.…), tanto al agregar el webhook como en cada envío.

Paso a paso

Agrega el webhook al formulario con POST /api/v1/forms/{formId}/webhooks:

curl https://anota.cloud/api/v1/forms/01a0df96-83fe-747c-b14e-03b183c3f962/webhooks \
  --request POST \
  --header "Authorization: Bearer anota_sk_…" \
  --header "Content-Type: application/json" \
  --data '{ "url": "https://example.com/hooks/anota" }'

anota responde con el id del webhook y su secret de firma (aquí oculto):

{
  "id": "01a0e40b-544b-71bb-a8b9-c847a4d695ef",
  "formId": "01a0df96-83fe-747c-b14e-03b183c3f962",
  "url": "https://example.com/hooks/anota",
  "secret": "whsec_…",
  "note": "Webhook active. Each new submission is POSTed to the URL with headers X-Anota-Event: submission.created and X-Anota-Signature: sha256=<HMAC-SHA256 of the raw body, keyed with this secret>. This is the only time the full secret is shown — store it now; list_webhooks returns only a masked hint."
}

Guarda el secret en tu sistema ahora. Esta es la única respuesta que lo contiene. Las notas (note) de la API están siempre en inglés.

Revisa los webhooks del formulario con GET /api/v1/forms/{formId}/webhooks. Cada uno muestra solo una pista de su secreto, whsec_… más los últimos cuatro caracteres, para que sepas qué secreto tiene tu sistema:

{
  "formId": "01a0df96-83fe-747c-b14e-03b183c3f962",
  "count": 1,
  "webhooks": [
    {
      "id": "01a0e40b-544b-71bb-a8b9-c847a4d695ef",
      "url": "https://example.com/hooks/anota",
      "events": "submission.created",
      "enabled": true,
      "secretHint": "whsec_…da56",
      "secretNote": "Masked. The full signing secret is shown only once, in the add_webhook response. If it was lost, delete this webhook and add it again to get a new secret."
    }
  ]
}

Para detener los envíos, elimina el webhook con DELETE /api/v1/forms/{formId}/webhooks/{webhookId}:

curl https://anota.cloud/api/v1/forms/01a0df96-83fe-747c-b14e-03b183c3f962/webhooks/01a0e40b-544b-71bb-a8b9-c847a4d695ef \
  --request DELETE \
  --header "Authorization: Bearer anota_sk_…"

{ "id": "01a0e40b-544b-71bb-a8b9-c847a4d695ef", "note": "Webhook deleted. Deliveries to its URL have stopped." }

Resultado

Mientras el webhook existe, cada respuesta nueva del formulario se envía a tu dirección como se describe en Qué envía un webhook. Un formulario puede tener hasta 10 webhooks. Si pierdes un secreto, elimina el webhook y vuelve a agregarlo para obtener uno nuevo.

Si la dirección se rechaza, anota responde 400 Bad Request con el motivo en detail, por ejemplo "Error: 'url' must be an absolute HTTPS URL, e.g. https://example.com/hooks/anota." o "Error: this URL could not be resolved or points to a private/internal network address, which webhooks cannot target."

Tarea 4 — Revocar una clave

Revoca una clave cuando una herramienta ya no la necesita, cuando se va alguien que la conocía o si pudo haberse filtrado.

Paso a paso

En la página Claves de API, haz clic en Revocar en la fila de la clave.

Revisa antes Último uso: una fecha reciente significa que una herramienta todavía depende de la clave.
anota pregunta en la misma fila: "¿Revocar? Las integraciones que la usan dejarán de funcionar." Haz clic en Sí, revocar, o en Cancelar para conservar la clave.

Después de Sí, revocar no hay vuelta atrás.
La clave desaparece de la tabla. Si no queda ninguna, la página muestra Aún no tienes claves de API.

El espacio de trabajo de Café Aurora después de revocar su única clave.

Resultado

La clave se elimina al instante y para siempre. Cualquier herramienta que todavía la use recibe 401 Unauthorized desde la siguiente solicitud. No existe "regenerar": para reemplazar una clave, crea primero una nueva, actualiza tu herramienta y después revoca la anterior. Si otra persona ya revocó la clave, anota muestra "No encontramos esa clave."

Tarea 5 — Encontrar la referencia completa de la API

Paso a paso

En el sitio web de anota, baja hasta el pie de página y haz clic en API, en la columna Producto. También puedes ir directo a https://anota.cloud/developers. La aplicación en sí no tiene un enlace a ella.

La misma columna enlaza la lista de herramientas MCP y los SDK oficiales en GitHub.
Se abre la referencia anota API, con una introducción, la lista de SDK oficiales y todos los endpoints en la barra lateral. La referencia está en inglés. Haz clic en Download OpenAPI Document para descargar el archivo de especificación, por ejemplo para generar un cliente o importarlo en Postman.

Para probar solicitudes desde la página, pega tu clave en Bearer Token.
Haz clic en un endpoint de la barra lateral, aquí Add a webhook, para ver su descripción, parámetros y cuerpo, y una solicitud lista para usar en el lenguaje que elijas (Shell, Ruby, Node.js, PHP, Python o More). Test Request la envía con tu clave.

Test Request llama a tu espacio de trabajo real: crea, cambia o elimina de verdad lo que pidas.

Resultado

Tienes la referencia técnica completa y siempre al día. La tabla de Endpoints de la API REST, más abajo, es un resumen de ella.

Tarea 6 — Abrir la página Integraciones

La página Integraciones conecta tu espacio de trabajo con un CRM para que los formularios creen registros ahí automáticamente. Es solo para conexiones con un CRM; los webhooks se gestionan con la API (tarea 3).

Paso a paso

Haz clic en Integraciones en la barra superior. La página dice "Conecta tu espacio de trabajo a otros sistemas (CRM, tickets). Cada formulario elige a dónde enviar sus respuestas." Mientras no haya conexiones, muestra Aún no hay conexiones.

Solo los Administradores y el Propietario pueden abrir esta página.
Haz clic en + Conexión. Elige el Sistema (anota ofrece P4 CRM), ponle un Nombre a la conexión e ingresa la URL base y la API key del CRM. Haz clic en Guardar, o en Cancelar para cerrar sin guardar.

Guardar está desactivado hasta que completas el nombre, la URL base y la API key.

Resultado

Una vez guardada, la conexión aparece en la lista con su Nombre, Sistema, URL y Estado, y los botones Probar, Editar y Eliminar. Al editarla, deja la API key en blanco para conservar la que está guardada. Después, cada formulario elige qué crear en el CRM desde su editor, en la pestaña Publicar > Integraciones: con + Integración eliges la conexión y qué crear, y asocias cada campo del CRM con un campo del formulario. Ver entregas lista cada respuesta enviada al CRM con su estado (Entregada, Fallida o Pendiente) y sus intentos, y te permite Reintentar una que falló.

Autenticación y límites

Envía Authorization: Bearer anota_sk_… en cada solicitud. La misma clave sirve para la API REST (https://anota.cloud/api/v1/…) y para el conector MCP (https://anota.cloud/mcp).
Cada clave de API tiene acceso completo a su espacio de trabajo: todos los formularios, respuestas, Plantillas, webhooks y Notificaciones por correo. Las claves no tienen permisos parciales ni fecha de vencimiento. Para un acceso limitado, conecta Claude o ChatGPT con el Inicio de sesión de un clic, donde el miembro elige los permisos (consulta Conectar Claude y ChatGPT (MCP)).
La API REST acepta solo claves de API. El Inicio de sesión de un clic es para el conector MCP.

Límites de uso

Cada clave tiene un presupuesto por minuto, compartido entre la API REST y el conector MCP:

120 solicitudes por minuto por clave.
30 respuestas creadas por minuto por clave (POST /api/v1/forms/{formId}/submissions, o create_submission por MCP), porque cada respuesta nueva puede enviar la autorespuesta al correo escrito en el formulario.

Al pasar un límite, anota responde 429 Too Many Requests con el encabezado Retry-After: 60 y el texto "Demasiados intentos. Espera un minuto e inténtalo de nuevo."

Errores

401 Unauthorized: falta el encabezado, no empieza con Bearer o la clave fue revocada.
400 Bad Request: anota no pudo hacer lo que pediste. El motivo está en el campo detail de la respuesta JSON, empieza con "Error:" y está en inglés; por ejemplo, un id de formulario que no existe en tu espacio de trabajo o un campo bloqueado porque el formulario ya se publicó.

Aplicaciones conectadas

Si los miembros conectan Claude o ChatGPT con el Inicio de sesión de un clic, la página Claves de API también las lista en Aplicaciones conectadas: "ChatGPT, Claude y otras aplicaciones que los miembros conectaron a este espacio de trabajo con su propia cuenta." La tabla muestra la Aplicación, el Miembro, los Permisos y la fecha en Conectada; Desconectar elimina la conexión de cualquier miembro. Si no hay ninguna, muestra Ninguna aplicación conectada todavía. Cada miembro gestiona las suyas en Configuración de la cuenta > Aplicaciones conectadas.

Qué envía un webhook

Por cada respuesta nueva, anota envía un POST HTTP a la dirección del webhook con un cuerpo JSON (Content-Type: application/json; charset=utf-8):

{
  "event": "submission.created",
  "formId": "01a0df96-83fe-747c-b14e-03b183c3f962",
  "formTitle": "Solicitud de pedido de catering",
  "submissionId": "…",
  "submittedAt": "2026-09-27T15:04:05.1234567",
  "answers": [
    { "fieldId": "f_…", "label": "Nombre completo", "value": "Sofía Herrera" },
    { "fieldId": "f_…", "label": "Correo electrónico", "value": "sofia.herrera@example.com" },
    { "fieldId": "f_…", "label": "¿Qué paquete te gustaría?", "value": "Panadería para el desayuno" }
  ]
}

submittedAt está en UTC, escrito sin indicador de zona horaria (igual que las fechas que devuelve la API, como updatedAt).
answers tiene una etiqueta y un valor legibles por cada respuesta. Una firma se envía como el texto [signature captured], no como imagen.
En los formularios que cobran con Stripe, el cuerpo tiene además un objeto payment con status, amount (en unidades mayores, 25.00 = 25 dólares), currency (USD o MXN), paidAt y paymentIntentId. En esos formularios el webhook se envía cuando el pago se completa, así que status normalmente es Paid. Los formularios sin pagos nunca incluyen payment.

Encabezados y firma

Encabezado	Valor
`X-Anota-Event`	`submission.created`, o `submission.approved` / `submission.rejected` para una aprobación
`X-Anota-Webhook-Id`	El `id` del webhook
`X-Anota-Signature`	`sha256=` seguido del HMAC-SHA256 del cuerpo original de la solicitud, con el secreto de firma del webhook como clave, en hexadecimal en minúsculas

Para verificar un envío, calcula el HMAC-SHA256 del cuerpo exactamente como lo recibiste (antes de interpretarlo) con tu secreto, y compáralo con el valor que sigue a sha256=.

Eventos de aprobación

Los webhooks creados con includeApprovalEvents (en add_webhook, o "includeApprovalEvents": true en el cuerpo de la llamada REST) reciben además un evento cuando un aprobador decide sobre una respuesta de un formulario que pide aprobación: submission.approved o submission.rejected. El cuerpo es el mismo de submission.created, con "event" con el nombre nuevo y un objeto approval adicional:

"approval": {
  "decision": "approved",
  "approverEmail": "manager@example.com",
  "comment": "Que disfrutes el viaje.",
  "decidedAt": "2026-10-04T14:19:03Z"
}

Los webhooks que se crearon sin esa opción nunca reciben estos eventos, así que las integraciones existentes siguen recibiendo solo submission.created. Cada entrega se firma y se reintenta igual que las demás.

Reintentos

anota espera tu respuesta hasta 10 segundos. Cualquier código 2xx cuenta como entregado. Si tu servidor no responde, tarda demasiado o devuelve otro código, anota vuelve a intentarlo, hasta 6 intentos en total, separados por unos 30 segundos, 2 minutos, 10 minutos, 30 minutos y 2 horas, así que una caída de un par de horas de tu lado queda cubierta. Un envío nunca hace más lenta ni afecta a la persona que llena el formulario. anota no tiene una pantalla con el historial de envíos de los webhooks.

Endpoints de la API REST

Todos los endpoints están bajo https://anota.cloud/api/v1. Ofrecen las mismas operaciones que las herramientas del conector MCP.

Área	Endpoints
Formularios	`GET /forms`, `POST /forms`, `GET /forms/{formId}`, `PATCH /forms/{formId}` (renombrar), `DELETE /forms/{formId}` (mover a la papelera), `POST /forms/{formId}/publish`, `POST /forms/{formId}/clone`, `PUT /forms/{formId}/pdf-template`
Campos	`POST /forms/{formId}/fields`, `PATCH /forms/{formId}/fields/{fieldId}`, `DELETE /forms/{formId}/fields/{fieldId}`
Reglas de lógica	`POST /forms/{formId}/logic-rules`, `PUT /forms/{formId}/logic-rules/{ruleId}`, `DELETE /forms/{formId}/logic-rules/{ruleId}`
Respuestas	`GET /forms/{formId}/submissions`, `POST /forms/{formId}/submissions`, `GET /submissions/{submissionId}`, `PATCH /submissions/{submissionId}/status`, `POST /submissions/{submissionId}/approval/resend`, `DELETE /submissions/{submissionId}`, `GET /forms/{formId}/stats`
Plantillas	`GET /templates`, `POST /forms/from-template/{templateId}`
Notificaciones por correo	`POST /forms/{formId}/email-notifications` (agregar), `PUT /forms/{formId}/email-notifications/{notificationId}` (actualizar)
Webhooks	`GET /forms/{formId}/webhooks`, `POST /forms/{formId}/webhooks`, `DELETE /forms/{formId}/webhooks/{webhookId}`

GET /forms/{formId}/submissions acepta page, pageSize (25 por defecto), status (New, Read, Flagged o Spam), payment (paid o unpaid) y approval (pending, approved o rejected); los pagos de Stripe no completados se ocultan salvo que los pidas. POST /submissions/{submissionId}/approval/resend envía por correo un enlace de revisión nuevo a los aprobadores de una aprobación pendiente. GET /templates acepta language (es, el predeterminado, en o pt).

SDK oficiales

anota publica bibliotecas cliente de código abierto para 10 lenguajes de programación, que cubren formularios, campos, Lógica condicional, respuestas y webhooks. Todas están en github.com/anotacloud con licencia MIT.

Lenguaje	Repositorio	Descarga
Android (Kotlin)	anota-api-android	ZIP · Tarball
C# / .NET	anota-api-csharp	ZIP · Tarball
Go	anota-api-go	ZIP · Tarball
iOS (Swift)	anota-api-ios	ZIP · Tarball
Java	anota-api-java	ZIP · Tarball
NodeJS (TypeScript)	anota-api-nodejs	ZIP · Tarball
PHP	anota-api-php	ZIP · Tarball
Python	anota-api-python	ZIP · Tarball
Ruby	anota-api-ruby	ZIP · Tarball
Scala	anota-api-scala	ZIP · Tarball

Cada repositorio tiene su propio README con los pasos de instalación, un ejemplo funcional y la lista completa de métodos.

Conectar Claude y ChatGPT (MCP)

La guía completa está en Conectar Claude y ChatGPT (MCP). En resumen:

Claude (web, escritorio, móvil) y ChatGPT: agrega https://anota.cloud/mcp como conector personalizado, inicia sesión en anota, elige un espacio de trabajo y los permisos, y haz clic en Permitir acceso. No necesitas clave de API.
Claude Code y otras herramientas para desarrolladores: crea una clave de API (tarea 1) y envíala como token Bearer a https://anota.cloud/mcp.

Ejemplo: le pides a Claude "Crea un formulario de inscripción a un evento con nombre, correo y una lista desplegable para el tipo de entrada (General o VIP)." Claude llama a create_form para crear el formulario como borrador con esos campos, listo para que lo revises en el editor de formularios y lo publiques.

Herramientas MCP disponibles

El conector tiene 28 herramientas. La API REST ofrece las mismas operaciones.

Formularios y campos

Herramienta	Qué hace
`list_forms`	Lista los formularios del espacio de trabajo (borradores y publicados; excluye los archivados), del actualizado más recientemente al más antiguo, con el id, el estado, la cantidad de respuestas y la URL pública de cada uno.
`get_form`	Obtiene la estructura completa de un formulario desde su borrador actual: título, estado, plantilla de PDF, su idioma base, cada página y campo (id, tipo, etiqueta, si es obligatorio, opciones, el contenido HTML de los campos de encabezado y párrafo), las traducciones del título, las páginas, los campos y los textos de configuración, cada regla de lógica condicional (con los ids que necesitan `edit_logic_rule` y `delete_logic_rule`) y sus notificaciones por correo (id, tipo notificación/autorespuesta, activa, destinatarios, asunto, attachPdf), con una nota que dice a quién se envía el correo.
`create_form`	Crea un formulario nuevo como borrador, con un título, un texto de introducción opcional y sus campos, todos en una sola página.
`add_fields`	Agrega uno o más campos al final del borrador de un formulario (su última página).
`edit_field`	Reemplaza la definición de un campo existente, conservando su id y su posición. Solo funciona mientras el formulario nunca se ha publicado.
`delete_field`	Elimina un campo. Solo funciona mientras el formulario nunca se ha publicado. Si una regla de lógica usaba el campo, esa referencia se quita de la regla (y la regla se elimina si no le queda nada), en lugar de bloquear la eliminación.
`publish_form`	Publica el formulario por primera vez, o pone en línea los cambios del borrador como una versión nueva. Las respuestas existentes se conservan. Salvo que el formulario tenga una notificación por correo activa (consulta `get_form`, `set_email_notification`), cada respuesta se envía por correo al dueño del espacio de trabajo.
`rename_form`	Cambia el título del formulario. La URL pública y las respuestas existentes no cambian.
`set_translations`	Escribe los textos del formulario en un idioma distinto de su idioma base: `title`, `pages` (títulos de página), `fields` (etiqueta, marcador de posición, texto de ayuda, `html` de encabezados y párrafos, `optionLabels` por valor de opción), `submitText`, `thankYouMessage`, `closedMessage`. Solo cambian los textos que se envían; una cadena vacía quita una traducción. También funciona en formularios publicados, porque las traducciones no cambian las respuestas guardadas; se aplican al volver a publicar el formulario.
`delete_form`	Mueve el formulario a la papelera: desaparece de las listas y su URL pública deja de aceptar respuestas, pero las respuestas se conservan y puedes restaurarlo desde la papelera en la aplicación. Un formulario en la papelera no cuenta para el límite de formularios de tu plan.
`clone_form`	Duplica un formulario como un borrador nuevo con su propia URL pública, copiando páginas, campos, reglas de lógica y plantilla de PDF (no las versiones ni las respuestas). Como la copia nunca se ha publicado, todos sus campos se pueden editar. Así se "editan" los campos bloqueados de un formulario publicado.
`set_pdf_template`	Define el diseño que se usa al exportar respuestas a PDF. Una clave de plantilla desconocida devuelve la lista de las válidas.
`add_logic_rules`	Agrega una o más reglas de lógica condicional al borrador de un formulario. Cada regla tiene sus condiciones (SI, que deben cumplirse "todas" o "cualquiera"), sus acciones (ENTONCES, consulta Acciones de lógica más abajo) y un indicador opcional `disabled` para agregarla en pausa. Las reglas nuevas se ejecutan después de las existentes.
`edit_logic_rule`	Reemplaza las condiciones, las acciones y el indicador `disabled` de una regla existente, identificada por su id (de `get_form`), conservando su posición entre las demás reglas.
`delete_logic_rule`	Elimina una regla de lógica por su id.

Plantillas

Herramienta	Qué hace
`list_templates`	Lista las plantillas listas para usar en español (`es`, el predeterminado), inglés (`en`) o portugués (`pt`), agrupadas por categoría.
`create_form_from_template`	Crea un formulario nuevo como borrador en tu espacio de trabajo, copiando la estructura completa de una plantilla.

Respuestas

Herramienta	Qué hace
`list_submissions`	Lista las respuestas de un formulario, de la más reciente a la más antigua, por páginas (hasta 100 por página), con un filtro opcional por estado (New, Read, Flagged, Spam) y otro por pago. Por defecto oculta las respuestas con pago de Stripe sin completar (pagos abandonados). Cada fila muestra su estado de aprobación y `approval` filtra por `pending`, `approved` o `rejected`.
`get_submission`	Obtiene las respuestas completas de un envío como pares legibles de etiqueta y valor, más su aprobación (los aprobadores con sus decisiones y comentarios) cuando el formulario pide aprobación.
`submission_stats`	Devuelve el total, la cantidad por estado, los conteos diarios de los últimos 7 días (UTC) y los conteos de pagos de Stripe (pagados / sin pagar).
`create_submission`	Crea una respuesta en un formulario publicado como si la hubiera llenado una persona: las respuestas se validan contra la versión en línea, se aplican los límites del plan y los correos de notificación y los webhooks funcionan como siempre.
`set_submission_status`	Cambia el estado de una respuesta a New, Read, Flagged o Spam. Solo cambia la etiqueta; las respuestas nunca se modifican.
`resend_approval_request`	Envía por correo un enlace de revisión nuevo a cada aprobador de una respuesta cuya aprobación sigue pendiente y anula los enlaces anteriores. Nunca aprueba ni rechaza: solo un aprobador puede decidir, desde su propio enlace.
`delete_submission`	Elimina para siempre una respuesta y sus archivos subidos. No se puede deshacer.

Notificaciones por correo

Herramienta Qué hace

set_email_notification Crea o actualiza una de las notificaciones por correo de un formulario: cada respuesta nueva se envía a los destinatarios indicados (de 1 a 10 direcciones, cualquier correo, no solo miembros del espacio de trabajo) como una tabla con las respuestas, con el PDF de la respuesta adjunto si quieres. Omite notificationId para crear una notificación nueva, o pasa un id de get_form para actualizar esa. enabled (true por defecto) se puede poner en false para pausar la notificación sin perder sus destinatarios. Máximo 10 notificaciones por formulario. No gestiona las autorespuestas (el correo que recibe la persona que respondió); esas se configuran solo en el editor.

Herramienta	Qué hace
`set_email_notification`	Crea o actualiza una de las notificaciones por correo de un formulario: cada respuesta nueva se envía a los destinatarios indicados (de 1 a 10 direcciones, cualquier correo, no solo miembros del espacio de trabajo) como una tabla con las respuestas, con el PDF de la respuesta adjunto si quieres. Omite `notificationId` para crear una notificación nueva, o pasa un id de `get_form` para actualizar esa. `enabled` (`true` por defecto) se puede poner en `false` para pausar la notificación sin perder sus destinatarios. Máximo 10 notificaciones por formulario. No gestiona las autorespuestas (el correo que recibe la persona que respondió); esas se configuran solo en el editor.

Webhooks

Herramienta	Qué hace
`list_webhooks`	Lista los webhooks de un formulario: id, URL, eventos, si está activo y una pista oculta del secreto de firma.
`add_webhook`	Agrega un webhook a un formulario y devuelve su secreto de firma (solo esta vez). Pasa `includeApprovalEvents` para recibir también `submission.approved` y `submission.rejected`.
`delete_webhook`	Elimina un webhook. Los envíos se detienen de inmediato.

Acciones de lógica (add_logic_rules / edit_logic_rule)

Cada regla tiene una lista if de condiciones, una lista then de acciones, un match opcional ("all", el predeterminado, o "any") y un indicador opcional disabled. Una regla necesita al menos una condición y al menos una acción.

Operadores de condición: equals, notEquals, contains, notContains, startsWith, endsWith, isEmpty, isNotEmpty, greaterThan, lessThan. El value se ignora en isEmpty e isNotEmpty.

Acciones: cada elemento de then tiene un campo action con uno de estos doce valores:

`action`	Campos adicionales	Qué hace
`show`	`targetId` (id del campo)	Muestra el campo.
`hide`	`targetId` (id del campo)	Oculta el campo.
`require`	`targetId` (id del campo)	Hace obligatorio el campo mientras la regla se cumple.
`unrequire`	`targetId` (id del campo)	Hace opcional el campo mientras la regla se cumple.
`enable`	`targetId` (id del campo)	Habilita el campo, deshaciendo un `disable` anterior.
`disable`	`targetId` (id del campo)	Deshabilita el campo; su respuesta nunca se incluye en el envío.
`copyValue`	`targetId` (campo destino), `copyFrom` (campo origen)	Copia la respuesta de `copyFrom` en `targetId`, en vivo en el navegador de la persona (como `calculate`). Necesita JavaScript; no tiene efecto si la persona lo tiene desactivado.
`skipToPage`	`targetId` (id de la página, p. ej. `p1`)	Salta directo a esa página.
`calculate`	`targetId` (campo numérico), `formula`	Asigna al campo el valor de la fórmula, que puede usar otros campos entre llaves, p. ej. `{f_qty} * 25`.
`routeEmail`	`emailTo`	Envía a esa dirección una copia de la notificación de esa respuesta.
`setThankYou`	`value` (texto)	Reemplaza el mensaje de agradecimiento por `value` mientras la regla se cumple. Si varias reglas con esta acción se cumplen, gana la primera (no la última), la única excepción al orden normal de las reglas. No tiene variantes por idioma.
`redirectTo`	`value` (URL)	Redirige a `value` en lugar de mostrar la pantalla de agradecimiento mientras la regla se cumple. Usa la misma lógica de "gana la primera regla" que `setThankYou`, y tiene prioridad sobre `setThankYou` si se cumplen las dos.

value es obligatorio y no puede estar vacío en setThankYou y redirectTo. Una llamada a la que le falta un campo obligatorio o lo tiene vacío se rechaza, y toda la llamada es de todo o nada: si alguna acción no pasa la validación, no se guarda nada.

Una regla con disabled: true se queda en el formulario, pero anota nunca la evalúa en la página pública. Es lo mismo que pausarla con el botón ⏸ del panel Condiciones del editor (consulta Lógica condicional).

Regla importante: los campos se bloquean al publicar

Un formulario empieza como borrador, sin restricciones. En cuanto se publica por primera vez, sus campos existentes se bloquean para proteger la integridad de las respuestas ya recibidas. A partir de ahí solo puedes agregar campos nuevos (add_fields); ya no puedes editar (edit_field) ni eliminar (delete_field) los campos que existían al publicarlo. La regla se aplica a la API REST y a Claude y demás conexiones MCP. El editor de formularios visual no tiene este bloqueo: un Editor todavía puede cambiar ahí un campo publicado.

Para cambiar o quitar un campo existente después de publicar, usa clone_form: la copia es un borrador nuevo con todos los campos editables. O haz el cambio antes de la primera publicación.

Las reglas de lógica no se bloquean: add_logic_rules, edit_logic_rule y delete_logic_rule funcionan igual en el borrador de un formulario publicado que en uno que nunca se publicó. Llama a publish_form después para poner el cambio en línea. Editar una regla que envía una copia por correo (routeEmail) se aplica a las respuestas nuevas desde ese momento; no reenvía las notificaciones ya enviadas.

Roles y permisos

Rol	Página Claves de API (crear, revocar, desconectar las aplicaciones de los miembros)	Página Integraciones (conexiones)	Publicar > Integraciones de un formulario
Propietario / Administrador	Sí	Sí	Sí
Editor	No (acceso denegado)	No	Sí, con las conexiones que existen
Lector	No (acceso denegado)	No	No

Los Editores y Lectores pueden desconectar sus propias aplicaciones en Configuración de la cuenta > Aplicaciones conectadas. Consulta Roles y permisos.

Solución de problemas

Síntoma	Causa probable	Solución
No puedes ver completa una clave que ya creaste	anota muestra la clave completa una sola vez, al crearla	Crea una clave nueva y revoca la anterior.
`401 Unauthorized` desde `/api/v1` o `/mcp`	Falta el encabezado `Authorization`, no empieza con `Bearer` o la clave fue revocada	Envía `Authorization: Bearer anota_sk_…` y comprueba que la clave siga en la página Claves de API.
`400 Bad Request`	anota no pudo hacer lo que pediste	Lee el campo `detail` de la respuesta; dice qué corregir.
`429 Too Many Requests`	Más de 120 solicitudes por minuto con la clave, o 30 respuestas creadas por minuto	Espera un minuto (consulta `Retry-After`) y espacia tus solicitudes.
`edit_field` o `delete_field` falla	El formulario se publicó al menos una vez, así que sus campos existentes están bloqueados	Agrega campos nuevos con `add_fields`, o usa `clone_form` y edita la copia.
`edit_logic_rule` o `delete_logic_rule` dice que no encontró el id	El id de la regla no existe en el borrador actual del formulario	Llama a `get_form` para obtener los ids actuales e inténtalo de nuevo.
Se rechaza el webhook que quieres agregar	La dirección no es HTTPS, no se resuelve o apunta a una red privada o interna; o el formulario ya tiene 10 webhooks	Usa una dirección HTTPS pública, o elimina antes un webhook.
Tu sistema rechaza las firmas del webhook	El secreto no es el correcto, o el HMAC se calculó sobre un cuerpo reserializado en lugar del cuerpo original	Usa el secreto que recibiste al agregar el webhook (compáralo con `secretHint`) y firma el cuerpo exactamente como llegó. Si perdiste el secreto, elimina y vuelve a agregar el webhook.
Tu sistema no recibe nada	No ha llegado ninguna respuesta nueva desde que agregaste el webhook, o tu servidor devolvió errores en los 6 intentos	Envía una respuesta de prueba y revisa los registros de tu servidor.
No ves API ni Integraciones en la barra superior	Tu rol es inferior a Administrador	Pídeselo a un Administrador o al Propietario.
Crear una clave falla con "No pudimos crear la clave. Inténtalo de nuevo."	Un error temporal	Inténtalo de nuevo; si sigue pasando, contacta a soporte.

Funciones relacionadas

¿Te resultó útil esta página?

Anterior Autenticación de dos factores y passkeys Siguiente Conectar Claude (MCP)