API pública, webhooks y MCP en Adminia Manager: conectá tu administración con cualquier sistema

Una de las preguntas más frecuentes que recibimos de estudios contables, ERPs verticales e integradores es: '¿Cómo me conecto con Adminia Manager para no tener que copiar datos a mano?'. La respuesta, desde hoy, tiene tres formas oficiales: una API REST pública, webhooks salientes firmados y un servidor MCP para asistentes IA como ChatGPT y Claude.

Las tres conviven en la misma capa de seguridad: API keys por organización, scopes granulares, Row Level Security en Postgres y auditoría completa. En este artículo te contamos qué se puede consultar hoy, cómo se asegura cada vía y qué casos reales habilita en una administración de consorcios.

Por qué importa que tu plataforma tenga API

Una administración moderna no vive aislada. El contador necesita los gastos del mes en su sistema. La inmobiliaria quiere mostrar el saldo del propietario dentro de su propio portal. La consultora arma dashboards en Power BI con la cobranza. El administrador quiere preguntarle a ChatGPT 'mostrame las unidades con más de 90 días de deuda' sin abrir la app.

Sin API, todo eso se resuelve con planillas exportadas a mano, capturas de pantalla y errores de transcripción. Con API, todo eso pasa solo. Por eso decidimos que la integración con terceros tenía que ser ciudadana de primera clase dentro de Adminia Manager, no un parche.

Vía 1 — REST API v1 (lectura)

Es el camino más universal: cualquier lenguaje, cualquier sistema, una llamada HTTP con un header de autenticación. La Fase 1 expone endpoints de lectura sobre los datos operativos más pedidos:

• GET /v1/me — datos de la organización y scopes habilitados de tu API key.
• GET /v1/buildings — listado de edificios de la organización.
• GET /v1/buildings/{id}/units — unidades, coeficientes, propietarios y residentes.
• GET /v1/buildings/{id}/expenses — gastos del edificio, filtrables por período.
• GET /v1/buildings/{id}/income — cobros registrados.
• GET /v1/buildings/{id}/liquidations — liquidaciones publicadas al portal.
• GET /v1/buildings/{id}/units/{unitId}/ledger — libro mayor (debito/credito) de una unidad.
• GET /v1/buildings/{id}/incidents — incidencias del edificio.

Cada llamada requiere una API key generada desde Configuración → Integraciones. La key se muestra una sola vez y en la base se guarda únicamente su hash SHA-256, por lo que ni el equipo de Adminia puede recuperarla. Cada key tiene scopes granulares (buildings:read, expenses:read, ledger:read, etc.), expiración opcional y límite de uso (100 req/min, 10 mil/día por defecto). Si lo excedés, la API responde 429 con un Retry-After.

Vía 2 — Webhooks salientes (push en tiempo real)

La API resuelve el caso 'dame los datos cuando los pido'. Los webhooks resuelven el opuesto: 'avisame cuando pase algo'. Adminia te notifica con un POST HTTPS los eventos clave:

• liquidation.published — se publicó una liquidación al portal.
• payment.received — se registró un cobro y emitió recibo.
• expense.created — se cargó un gasto del edificio.
• incident.created — se creó una incidencia.

Cada evento llega con un event_id único para deduplicar, un timestamp y una firma HMAC-SHA256 en el header X-Adminia-Signature. Validar la firma es obligatorio: garantiza que el payload viene realmente de Adminia y no fue alterado en el camino. El sistema reintenta con backoff exponencial (1 min, 5 min, 30 min, 2 h, 12 h, 24 h) y bloquea destinos a IPs privadas para evitar SSRF.

El panel de entregas muestra cada intento con su status code, body de respuesta y botón para reenviar manualmente. Esto vuelve el debugging trivial: cuando algo no llega, se ve por qué.

Vía 3 — Servidor MCP (Model Context Protocol)

