Formularios
Formularios de suscripción, las personas que los rellenan y sus cifras.
Herramientas de formularios
| Herramienta | Qué hace |
|---|---|
| listForms | Los formularios de suscripción del espacio de trabajo, primero los modificados más recientemente, con su estado, sus suscripciones y sus vistas. |
| getForm | Un formulario completo: sus campos, sus textos, sus audiencias, el doble opt-in y las notificaciones. Un formulario publicado añade su enlace, su código de inserción y la dirección a la que envía los datos un formulario HTML simple, e includeDesign devuelve el borrador como JSON. |
| listFormStarters | Los puntos de partida desde los que puede empezar un formulario nuevo, con los campos que pide cada uno. |
| createForm | Crea un formulario a partir de un punto de partida, de un diseño escrito como document o de un punto de partida con cambios encima, con cualquier ajuste. Sigue siendo un borrador salvo que publish sea true. |
| updateForm | Cambia el nombre y los ajustes de un formulario, que se aplican al instante, o el diseño de su borrador mediante document. Los textos y el estilo se fusionan clave por clave, y fields sustituye la lista entera. |
| publishForm | Convierte el borrador actual en lo que ven los visitantes, para que el formulario acepte suscripciones. |
| setFormStatus | Pausa un formulario publicado o vuelve a abrirlo. |
| duplicateForm | Copia un formulario en un borrador nuevo, sin sus suscripciones. |
| deleteForm | Elimina para siempre un formulario y sus suscripciones. Su enlace y sus inserciones dejan de funcionar, y las personas que añadió siguen en tus contactos. |
| getFormAnalytics | Vistas, suscripciones, personas añadidas y las que siguen esperando, y la tasa de conversión en un periodo, en total y por minuto, hora o día. Las vistas se guardan por hora. |
| listFormSubmissions | Las personas que rellenaron un formulario, de la más reciente a la más antigua, con sus respuestas y su estado, una página cada vez. Permite buscar por dirección de correo y filtrar por estado. |
| getFormSubmission | Una suscripción completa: cada respuesta, su estado, cuándo llegó y cuándo se añadió a la persona, la página de la que vino y sus audiencias. |
| approveFormSubmission | Añade una suscripción que espera su confirmación, sin el correo. También requiere contacts:write. |
| resendFormConfirmation | Envía por correo un enlace de confirmación nuevo a una suscripción que sigue pendiente. No se envía nada si este formulario escribió a esa dirección en los últimos diez minutos o si la dirección ya recibió cinco correos de este espacio de trabajo en el último día. También requiere emails:send. |
| removeFormSubmissions | Elimina hasta 200 suscripciones de un formulario por id. Los contactos y las audiencias se quedan como están. |
Leer requiere forms:read y cada cambio requiere forms:write. Todo lo que haga que un formulario envíe correo también requiere emails:send: activar el doble opt-in, configurar el remitente o el correo de confirmación, publicar o volver a abrir un formulario con doble opt-in, y reenviar una confirmación. Un cliente que actúa por un miembro solo ve los formularios que creó ese miembro, y un cliente limitado a algunas direcciones solo puede enviar confirmaciones desde direcciones a las que puede llegar, y solo puede avisar a esas direcciones.
Diseñar un formulario a partir de una descripción escrita se hace en el chat de la app. Por MCP, el diseñador es el cliente: pasa los campos, los textos y el estilo como document a createForm o updateForm, y las herramientas ordenan el diseño y dicen qué han cambiado.
Siete herramientas de este servidor hacen un cambio que la API REST protege con un código de verificación, y piden el mismo código: createRule, setRuleEnabled, removeDomain, removeDomainAddress, removeAppHost, deleteForm y deleteAudience en una audiencia que creaste. Hasta que el cliente haya verificado un código en los últimos 60 minutos, o la persona haya elegido Permitir cambios durante 60 minutos para él en Cuenta → Aplicaciones conectadas, esa herramienta responde con un resultado que empieza por Refused (step_up_required): y no cambia nada. emptyAudience nunca pide un código. La página Autenticación de la API muestra cómo pedir un código y verificarlo.
Las herramientas aplican las mismas reglas y los mismos rechazos que la API REST, y las páginas de /forms de la referencia de la API describen cada campo. listForms ordena por la última modificación, y createForm y updateForm arreglan un document parcial, mientras que la API lo recibe entero.
