AppFolio — Ordres de travail & Maintenance
Vue d'ensemble
Gérez le cycle de vie complet des ordres de travail de maintenance via l'API Stack d'AppFolio.
Utilisez ce workflow lorsque les locataires soumettent des demandes de maintenance, lorsque vous devez affecter
prestataires à des ordres de travail ouverts, suivre l'avancement des réparations sur plusieurs propriétés, ou clôturer
des jobs terminés avec enregistrement des coûts. Il s'agit du workflow secondaire — pour les tableaux de bord de propriété
et la location, voir appfolio-core-workflow-a.
Prérequis
- Un contrat AppFolio vérifié et un portfolio sandbox avec des enregistrements synthétiques de propriété, d'unité, de prestataire et d'ordre de travail ; ne testez pas l'automatisation de la maintenance sur une unité de production occupée.
- Une identité de service à privilèges minimaux, un support d'idempotence pour les actions de création/clôture, et un chemin d'escalade approuvé pour la maintenance critique.
- Une politique de minimisation des données : stockez et transmettez uniquement les faits de maintenance nécessaires pour effectuer le travail, jamais les préférences des locataires, les codes d'accès, ou les informations détaillées d'occupation dans les notes ou journaux génériques des prestataires.
Instructions
Étape 1 : Créer un ordre de travail à partir d'une demande de maintenance
const workOrder = await client.workOrders.create({
property_id: 'prop_4821',
unit_id: 'unit_12B',
category: 'plumbing',
priority: 'high',
description: 'Fuite de plomberie synthétique signalée dans l\'unité sandbox',
requested_by: 'tenant_8934',
due_date: '2026-04-10',
});
console.log(`Ordre de travail ${workOrder.id} créé — statut: ${workOrder.status}`);
Étape 2 : Affecter un prestataire
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: 'Confirmez le rendez-vous programmé via le canal d\'ordre de travail approuvé.',
});
console.log(`Affecté à ${assignment.vendor_name} le ${assignment.scheduled_date}`);
Étape 3 : Suivre le statut de l'ordre de travail
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} (échéance ${wo.due_date})`)
);
Étape 4 : Clôturer l'ordre de travail avec enregistrement des coûts
const closed = await client.workOrders.close(workOrder.id, {
resolution: 'Remplacement du siphon et serrage de la conduite d\'alimentation. Plus de fuites.',
labor_cost: 175.00,
materials_cost: 42.50,
completed_date: '2026-04-08',
attachments: ['receipt_plumb_0408.pdf'],
});
console.log(`Clôturé #${closed.id} — coût total: $${closed.total_cost}`);
Gestion des erreurs
| Problème | Cause | Correctif |
|---|---|---|
401 Non autorisé | Identifiants API expirés ou invalides | Rafraîchir client_id/secret dans le tableau de bord Stack |
404 Ordre de travail non trouvé | Mauvais ID d'ordre de travail ou déjà supprimé | Vérifier l'ID avec workOrders.list() |
422 Champs obligatoires manquants | Catégorie ou property_id omis | Inclure tous les champs obligatoires selon le schéma |
409 Conflit | Ordre de travail déjà clôturé | Vérifier le statut avant de tenter la clôture |
429 Limite de débit atteinte | Dépassement de 120 requêtes/minute | Ajouter un backoff exponentiel avec délai de base de 1s |
Résultat
Un exécution réussie crée un ordre de travail, l'affecte à un prestataire avec une fenêtre de service programmée, et le clôture avec des enregistrements de coûts et des notes de résolution. Le gestionnaire de propriété dispose d'une piste d'audit complète, de la demande à la réalisation.
Exemples
Pour un workflow de plomberie sandbox, créez un ordre de travail synthétique avec une clé d'idempotence stable, affectez un prestataire sandbox, et relisez son statut avant toute transition. Joignez uniquement un reçu de test non sensible, puis clôturez l'ordre une fois et vérifiez le total et l'enregistrement d'audit sans journaliser les détails du locataire ou d'accès. Rejouez la même requête pour prouver que les doublons d'ordres de travail et de coûts sont rejetés. Si l'affectation du prestataire, la classification de sécurité, l'état antérieur, ou le résultat de la clôture sont incertains, laissez l'ordre ouvert et acheminez-le vers l'opérateur de propriété autorisé pour examen.
Ressources
Prochaines étapes
Voir appfolio-sdk-patterns pour la configuration de l'authentification et les aides de pagination.