Urbaneta ya tiene una API pública: esto es lo que puedes hacer con ella
Hace unas semanas, un gestor de propiedades me preguntó algo que se me quedó grabado. "Usamos Urbaneta para nuestros edificios, pero nuestro software de contabilidad es personalizado. ¿Podemos extraer los datos de las facturas automáticamente en lugar de exportar CSVs cada mes?"
Mi respuesta entonces fue "todavía no". Mi respuesta hoy es diferente.
Urbaneta ya tiene una API pública. Está activa, documentada y lista para integraciones. Si eres desarrollador, una empresa de gestión de propiedades con equipo técnico propio o simplemente alguien que quiere dejar de copiar datos entre sistemas, esto es para ti.
Qué se ha lanzado realmente
Tres cosas salieron a la luz juntas, y funcionan como un conjunto:
- Documentación de la API — una referencia pública en
/api-docsque te indica exactamente qué endpoints existen, qué aceptan y qué devuelven. - Claves de API — tokens con permisos específicos que generas en tu panel de administración para autenticar solicitudes.
- Webhooks — notificaciones en tiempo real que envían eventos a tu propio servidor en lugar de obligarte a consultar cambios periódicamente.
Vamos a repasar cada una.
Documentación de la API: el mapa
Lo primero que necesitas al construir contra cualquier API es una documentación clara. Hemos puesto la nuestra en /api-docs en el dominio principal de Urbaneta. No se requiere iniciar sesión: es pública.
Cubre:
- Autenticación: Cómo incluir tu clave de API en el encabezado
Authorization: Bearer. - Edificios, apartamentos y residentes: Operaciones CRUD para las entidades principales.
- Facturas y lecturas de contadores: Los datos que realmente importan a los gestores de propiedades.
- Suscripción a webhooks: Cómo registrar y gestionar endpoints de webhooks.
- Códigos de error: Qué significan
400,401,403y429en la práctica, además del comportamiento de limitación de velocidad.
La documentación se genera a partir del código fuente real de la API, por lo que no se queda desactualizada. Si un endpoint cambia, la documentación se actualiza con él.
Claves de API: con permisos específicos, no omnipotentes
Hay algo en lo que insistí durante el diseño: las claves de API deben tener permisos específicos. No deberías entregar a una integración de terceros una clave que pueda eliminar edificios solo porque necesita leer datos de facturas.
En tu panel de administración, en Integraciones → Claves de API, puedes crear claves con permisos específicos:
read:buildings— listar edificios y apartamentosread:invoices— obtener datos de facturaswrite:invoices— crear o actualizar facturasread:residents— acceso al directorio de residenteswebhooks:manage— suscribirse y gestionar endpoints de webhooks
Puedes crear múltiples claves para diferentes integraciones. Si la clave de un proveedor se filtra, revocas solo esa. No hay necesidad de rotar todo.
Las claves tienen el prefijo nmv_ para que sean fáciles de identificar en los registros y en las revisiones de código. Usan hashing SHA-256 de nuestro lado, por lo que incluso una brecha en la base de datos no expone los tokens reales.
Webhooks: deja de consultar, empieza a reaccionar
Esta es la que personalmente más me entusiasma. Consultar periódicamente es un desperdicio. Si compruebas cada 5 minutos si se creó una nueva factura, estás haciendo 288 solicitudes al día para datos que quizás cambiaron dos veces.
Con los webhooks, Urbaneta envía eventos a tu URL a medida que ocurren:
invoice.createdinvoice.paidresident.invitedmaintenance_request.updatedmeter_reading.submitted
Te suscribes a los eventos que te interesan en Integraciones → Webhooks. Urbaneta envía una solicitud POST a tu endpoint con una carga útil firmada. Verificas la firma, procesas el evento y listo.
Incluimos un mecanismo de reintento: si tu endpoint devuelve un estado que no es 2xx o se agota el tiempo de espera, reintentamos con retroceso exponencial durante hasta 24 horas. La entrega es al menos una vez, por lo que tu endpoint debe ser idempotente. También incluimos un encabezado X-Urbaneta-Event-ID para que puedas deduplicar si es necesario.
Un ejemplo práctico
Digamos que diriges una empresa de gestión de propiedades con una docena de edificios. Quieres:
- Extraer todas las facturas creadas este mes en tu sistema de contabilidad.
- Marcar una factura como pagada cuando se acredite la transferencia bancaria.
- Notificar a tu equipo de mantenimiento cuando un residente envíe una foto de lectura de contador.
Antes de la API, esto era exportaciones manuales de CSV, coincidencias en hojas de cálculo y llamadas telefónicas. Ahora es:
- Un trabajo cron que llama a
GET /api/v1/invoices?created_after=2026-07-01una vez al día. - Un manejador de webhooks para
invoice.paidque actualiza tu libro mayor automáticamente. - Un manejador de webhooks para
meter_reading.submittedque publica en tu canal interno de Slack.
La integración completa podría llevar a un desarrollador uno o dos días. El ahorro de tiempo comienza de inmediato.
Qué significa esto para los gestores de propiedades
Si no eres desarrollador, podrías estar pensando: "esto está bien, pero yo no escribo código". Es justo. He aquí por qué sigue siendo importante:
Tus proveedores pueden integrarse. Si usas una herramienta de contabilidad, una plataforma de mantenimiento o una aplicación de comunicación con residentes, puedes pedirles que construyan una integración con Urbaneta. La API y los webhooks les dan todo lo que necesitan. Obtienes sincronización automática de datos sin tocar una sola línea de código.
Los portales de marca blanca se mantienen independientes. Las claves de API tienen permisos específicos por inquilino. Si gestionas un portal de gestión de propiedades de marca blanca bajo tu propio dominio, tus claves de API solo ven tus datos. No hay filtración entre inquilinos.
Qué viene después
La API actual cubre los flujos principales de gestión de propiedades: edificios, residentes, facturas, lecturas de contadores, mantenimiento y pagos. La estamos ampliando según lo que realmente solicitan los integradores.
Si estás construyendo algo y necesitas un endpoint que aún no existe, avísanos. La API está diseñada para crecer: preferimos lanzar una superficie pequeña y sólida y añadirle cosas que construir una especificación masiva que nadie use.
Cómo empezar
- Abre
/api-docsen tu navegador. Lee la sección de autenticación. - Ve a tu panel de administración → Integraciones → Claves de API y crea una clave de prueba.
- Haz tu primera solicitud:
GET /api/v1/buildingscon tu clave en el encabezado. - Si necesitas eventos en tiempo real, dirígete a Integraciones → Webhooks y registra tu endpoint.
La documentación incluye ejemplos de curl listos para copiar y pegar para cada endpoint. No necesitas adivinar la forma de la carga útil.
Hace un año, alguien me dijo que el software de gestión de propiedades debería "simplemente funcionar" sin integraciones. Solía creer eso. Ahora pienso lo contrario: la mejor plataforma de gestión de propiedades es la que se conecta con todo lo demás que ya usas.
Eso es lo que estamos construyendo.