Integraciones · Tu formulario
El autocompletado de direcciones en tu formulario, en tres archivos.
Sin plugin, sin plataforma: un archivo JavaScript que se conecta a los campos que ya tienes, un proxy listo para tu servidor que mantiene el token a salvo, tres líneas para unirlos. El visitante escribe, la calle se completa, el código postal, la ciudad y la provincia se rellenan solos; una dirección escrita a mano se verifica al salir del campo. Sugerencias de los registros de 26 países.
Qué hay en el kit
- ra-suggerisci.js·el widget: sin dependencias, el mismo archivo que los plugins de WooCommerce y PrestaShop; sugiere mientras se escribe y, al seleccionar, reparte la dirección verificada entre los campos
- ra-proxy.php·el proxy: guarda el token en el servidor, acepta solo tu dominio, frena por visitante, reenvía a RadarAddress; si falta el token o el crédito se ha agotado, responde con una lista vacía y el formulario sigue adelante
- esempio.html·un formulario completo — país, dirección, código postal, ciudad, provincia — que funciona en cuanto el token está en el proxy: se copia y se adapta
- README·las opciones del widget, el contrato del proxy para quien no usa PHP, qué consume
Cómo se hace, en tres pasos
Crea la cuenta y el token
La cuenta es gratuita, no pide tarjeta y cada mes incluye una cuota de operaciones: el token se crea con un clic y los pasos están explicados ahí.
Pon el proxy en el servidor
Copia ra-proxy.php en el mismo dominio del formulario y escribe el token en la línea indicada (mejor aún: en un archivo fuera de la carpeta web, leído desde ahí). Nada más que configurar.
Conecta el widget a los campos
Incluye ra-suggerisci.js en la página e indica los selectores de tus campos: dirección, código postal, ciudad, provincia y, si lo hay, el país. El resto lo hace el widget.
<script src="ra-suggerisci.js"></script>
<script>
RASuggerisci.attacca({
url: '/ra-proxy.php', // el proxy en tu servidor, nunca la API
campi: { indirizzo: '#indirizzo', cap: '#cap', localita: '#citta',
provincia: '#provincia', nazione_iso2: '#nazione' }, // el país es opcional
lingua: 'es'
});
</script>
campi acepta cualquier selector CSS. Las opciones adicionales: onSeleziona recibe el registro verificado (dirección normalizada, resultado, coordenadas cuando las hay), scriviCampo para los formularios de React y Vue, correggiAlBlur para decidir si también se verifican las direcciones escritas a mano, headers para un token CSRF hacia el proxy. Todo en el README del kit; el contrato de la API está en la documentación.
Requisitos: cualquier página web y, para el proxy del kit, PHP 8.0 o posterior con cURL; si no, sesenta líneas en tu lenguaje. El widget se publica con licencia Academic Free License 3.0.
Qué ocurre en el formulario
- Mientras escribe·tras dos letras el widget propone las calles, con el nombre completo y el municipio; las letras siguientes filtran lo que ya ha recibido, sin llamar al servidor en cada tecla; el código postal y la ciudad ya rellenados acotan la búsqueda
- Al seleccionar·la dirección verificada entra en los campos en la forma correcta — calle completa, número, el código postal correcto incluso en las grandes ciudades con zonas postales, ciudad y provincia — y se cuenta una verificación de contacto; los números de la calle se completan sin cargos adicionales
- Escrita a mano·quien ignora la lista y lo escribe todo por su cuenta se verifica al salir del campo: si la dirección se reconoce, los campos se ajustan; si no, se queda como está. Nada bloquea nunca el envío
- En el extranjero·con el país indicado, las sugerencias vienen del registro de ese país y el visitante escribe como se escribe allí, incluso todo en un solo campo; la atribución del registro está al final de la lista
Preguntas frecuentes
¿Por qué hace falta un proxy? ¿No puedo llamar a la API desde la página?
El token de la API da acceso a tu crédito: en la página lo leería cualquiera. El widget solo habla con una dirección de tu propio sitio; ahí un archivo de sesenta líneas añade el token y lo reenvía. El proxy PHP del kit está listo: se copia, se escribe el token, y ya está.
Mi sitio no está en PHP.
El proxy es la referencia, no una obligación: recibe el JSON del navegador, añade la cabecera Authorization con el token, lo reenvía a /api/v1/suggest y devuelve la respuesta. Se reescribe en cualquier lenguaje en pocos minutos; el README describe el contrato.
¿Funciona con React, Vue, Angular?
Sí: el widget se conecta a los campos con cualquier selector CSS. Los formularios controlados exigen que el valor se escriba con el setter nativo: para eso está la opción scriviCampo, la misma que usa el plugin de WooCommerce en el checkout de bloques.
¿Qué consume?
Escribir es gratis. Se cuenta una verificación de contacto cuando el visitante selecciona una dirección de la lista (o cuando una dirección escrita a mano se verifica al salir del campo, si dejas activado correggiAlBlur): una por dirección, no por tecla. Cada mes las primeras 50 son gratuitas; a partir de ahí, los paquetes y las suscripciones de la página de precios.
¿Y si el crédito se agota, o RadarAddress no responde?
El widget calla y el formulario funciona como siempre: ningún mensaje al visitante, ningún envío bloqueado. El proxy devuelve una lista vacía ante 401, 402 y cualquier error de red.
¿Vale para el extranjero?
Para todos los países en servicio: basta un campo con el código ISO del país (un select con IT, DE, FR… o un campo oculto) indicado en nazione_iso2. El visitante escribe como se escribe en su país, incluso todo en un solo campo; el popup muestra la atribución del registro.
¿Puedo cambiar el aspecto del popup?
El widget trae sus propios estilos, sin archivo CSS: las variables --ra-sugg-bg, --ra-sugg-bordo y --ra-sugg-hover en tu página cambian los colores; la clase es .ra-sugg-pop para el resto.
Versiones
- 1.0.0 — primera versión del kit: widget, proxy PHP con frenos y control del origen, formulario de ejemplo, README.
Las otras integraciones: WooCommerce, PrestaShop, AcyMailing, Convert Forms y Community Builder. La lista.