Formularios web
El único endpoint que tu propio sitio llama, y el único de Wrap que acepta un navegador.
POST https://wrap.eel.software/api/inbound/web-form
Casi toda la API de Eel es de servidor a servidor. Este endpoint es la excepción: existe para que el formulario de contacto de tu sitio deje una conversación en la bandeja.
No usa clave de API. Se identifica por el canal.
El cuerpo
{
"channelInstanceId": "…",
"email": "ana@ejemplo.com",
"message": "Quiero cotizar 200 unidades",
"name": "Ana Restrepo",
"phone": "+57 300 123 4567",
"formId": "contacto-home",
"source": "landing-black-friday",
"consentMarketing": true
}| Campo | Obligatorio | Notas |
|---|---|---|
channelInstanceId |
Sí | Identifica el formulario. Sale de la pestaña del canal en Wrap |
email |
Sí | Es lo que permite responder. Máximo 254 caracteres |
message |
Sí | Entre 1 y 20 000 caracteres |
name |
No | Hasta 120 |
phone |
No | Hasta 40 |
formId |
No | Para distinguir dos formularios del mismo canal |
source |
No | De dónde venía la visita |
consentMarketing |
No | Solo un true explícito concede el permiso |
Sobre lo último: que el campo falte no es una negativa, y un false no revoca
nada. Revocar tiene sus propios caminos, y ninguno es omitir una casilla.
Firmar los envíos
Si el canal tiene un secreto configurado, cada envío tiene que venir firmado. Calcula un HMAC-SHA256 del cuerpo crudo de la petición y mándalo así:
X-Wrap-Signature: sha256=<hex>Fírmalo sobre los bytes exactos que envías, antes de cualquier reserialización. Volver a convertir el objeto a JSON para firmarlo es la forma más común de producir una firma que no coincide.
Sin firma, o con una que no cuadre, se rechaza.
Sin secreto
El endpoint acepta envíos anónimos, limitados a 20 por minuto por IP y por formulario.
Es una red mínima, no una defensa. Si el formulario está expuesto en una página pública, pon un captcha delante en tu propio sitio.
Llamadas desde el navegador
Es el único endpoint de Wrap que las acepta: responde el preflight y manda
Access-Control-Allow-Origin: *, para que el formulario se envíe desde el
navegador de quien lo llena.
El resto de la API pública de Wrap no manda cabeceras CORS y no es alcanzable desde una página. Una clave de API en el JavaScript de un sitio es una clave publicada.
El canal define el espacio
El espacio de trabajo se lee del canal al que apunta channelInstanceId. No hay
campo de espacio en el cuerpo, así que nadie puede mandar una consulta al espacio
de otro cambiando un valor del JSON.