AppFolio — Gestión de Propiedades e Inquilinos
Resumen
Flujo de trabajo principal para la integración de gestión de propiedades con AppFolio. Cubre el ciclo de vida completo de una propiedad: crear y actualizar registros de propiedades, gestionar perfiles de inquilinos y contratos de arrendamiento, y consultar datos de ocupación. Utiliza la API Stack de AppFolio con credenciales de cliente OAuth 2.0 para acceso servidor a servidor. Todos los endpoints devuelven JSON y admiten paginación mediante parámetros cursor para carteras grandes.
Requisitos previos
- Un contrato actual de socio/API de AppFolio que confirme la URL base de la cartera asignada, el método de autenticación, los alcances aprobados y las capacidades de escritura; no inferir estos datos de un tutorial o de otra cartera.
- Un sandbox separado con propiedades, unidades y registros sintéticos de inquilinos, además de un propietario de credenciales y un presupuesto de solicitudes aprobado.
- Claves de idempotencia y un proceso de reversión/reconciliación aprobado por el operador para escrituras de propiedades, inquilinos y arrendamientos, que pueden tener consecuencias legales y de facturación reales.
Instrucciones
- Confirmar la URL base y el flujo de autenticación proporcionados por el proveedor para la cartera objetivo antes de copiar cualquier configuración de cliente en un entorno.
- Ejecutar la ruta de creación/actualización solo con datos sintéticos del sandbox y claves de idempotencia; recuperar registros canónicos antes de reintentar una escritura incierta.
- Validar la propiedad, las fechas del arrendamiento y la disponibilidad de la unidad antes de crear un arrendamiento, y emitir solo identificadores de registro y evidencia de estado resumida.
- Promover un flujo con capacidad de escritura solo después de que un ensayo por etapas demuestre la reversión, la reconciliación y el límite de alcance de menor privilegio.
Paso 1: Autenticar e Inicializar Cliente
const token = await fetch('https://api.appfolio.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.APPFOLIO_CLIENT_ID!,
client_secret: process.env.APPFOLIO_CLIENT_SECRET!,
scope: 'properties tenants leases',
}),
}).then(r => r.json());
const headers = { Authorization: `Bearer ${token.access_token}`, 'Content-Type': 'application/json' };
Paso 2: Crear o Actualizar una Propiedad
const property = await fetch('https://api.appfolio.com/v1/properties', {
method: 'POST', headers,
body: JSON.stringify({
name: 'Sunrise Apartments',
address: { street: '100 Main St', city: 'Austin', state: 'TX', zip: '78701' },
type: 'residential',
units: [
{ number: '101', bedrooms: 2, bathrooms: 1, rent: 1450 },
{ number: '102', bedrooms: 1, bathrooms: 1, rent: 1100 },
],
}),
}).then(r => r.json());
console.log(`Property created: ${property.id}`);
Paso 3: Agregar un Inquilino y un Arrendamiento
const tenant = await fetch('https://api.appfolio.com/v1/tenants', {
method: 'POST', headers,
body: JSON.stringify({
first_name: 'Test', last_name: 'Tenant',
email: '[email protected]', phone: '555-0100',
}),
}).then(r => r.json());
await fetch('https://api.appfolio.com/v1/leases', {
method: 'POST', headers,
body: JSON.stringify({
property_id: property.id, unit_number: '101',
tenant_id: tenant.id, start_date: '2026-05-01', end_date: '2027-04-30',
monthly_rent: 1450, security_deposit: 1450,
}),
}).then(r => r.json());
Paso 4: Consultar Ocupación
const units = await fetch(
`https://api.appfolio.com/v1/properties/${property.id}/units?status=vacant`,
{ headers },
).then(r => r.json());
console.log(`Vacant units: ${units.data.length} of ${units.meta.total}`);
Manejo de Errores
| Problema | Causa | Solución |
|---|---|---|
401 Unauthorized | Token expirado o inválido | Reautenticar con credenciales de cliente |
404 Not Found | ID de propiedad/inquilino incorrecto | Verificar que el ID del recurso exista antes de referenciarlo |
422 Unprocessable | Faltan campos requeridos | Revisar el arreglo errors[] en el cuerpo de la respuesta |
409 Conflict | Arrendamiento duplicado para la unidad | Consultar arrendamientos existentes antes de crear |
429 Too Many Requests | Límite de tasa excedido | Retroceder usando el valor del encabezado Retry-After |
Salida
Una ejecución exitosa crea una propiedad con unidades, agrega un inquilino, los vincula mediante un arrendamiento y reporta los conteos de vacantes. La salida de consola confirma cada ID de recurso en la creación.
Ejemplos
Para un cambio de creación de arrendamiento, ejecutar contra una unidad y un inquilino sintéticos con nombre en un sandbox, utilizando una clave de idempotencia estable. Leer la propiedad y los arrendamientos actuales, realizar la escritura candidata una vez, luego leer el arrendamiento resultante y registrar solo IDs, fechas y el estado de reconciliación. Re-ejecutar la misma solicitud para comprobar que no crea un segundo arrendamiento. Si no se puede verificar el contrato del proveedor, el endpoint, la autorización o el resultado de la escritura anterior, detenerse antes de cualquier escritura y enviar el caso al operador de la cartera para reconciliación.
Recursos
Próximos Pasos
Continuar con appfolio-core-workflow-b para solicitudes de mantenimiento y seguimiento de pagos.