REDA Data Service: conecte sus formularios

Cualquier formulario que use fuera de REDA — un formulario de contacto en el sitio de marketing, una landing page de campaña, un micrositio en Webflow — puede crear o actualizar un registro de REDA en el instante en que se envía, con toda la atribución de campaña incluida, sin escribir código. El Data Service es el motor empaquetado de captación web entrante de REDA: su formulario envía una pequeña solicitud web, REDA la verifica contra una fila de permisos que usted controla, y un mapeo que usted configura convierte los valores recibidos en un registro real. Este artículo está escrito para el administrador o el desarrollador web que conecta esa integración. Muestra cómo construir la dirección a la que su formulario envía la solicitud, cómo autenticarla, cómo dar forma al cuerpo de la solicitud, el conjunto de campos ya listo que alimenta una consulta web, y a dónde va un envío fallido para que pueda encontrarlo y corregirlo. Este es contenido orientado a desarrolladores, así que — a diferencia del resto del Centro de ayuda — muestra las direcciones web y los campos de solicitud literales que necesitará.

Cómo funciona

El Data Service acepta una solicitud web de su formulario, confirma que está permitida y la entrega para convertirla en un registro. El punto clave de diseño es que la aceptación y la creación del registro son dos momentos separados:

Como la aceptación y la creación están desacopladas, una respuesta de éxito significa "su solicitud fue aceptada", no "el registro ya existe". Casi todos los envíos sí se convierten en un registro; los raros fallos durante ese paso en segundo plano quedan registrados en el registro asincrónico en lugar de perderse, por lo que ese registro es su red de seguridad (vea Cuando algo falla).

El paso en segundo plano es casi instantáneo para un solo envío y procesa los envíos de a uno cuando llegan varios a la vez, de modo que ante una ráfaga — un envío masivo de correo de campaña, por ejemplo — los registros pueden aparecer un momento después de sus respuestas de éxito y no todos a la vez. Esto es normal y no pierde nada; toda solicitud aceptada se escribe o se registra.

Activación y controles de acceso

Antes de que cualquier formulario pueda crear registros, deben cumplirse cuatro condiciones. Toda solicitud — ya sea una solicitud de lectura al estilo del navegador o un envío de formulario — pasa por el mismo control:

De fábrica, un tipo de registro ya está conectado y listo para usarse: la Consulta — el registro de REDA para un prospecto que se ha puesto en contacto — con lectura, envío, creación y edición habilitados, y una clave de autenticación ya definida. Un segundo tipo de registro, la Solicitud de servicio, viene desactivada: su fila de Configuración existe, pero todos los interruptores están apagados, por lo que no acepta nada hasta que un administrador la active. Agregar sus propios tipos de registro sigue el mismo patrón, cubierto en Agregar objetos y fuentes al Data Service.

El endpoint

Su formulario envía la solicitud a una dirección web que indica el tipo de registro que está creando y la fuente de datos — una etiqueta que agrupa una familia de formularios para que sus mapeos se mantengan separados de los de otra. La dirección sigue esta forma:

<Your Site URL>/services/apexrest/reda1/dataservice/<Record Type>/<Data Source>

Para la captación de consultas web ya incluida, el tipo de registro es la Consulta y la fuente de datos es Web, lo que da una dirección que termina así:

.../dataservice/reda1__Inquiry__c/Web

La primera parte — la URL de su sitio — es la dirección web pública que su administrador configuró para exponer el servicio; pídasela. Una solicitud exitosa devuelve de inmediato una respuesta 200 con {"success": true}. Si falla un control de entrada, obtiene una respuesta 400 con un mensaje breve que explica por qué, y si el interruptor maestro está apagado, obtiene un 400 con un mensaje de "deshabilitado".

La solicitud

Un envío de formulario es una solicitud POST. Su cuerpo es una pequeña lista de pares clave/valor — una entrada por cada campo que envía — escrita en JSON:

[
  {"key": "FirstName", "value": "Aisha"},
  {"key": "LastName",  "value": "Rahman"},
  {"key": "Email",     "value": "aisha@example.com"}
]