MCP es el estándar abierto que están adoptando ChatGPT, Claude, Cursor y los agentes IA en general para conectarse con herramientas externas. Adminia expone un servidor MCP compatible con streamable-http, lo que permite que cualquier asistente IA consulte datos en vivo del consorcio.

Tools expuestas hoy: list_buildings, list_units, get_unit_debt, list_expenses, list_liquidations. Todas usan la misma API key y los mismos scopes que la REST, y todas son de solo lectura — las operaciones destructivas se hacen siempre desde la UI o la API REST con scopes explícitos.

Configurar Claude Desktop o un GPT custom toma 30 segundos: apuntás al endpoint, ponés el header Authorization y listo. A partir de ahí podés preguntarle en castellano: '¿Cuál es la deuda total del edificio Lavalle 1234?' y la IA llama al MCP, recibe los datos y te los devuelve formateados.

Casos de uso reales en una administración

• Estudio contable: descarga nocturna de gastos y cobros del mes para conciliar contra el sistema contable.
• Inmobiliaria que administra alquileres: muestra dentro de su portal el saldo de expensas del propietario tomado en vivo de Adminia.
• Consultora: dashboards en Looker o Power BI con morosidad, evolución de gastos y cobranza por edificio.
• n8n / Zapier: cuando se publica una liquidación → mandar email al contador + crear tarea en Trello + postear en Slack.
• Cobranza judicial: leer el estado de deuda y los comprobantes oficiales para iniciar gestión contra deudores.
• Agentes IA: 'Claude, decime qué edificios tienen morosidad arriba del 30%' — el agente combina datos de Adminia, AFIP y Mercado Pago en una sola respuesta.
• Apps de pago propias: consultar deuda en vivo, generar QR y registrar el pago de vuelta vía webhook (escritura en Fase 2).

Seguridad: lo que no se ve

Una API mal pensada es una puerta abierta. Por eso la integración pública de Adminia se construyó con foco obsesivo en seguridad, no como afterthought.

• API keys con hash SHA-256: la clave plana nunca se guarda en base.
• Scopes granulares por recurso, nunca permisos totales.
• RLS en Postgres: la edge function deriva el organization_id de la key; jamás se confía en un id que venga en el body.
• Rate limiting por key (100/min, 10k/día) con respuesta 429 + Retry-After.
• Auditoría completa: cada request queda en api_audit_log con key, endpoint, status, IP, user agent.
• Webhooks firmados con HMAC-SHA256 + timestamp anti-replay (ventana 5 minutos).
• SSRF guard: rechazo de URLs a localhost, redes privadas e IPs internas.
• Versionado /v1: breaking changes pasarán a /v2 con 6 meses de deprecation.
• Rotación con dos keys activas en simultáneo, sin downtime.

Qué viene en Fase 2

La Fase 1 cubre la pregunta '¿qué pasó?' (lectura) y la pregunta '¿avisame cuándo pase?' (webhooks). La Fase 2 va a cubrir '¿hacelo por mí?' con endpoints de escritura: crear gasto, registrar cobro, generar libre deuda, abrir incidencia. Todo con scopes *:write separados, validados y auditados.

También vienen plantillas oficiales de n8n y Zapier, un cliente TypeScript autogenerado a partir del OpenAPI 3.1 y más tools MCP para que el ecosistema de agentes IA crezca sobre Adminia.

Cómo empezar hoy

Si administrás consorcios con Adminia Manager: andá a Configuración → Integraciones, generá una API key con los scopes que necesites y compartila con tu contador, tu integrador o tu equipo de BI. La documentación completa con ejemplos cURL, formato de webhooks y guía MCP está en docs/integraciones-api-webhooks-mcp.md dentro de tu workspace.

Si sos desarrollador y querés integrar tu sistema con Adminia Manager: escribinos a soporte@adminiamanager.com con tu caso de uso y te mandamos una key de sandbox para empezar.

Preguntas frecuentes