Validar una dirección postal
Un número de apartamento faltante o un tipo de calle intercambiado convierten una entrega en un paquete perdido y un ticket de soporte. La API para validar direcciones postales analiza direcciones en texto libre, las separa en campos estructurados, corrige errores comunes de formato y las estandariza según las convenciones postales conocidas, para que la dirección guardada en su base de datos sea la que de verdad lleva un paquete o una carta hasta la puerta.
Ejecútela online
Ejecute esto en nuestros servidores con su cuenta. Las herramientas gratuitas corren en su navegador; esta cobra de su saldo del KIT según el precio de arriba.
El costo cotidiano de una dirección desordenada
Los datos de dirección suelen estar desordenados porque casi siempre se escriben una sola vez, a mano, sin mucha revisión, durante un pago o un registro. Las abreviaturas varían según el usuario y la región, los números de apartamento o unidad se omiten, los tipos de calle se escriben mal o se dejan fuera, y la misma dirección real termina guardada de una docena de formas distintas dentro de una base de clientes. Nada de eso importa hasta que un transportista, un sistema de facturación o un control de cumplimiento necesita que la dirección sea exacta, momento en el que el desorden se convierte en devoluciones, entregas fallidas y limpieza manual.
Qué hace el endpoint con una dirección sin procesar
Envíe texto libre o datos parcialmente estructurados a POST /verify/address y la tarea los separa en componentes discretos como calle, número, unidad, ciudad, región y código postal, aplica correcciones para errores tipográficos comunes y abreviaturas no estándar, y devuelve la dirección estandarizada según el formato postal convencional de su país. Cuando la entrada es ambigua o incompleta, el resultado lo refleja en lugar de adivinar en silencio, para que los sistemas posteriores decidan si aceptarla, marcarla o pedir aclaración.
Un poco de contexto sobre por qué los formatos de dirección varían tanto
Las convenciones de direccionamiento postal se desarrollaron de forma independiente en cada país, moldeadas por cómo evolucionaron localmente los sistemas de correo y la numeración municipal, y por eso un formato que se lee natural en un país resulta extraño en otro: el orden de unidad antes o después de la calle, la ubicación del código postal, e incluso si se espera o no un campo de región o estado, difieren según el país. Una capa de validación que entiende estas convenciones en lugar de aplicar una sola plantilla rígida es lo que hace útil la estandarización con una base de clientes internacional, y no solo una nacional.
Cómo encaja en flujos de pago, CRM o envíos
Como la tarea corre de forma asíncrona, la mayoría de las integraciones la llaman justo después de que un usuario envía una dirección al pagar o registrarse, usando el resultado estandarizado tanto para confirmar el pedido como para guardar un registro más limpio de ahí en adelante; el resultado llega por webhook firmado, o mediante un enlace firmado válido por 24 horas si su flujo prefiere consultarlo. A $0.003 por solicitud más $0.0135 por ítem validado, escala de forma natural desde una sola llamada en un pago hasta una limpieza masiva de una tabla de clientes heredada completa, y las validaciones fallidas nunca se cobran.
Qué valida, y qué deliberadamente no afirma
Este endpoint valida estructura y formato frente a las convenciones postales; no afirma confirmar que una unidad específica está actualmente habitada ni que un negocio sigue operando en esa dirección, lo cual es un tipo de verificación completamente distinto. Trátelo como una herramienta que hace que una dirección sea correcta y tenga forma de dirección entregable, no como una garantía de quién o qué está físicamente ahí hoy.
Qué puede hacer con ella
Confirmación de dirección en el pago
Valida y estandariza la dirección de envío en el momento en que el cliente la ingresa, detectando un número de unidad faltante antes de que el pedido salga hacia la puerta equivocada.
Limpieza de bases de clientes heredadas
Ejecuta una pasada masiva sobre años de direcciones acumuladas en texto libre para estandarizar el formato y detectar registros demasiado incompletos como para enviar con confianza.
Facturación y registros de cumplimiento
Estandariza las direcciones de facturación según las convenciones postales para que las facturas y documentos fiscales lleven una dirección con formato consistente y entregable.
Formularios de registro multipaís
Analiza direcciones enviadas desde distintos países y las estructura con el orden de campos correcto para cada uno, en vez de forzar un único diseño de formulario rígido.
Preguntas frecuentes
¿La API de validar direcciones postales es gratuita?
No hay capa gratuita: las capas gratis se abusan y ralentizan a todos. El acceso funciona con un saldo prepago de ForHosting KIT: se recarga desde $10.00 (no caduca) y cada solicitud se cobra a su precio publicado, así que una llamada sin saldo devuelve HTTP 402. Sin suscripción, sin tokens ni créditos inventados, y una tarea fallida no se cobra.
¿Cómo se cobra la validación de direcciones?
$0.003 por solicitud más $0.0135 por cada ítem de dirección validado, cobrado solo cuando la tarea se completa con éxito.
¿Puede validar direcciones en lote?
Sí, envíe un lote como varios ítems dentro de una solicitud o realice múltiples solicitudes; el precio por ítem está pensado justamente para limpiar grandes conjuntos de direcciones existentes.
¿Funciona con direcciones internacionales?
Sí, la tarea aplica las convenciones de formato postal correspondientes al país de la dirección en lugar de una sola plantilla fija.
¿Confirma que alguien realmente vive en esa dirección?
No, valida la estructura y el formato postal, no la ocupación actual; eso es un tipo de comprobación completamente distinto.
¿Qué pasa con una dirección incompleta o ambigua?
El resultado refleja esa ambigüedad en lugar de adivinar en silencio, para que pueda decidir si la marca, pide aclaración o la acepta tal cual.
¿Cómo recibo el resultado validado?
Por webhook firmado, recomendado para flujos de pago y registro, o mediante un enlace firmado válido por 24 horas si prefiere consultarlo.
¿Se conservan mis datos de dirección después de validarlos?
No, los datos de dirección enviados se eliminan al vencer el periodo de retención y nunca se usan para entrenar modelos.
Para desarrolladores — acceso por API
Todo lo de esta página está disponible por programación. Esta sección es para equipos que quieren integrarlo en sus sistemas; el resto puede usar la herramienta de arriba sin más.
Endpoint de API
¿Prefiere automatizarlo? Un POST autenticado crea la tarea; el resultado llega por webhook o enlace firmado. La misma capacidad también se ejecuta aquí en la web, y pronto desde nuestra app, el email y Telegram.
Llámela desde su stack
curl -X POST https://api.kit.forhosting.com/verify/address \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"items":["valor-1","valor-2"]}'const res = await fetch("https://api.kit.forhosting.com/verify/address", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"items": [
"valor-1",
"valor-2"
]
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/verify/address",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"items": [
"valor-1",
"valor-2"
]
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/verify/address", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"items":["valor-1","valor-2"]}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"items":["valor-1","valor-2"]}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/verify/address", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Ejemplo de solicitud
{
"items": [
"valor-1",
"valor-2"
]
}Ejemplo de respuesta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "verify.address",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}La API es asíncrona: la llamada devuelve un task_id al instante y el resultado llega por webhook. El polling está limitado a 1 req/s por tarea.
Precio
Precio publicado — sin tokens ni créditos inventados. Una tarea fallida no se cobra.
Errores
| HTTP | Código | Significado |
|---|---|---|
401 | unauthorized | API key ausente o inválida. |
402 | insufficient_balance | El saldo no cubre el precio de la tarea. |
404 | unknown_type | El tipo de tarea no existe. |
429 | rate_limited | Demasiadas peticiones. Use el webhook en vez de sondear. |
422 | task_failed | La tarea falló tras 3 reintentos. No se cobra. |