Cuando la fila de Configuración exige autenticación, la solicitud también lleva la clave en un encabezado llamado x-api-key. (Una solicitud de lectura tipo GET funciona igual, pasando los valores como parámetros de la dirección en lugar de un cuerpo; los formularios deben usar POST).

Que una solicitud cree un registro nuevo o actualice uno existente lo decide un solo campo: recordId.

Envíe un recordId cuando Edit Record está apagado (o una creación cuando Create Record está apagado) y REDA responde "DML Operation not supported." — le está indicando que la operación que pidió no está habilitada en esa fila de Configuración.

La integración web ya incluida

Un mapeo es la tabla de traducción entre las claves que envía su formulario y los campos del registro de REDA. REDA incluye un mapeo completo para consultas web: 21 parámetros que cubren los datos del visitante, de dónde viene y todo el conjunto de atribución de marketing. Envíe cualquiera de estas claves en su solicitud y llegarán al campo correcto de la consulta. Dos de ellas llevan un valor predeterminado, que se aplica cuando su formulario omite el valor:

No tiene que enviar las 21 — envíe las que tenga su formulario. La fuente de datos Web mantiene este grupo de mapeos unido, de modo que otra familia de formularios puede usar su propia fuente de datos con un conjunto distinto de claves, sin que se superpongan.

Cuando algo falla: el registro asincrónico

Como el registro se construye un momento después de que su formulario recibe la respuesta de éxito, el lugar para confirmar qué ocurrió realmente es el registro asincrónico — el registro de REDA del procesamiento en segundo plano. Cuando un envío no puede convertirse en un registro — falta un campo obligatorio, un valor incumple una regla — REDA revierte la escritura y en su lugar crea una entrada en el registro asincrónico. Nada se pierde en silencio.

Cada entrada de un envío fallido lleva la fuente de la que proviene, un conteo de fallos y — lo más útil de todo — la solicitud completa en sus detalles, para que pueda ver exactamente qué envió el formulario y por qué fue rechazada. Para corregir un envío incorrecto, corrija el formulario (o los datos) y envíelo de nuevo; no hay reintento automático. Para conocer la anatomía del registro en sí, el indicador Attention Needed y las alertas por correo al administrador, consulte Understanding REDA Async Logs.

Ejemplo práctico: una landing page de campaña

Meridian Properties tiene una landing page de arrendamiento de verano. Cuando un prospecto completa el formulario de contacto, la página envía esta solicitud a .../dataservice/reda1__Inquiry__c/Web con un encabezado x-api-key que lleva la clave de Meridian:

[
  {"key": "FirstName",    "value": "Aisha"},
  {"key": "LastName",     "value": "Rahman"},
  {"key": "Email",        "value": "aisha@example.com"},
  {"key": "utm_source",   "value": "google"},
  {"key": "utm_campaign", "value": "summer-lease"},
  {"key": "gclid",        "value": "..."}
]

REDA responde 200 {"success": true}, y momentos después aparece una consulta llamada Aisha Rahman — con Origen de la consulta Web, y la campaña y el ID de clic de Google registrados para los informes de marketing.

Actualizar en lugar de crear. Si Aisha vuelve a enviar el formulario más tarde con su número de teléfono, la misma solicitud más {"key": "recordId", "value": "<id de su consulta>"} actualiza su consulta existente en lugar de crear un duplicado.

Cuando falla. Si un envío llega con un campo obligatorio faltante, no se crea ningún registro — pero aparece una entrada en el registro asincrónico con la carga útil completa, para que pueda ver qué se envió y corregir el formulario.

Qué sigue

1. Agregar objetos y fuentes al Data Service — conecte el mismo motor a un nuevo tipo de registro o divida los formularios en fuentes separadas.
2. Consultas web y solicitudes de recorrido — la vía de captura hermana, donde las páginas de listados de REDA escriben consultas directamente.
3. Understanding REDA Async Logs — la anatomía completa del registro de fallos al que remite este artículo.
4. Cómo leer datos de REDA mediante las APIs de Salesforce — el lado saliente, de lectura y escritura, por contraste.
5. Buscar y fusionar consultas duplicadas — para limpiar cuando el mismo prospecto envía el formulario dos veces.

Preguntas frecuentes