Detener un envío defectuoso antes de Enviar con la verificación previa

Un envío rechazado cuesta lo único que este producto no puede recuperar: una persona que estaba en la página y dejó de estarlo. FormFlow conserva cada rechazo como un registro sobre el que puedes actuar, y las señales de salud del formulario los cuentan. La verificación previa es la única parte de ese juicio que se ejecuta antes de Enviar. Llegó con la v1.0.0.

Qué responde una verificación previa

Envía un POST a /api/v1/f/{token}/preflight con las respuestas que tu formulario habría enviado, en JSON, y el token público del formulario en la ruta. El endpoint devuelve el juicio que el endpoint de ingesta haría sobre esas respuestas, sin hacerlo. Pasa la cabecera Origin de tu propia página y se comprueba exactamente como la comprueba el endpoint de envío. El contrato está escrito en la referencia de la API.

La respuesta tiene cuatro claves: ok, errors, checked y policy. errors es un objeto con nombres de campo como claves y listas de frases como valores, y sigue siendo un objeto aunque esté vacío para que un cliente generado pueda indexarlo. checked nombra lo que se preguntó de verdad — forma, origin y esquema — con origin ausente en una página alojada, porque la página que sirve FormFlow no está sujeta a tu lista de orígenes permitidos.

Llámala mientras la persona sigue en la página

Un solo fetch basta. Esta es la forma de la llamada; engánchala al evento en el que tu página ya confía, como salir de un campo.

const endpoint = 'https://formflow.digital/api/v1/f/YOUR_FORM_TOKEN/preflight'

async function preflight(answers) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
    body: JSON.stringify(answers),
  })

  // A 429 or an outage is not a verdict. Say nothing rather than something wrong.
  if (!response.ok) return null

  const { ok, errors, checked, policy } = await response.json()
  return ok ? [] : Object.entries(errors)
}

Muestra las frases que vuelven junto al campo que cada una nombra. No repitas las reglas en tu propio código: la razón de ser del endpoint es que el mensaje que lee la persona sea el mensaje que el endpoint habría usado, en el idioma del formulario y no en el de tu JavaScript.

Leer la respuesta

Dos claves de errors no son campos. origin lleva un rechazo de la lista de orígenes permitidos, y submission lleva un rechazo que pertenece al formulario y no a una respuesta concreta, como un formulario cerrado. Registra el bloque policy: la revisión y la huella juntas identifican la política exacta que usó el juicio, que es lo que necesitas el día que un aprobado aquí va seguido de un rechazo allí.

Qué no pregunta

Solo pregunta la mitad de la decisión que es función pura de la configuración del formulario. No ejecuta la puntuación de spam, no pide el desafío de Turnstile y no mira los campos de archivo en absoluto: una verificación previa no lleva bytes, así que una imagen declarada no se comprueba ni se promete. No guarda fila, no consume cuota y no entrega nada.

Pero sí está dentro del limitador de peticiones. Comparte el cubo token|IP y el cubo de peticiones de todo el equipo con el endpoint de envío, así que una ráfaga puede devolver 429 con Retry-After. Un 429 es la ausencia de veredicto, no un rechazo, y la página debe callarse en vez de inventar un error.

Dónde encaja

Todos los demás mecanismos que FormFlow tiene para un envío rechazado funcionan después de que alguien haya sido rechazado: el registro de rechazos, la señal de salud, la superficie de rechazo y la bandeja de recuperación. Esta es la única que funciona antes. Úsala como el primero de los dos juicios, nunca como el único.

• Un aprobado no es una promesa. El POST decide, y decide otra vez con todo lo que la verificación previa no preguntó.

• Cambia el formulario entre las dos llamadas y la respuesta puede cambiar con él. La revisión de política de la respuesta es la que te juzgó.

• Los campos de archivo no se examinan, así que nunca le digas a quien envía que su imagen fue aceptada por una verificación previa.

• errors tiene nombres de campo como claves, pero origin y submission no son campos; muéstralos en la parte superior del formulario.

• Cualquiera que tenga el token público del formulario puede llamarla. No prueba nada sobre quién llama y no es un secreto.