AppFolio — Gestion des propriétés et des locataires
Présentation
Workflow principal pour l'intégration de la gestion immobilière AppFolio. Couvre l'ensemble du cycle de vie d'une propriété : création et mise à jour des fiches, gestion des profils locataires et des contrats de location, et interrogation des données d'occupation. Utilise l'API Stack d'AppFolio avec OAuth 2.0 (client credentials) pour un accès de serveur à serveur. Tous les endpoints renvoient du JSON et prennent en charge la pagination via le paramètre cursor pour les grands portefeuilles.
Prérequis
- Un contrat partenaire/API AppFolio en cours qui confirme l'URL de base du portefeuille attribué, la méthode d'authentification, les portées approuvées et les capacités d'écriture ; ne pas les déduire d'un tutoriel ou d'un autre portefeuille.
- Un bac à sable séparé avec des propriétés, unités et enregistrements de locataires synthétiques, ainsi qu'un propriétaire d'identifiants et un budget de requêtes approuvé.
- Des clés d'idempotence et un processus de rollback/réconciliation approuvé par l'opérateur pour les écritures sur les propriétés, locataires et baux, qui peuvent avoir des conséquences juridiques et de facturation réelles.
Instructions
- Confirmer l'URL de base et le flux d'authentification fournis par le prestataire pour le portefeuille cible avant de copier une configuration client dans un environnement.
- N'utiliser le chemin de création/mise à jour qu'avec des fixtures synthétiques du bac à sable et des clés d'idempotence ; récupérer les enregistrements canoniques avant de réessayer une écriture incertaine.
- Valider la propriété, les dates de bail et la disponibilité des unités avant de créer un bail, et n'émettre que les identifiants d'enregistrement et les preuves de statut expurgées.
- Ne promouvoir un flux capable d'écriture qu'après une répétition en conditions réelles prouvant le rollback, la réconciliation et la limite de portée la moins privilégiée.
Étape 1 : Authentification et initialisation du client
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' };
Étape 2 : Créer ou mettre à jour une propriété
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(`Propriété créée : ${property.id}`);
Étape 3 : Ajouter un locataire et un bail
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());
Étape 4 : Interroger l'occupation
const units = await fetch(
`https://api.appfolio.com/v1/properties/${property.id}/units?status=vacant`,
{ headers },
).then(r => r.json());
console.log(`Unités vacantes : ${units.data.length} sur ${units.meta.total}`);
Gestion des erreurs
| Problème | Cause | Correctif |
|---|---|---|
401 Unauthorized | Jeton expiré ou invalide | Réauthentifier avec les identifiants client |
404 Not Found | Mauvais ID de propriété/locataire | Vérifier que l'ID existe avant de l'utiliser |
422 Unprocessable | Champs obligatoires manquants | Vérifier le tableau errors[] dans le corps de la réponse |
409 Conflict | Bail en double pour l'unité | Interroger les baux existants avant de créer |
429 Too Many Requests | Limite de débit dépassée | Attendre en utilisant l'en-tête Retry-After |
Résultat
Une exécution réussie crée une propriété avec des unités, ajoute un locataire, les lie via un bail, et rapporte le nombre de vacances. La sortie console confirme chaque ID de ressource à la création.
Exemples
Pour une modification de bail, exécuter contre une unité de bac à sable synthétique nommée et un locataire avec une clé d'idempotence stable. Lire la propriété et les baux actuels, effectuer l'écriture candidate une fois, puis relire le bail résultant et n'enregistrer que les ID, les dates et le statut de réconciliation. Réexécuter la même requête pour prouver qu'elle ne crée pas un second bail. Si le contrat fournisseur, l'endpoint, l'autorisation ou le résultat d'une écriture antérieure ne peut pas être vérifié, arrêter avant toute écriture et transmettre le cas à l'opérateur du portefeuille pour réconciliation.
Ressources
Prochaines étapes
Continuer avec appfolio-core-workflow-b pour les demandes d'entretien et le suivi des paiements.