AppFolio — Órdenes de Trabajo y Mantenimiento
Resumen
Gestiona el ciclo de vida completo de las órdenes de trabajo de mantenimiento a través de la API Stack de AppFolio.
Utilice este flujo de trabajo cuando los inquilinos envíen solicitudes de mantenimiento, cuando necesite asignar
proveedores a órdenes de trabajo abiertas, rastrear el progreso de las reparaciones en todas las propiedades o cerrar
trabajos completados con registros de costos. Este es el flujo de trabajo secundario — para paneles de propiedades
y arrendamientos, consulte appfolio-core-workflow-a.
Requisitos previos
- Un contrato de AppFolio verificado y un portafolio sandbox con registros sintéticos de propiedad, unidad, proveedor y orden de trabajo; no pruebe la automatización de mantenimiento contra una unidad de producción ocupada.
- Una identidad de servicio con privilegios mínimos, soporte de idempotencia para acciones de creación/cierre, y una ruta de escalación aprobada para mantenimiento crítico de seguridad.
- Una política de minimización de datos: almacene y transmita solo los hechos de mantenimiento necesarios para realizar el trabajo, nunca preferencias de inquilinos, códigos de acceso o información detallada de ocupación en notas o registros genéricos de proveedores.
Instrucciones
Paso 1: Crear una Orden de Trabajo a partir de una Solicitud de Mantenimiento
const workOrder = await client.workOrders.create({
property_id: 'prop_4821',
unit_id: 'unit_12B',
category: 'plumbing',
priority: 'high',
description: 'Synthetic plumbing fixture leak reported in sandbox unit',
requested_by: 'tenant_8934',
due_date: '2026-04-10',
});
console.log(`Work order ${workOrder.id} created — status: ${workOrder.status}`);
Paso 2: Asignar un Proveedor
const assignment = await client.workOrders.assign(workOrder.id, {
vendor_id: 'vendor_plumb_01',
scheduled_date: '2026-04-08',
time_window: '09:00-12:00',
notes: 'Confirm scheduled appointment through the approved work-order channel.',
});
console.log(`Assigned to ${assignment.vendor_name} on ${assignment.scheduled_date}`);
Paso 3: Rastrear el Estado de la Orden de Trabajo
const open = await client.workOrders.list({
property_id: 'prop_4821',
status: ['open', 'in_progress', 'scheduled'],
sort: 'priority_desc',
});
open.items.forEach(wo =>
console.log(`#${wo.id} [${wo.priority}] ${wo.category} — ${wo.status} (due ${wo.due_date})`)
);
Paso 4: Cerrar la Orden de Trabajo con Registro de Costos
const closed = await client.workOrders.close(workOrder.id, {
resolution: 'Replaced P-trap and tightened supply line. No further leaks.',
labor_cost: 175.00,
materials_cost: 42.50,
completed_date: '2026-04-08',
attachments: ['receipt_plumb_0408.pdf'],
});
console.log(`Closed #${closed.id} — total cost: $${closed.total_cost}`);
Manejo de Errores
| Problema | Causa | Solución |
|---|---|---|
401 Unauthorized | Credenciales de API caducadas o inválidas | Actualice client_id/secret en el panel de Stack |
404 Work Order Not Found | ID de orden de trabajo incorrecto o ya eliminado | Verifique el ID con workOrders.list() |
422 Missing required fields | Categoría o property_id omitidos | Incluya todos los campos requeridos según el esquema |
409 Conflict | La orden de trabajo ya está cerrada | Verifique el estado antes de intentar cerrar |
429 Rate Limited | Superó las 120 solicitudes/minuto | Agregue retroceso exponencial con un retraso base de 1s |
Salida
Una ejecución exitosa crea una orden de trabajo, la asigna a un proveedor con una ventana de servicio programada y la cierra con registros de costos y notas de resolución. El administrador de la propiedad obtiene un registro de auditoría completo desde la solicitud hasta la finalización.
Ejemplos
Para un flujo de trabajo de plomería sandbox, cree una orden de trabajo sintética con una clave de idempotencia estable, asigne un proveedor sandbox y lea su estado antes de cualquier transición. Adjunte solo un recibo de prueba no sensible, luego cierre la orden una vez y verifique el total y el registro de auditoría sin registrar detalles del inquilino o de acceso. Repita la misma solicitud para demostrar que se rechazan las órdenes de trabajo duplicadas y los registros de costos duplicados. Si la asignación del proveedor, la clasificación de seguridad, el estado anterior o el resultado del cierre es incierto, deje la orden abierta y enrútela al operador de la propiedad autorizado para su revisión.
Recursos
Próximos Pasos
Consulte appfolio-sdk-patterns para la configuración de autenticación y los ayudantes de paginación.