Idioma

Tema

Blog/9 min de lectura

Urbaneta ya tiene una API pública: esto es lo que puedes hacer con ella

Urbaneta Team

1 July 2026

Urbaneta ya tiene una API pública: esto es lo que puedes hacer con ella

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:

  1. Documentación de la API — una referencia pública en /api-docs que te indica exactamente qué endpoints existen, qué aceptan y qué devuelven.
  2. Claves de API — tokens con permisos específicos que generas en tu panel de administración para autenticar solicitudes.
  3. 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, 403 y 429 en 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 apartamentos
  • read:invoices — obtener datos de facturas
  • write:invoices — crear o actualizar facturas
  • read:residents — acceso al directorio de residentes
  • webhooks: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.created
  • invoice.paid
  • resident.invited
  • maintenance_request.updated
  • meter_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:

  1. Extraer todas las facturas creadas este mes en tu sistema de contabilidad.
  2. Marcar una factura como pagada cuando se acredite la transferencia bancaria.
  3. 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-01 una vez al día.
  • Un manejador de webhooks para invoice.paid que actualiza tu libro mayor automáticamente.
  • Un manejador de webhooks para meter_reading.submitted que 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

  1. Abre /api-docs en tu navegador. Lee la sección de autenticación.
  2. Ve a tu panel de administración → Integraciones → Claves de API y crea una clave de prueba.
  3. Haz tu primera solicitud: GET /api/v1/buildings con tu clave en el encabezado.
  4. 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.

Artículos relacionados