API · MÓDULO LANDINGS

Landings: cómo funciona

API en preparación. Esta guía describe su contrato. Confirma que el módulo esté disponible y habilitado en tu espacio antes de integrar estas rutas.

Le das a Bentho un brief y la URL que recibe los formularios. Bentho escribe una landing de una sola página, la prueba en un navegador (formulario, enlaces, teclado, escritorio y móvil) y te la entrega en un HTML listo para publicar donde quieras.

También puedes hacerlo desde la consola: entra al Estudio de un espacio con el módulo activo y abre Landings. El panel permite crear la landing, responder a los datos que falten, refinarla, consultar su calidad y descargar el HTML.

Antes de empezar

El espacio tiene que tener el módulo Landings: landing sale en sus módulos en GET /api/companies. Si no, cada ruta responde 403 módulo no habilitado para este espacio.
Crear, refinar, validar, completar, cancelar y borrar piden una clave escribe. Leer vale con cualquier clave.
Las rutas cuelgan de /api/mod/landing/{espacio}/, con la misma clave y los mismos límites que el resto de la API.

El recorrido

Crea la landing: responde 202 con su id y la versión 1 en pendiente.
Consulta su estado cada 10 a 15 s. Suele tardar unos minutos.
Si queda en esperando_datos, enséñale a tu usuario las preguntas de faltantes y manda lo que responda a completar. La versión sigue sola.
Cuando termine (aprobado o revision), descarga su HTML y publícalo.
Para cambiarla, refínala con una instrucción. Si la retocaste a mano, mándala a validar.

ESTADOS

pendiente → generando → aprobado | revision | fallido
                     ↘ esperando_datos → (completar) → pendiente
generando → aplazado → generando        (se reanuda sola)
cualquiera en curso → (cancelar) → cancelado

Versiones

Cada generación, refinado o validación es una versión nueva de la misma landing. Las anteriores se conservan y puedes pedir cualquiera con ?version=.
Una landing tiene una sola versión en curso: pedir otra mientras tanto da 409. Cancélala o espera.
Un espacio tiene un tope de landings generándose a la vez: al pasarlo, 429. Las que esperan datos no cuentan.
aprobado quiere decir que pasó las dos revisiones: la de funcionamiento (el formulario envía, los enlaces llevan a su sitio, se usa con teclado, nada se sale de la pantalla) y la de diseño, en escritorio y en móvil. revision trae HTML, pero alguna no pasó: calidad.motivos dice cuál.
El certificado (calidad) vale para un HTML exacto, el de su html_sha256. Si lo retocas, ya no vale: mándalo a validar.

Datos que faltan

Bentho no inventa testimonios, reseñas, resultados, ponentes, agendas ni fechas. Si el brief pide algo así sin darlo, antes de escribir te pregunta (hasta cinco cosas). Respondes lo que tengas y omites lo demás; lo omitido se escribe sin ese elemento y sin avisarle al visitante de que falta. Para que no pregunte, crea la landing con revisarBrief: false.

Lo que recibe tu submitUrl

Al enviar, el formulario de la landing hace un POST desde el navegador del visitante a tu submitUrl, con Content-Type: application/json:

CUERPO DEL ENVÍO

{
  "page_id": "curso-excel-otono",
  "source": "https://tu-dominio.com/excel-para-pymes?utm_source=newsletter",
  "nombre": "Ana",
  "email": "[email protected]",
  "telefono": "+34 600 000 000",
  "utm_source": "newsletter"
}

page_id es el pageId que mandaste al crearla, y source, la dirección de la página. Después, un campo por cada campo del formulario.
Llegan también utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid, ttclid y msclkid si la visita los traía, aunque el visitante haya pasado por otras páginas antes de enviar.
Contesta con un 2xx y {"success": true}. Con cualquier otra cosa, el visitante ve «No pudimos enviar tu solicitud» y puede reintentar.
El envío sale del navegador: si tu submitUrl está en otro dominio que la landing, tiene que aceptar CORS (la petición previa OPTIONS y el POST con Content-Type: application/json).

El formulario: formConfig

Sin formConfig, Bentho arma el formulario según el brief. Con él, lo fijas tú:

CAMPO	QUÉ ES
`fields`	Obligatorio. Hasta 20 campos, en orden: `name` (letras, números y `_`, empieza por letra; no puede ser `page_id` ni `source`), `label`, `type` (`text`, `email`, `tel`, `number`, `textarea` o `select`), `required` (boolean), y si quieres `placeholder` y `options` (para `select`, hasta 30).
`success_message`	Obligatorio. Lo que ve el visitante al enviar. Hasta 2000 caracteres.
`cta_text`	El texto del botón de envío.
`redirect_url`	Adónde lleva al visitante después de enviar (HTTP o HTTPS).
`cta_url` · `cta_links`	Adónde llevan los botones que no son el envío: una URL para todos o una lista `[{text, url}]`, en orden.

FORMCONFIG

{
  "fields": [
    { "name": "nombre", "label": "Nombre", "type": "text", "required": true },
    { "name": "email", "label": "Email", "type": "email", "required": true },
    { "name": "telefono", "label": "Teléfono", "type": "tel", "required": false }
  ],
  "cta_text": "Quiero mi plaza",
  "success_message": "¡Listo! Te escribimos en menos de 24 horas."
}

Un formConfig que no cumple esta forma no da 422: la versión termina en fallido y error dice por qué.

Créditos

Crear, refinar, validar y completar gastan créditos de la bolsa de tu cuenta, como las preguntas. Lo que gasta cada una depende del brief y de cuánto haya que corregir.
Con la bolsa agotada, esas cuatro rutas responden 402 (bolsa_agotada). Leer, cancelar y borrar siguen funcionando.
Cancelar o borrar no devuelve lo que ya se gastó.
El saldo, en la bolsa de créditos.

Tamaños

El cuerpo de una petición, hasta 24 MB.
prompt, hasta 24 000 caracteres; brandBlock, hasta 20 000; funnelReferenceHtml y el html de validar, hasta 300 000.
El PDF, en base64 dentro del JSON: hasta 16 000 000 de caracteres, unos 12 MB de PDF.