AppFolio — Immobilien- & Mieterverwaltung
Überblick
Primärer Workflow für die AppFolio-Immobilienverwaltungsintegration. Deckt den gesamten
Lebenszyklus einer Immobilie ab: Erstellen und Aktualisieren von Immobilieneinträgen,
Verwalten von Mieterprofilen und Mietverträgen sowie Abfragen von Belegungsdaten.
Verwendet die AppFolio Stack API mit OAuth 2.0
Client Credentials für den Server-zu-Server-Zugriff. Alle Endpunkte geben JSON zurück und unterstützen
Paginierung über cursor-Parameter für große Portfolios.
Voraussetzungen
- Ein aktueller AppFolio-Partner-/API-Vertrag, der die bestätigte Portfolio- Basis-URL, Authentifizierungsmethode, freigegebene Bereiche und Schreibfähigkeiten angibt; leiten Sie diese nicht aus einem Tutorial oder einem anderen Portfolio ab.
- Eine separate Sandbox mit austauschbaren Immobilien, Einheiten und synthetischen Mieterdatensätzen sowie einem Berechtigungsinhaber und einem genehmigten Anforderungsbudget.
- Idempotenz-Keys und ein vom Betreiber genehmigter Rollback-/Abgleichprozess für Immobilien-, Mieter- und Mietvertragsschreibvorgänge, die reale rechtliche und abrechnungstechnische Konsequenzen haben können.
Anweisungen
- Bestätigen Sie die vom Anbieter ausgestellte Basis-URL und den Authentifizierungsablauf für das Ziel- Portfolio, bevor Sie eine Client-Konfiguration in eine Umgebung kopieren.
- Führen Sie den Erstellungs-/Aktualisierungspfad nur mit synthetischen Sandbox-Fixtures und Idempotenz-Keys aus; rufen Sie kanonische Datensätze ab, bevor Sie einen unsicheren Schreibvorgang wiederholen.
- Validieren Sie Eigentumsverhältnisse, Mietvertragsdaten und Einheitenverfügbarkeit, bevor Sie einen Mietvertrag erstellen, und geben Sie nur Datensatz-IDs und einen gekürzten Statusnachweis aus.
- Stufen Sie einen schreibfähigen Ablauf erst hoch, nachdem eine gestaffelte Probe den Rollback, den Abgleich und die niedrigstmöglichen Berechtigungsgrenzen nachweist.
Schritt 1: Authentifizieren und Client initialisieren
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' };
Schritt 2: Eine Immobilie erstellen oder aktualisieren
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(`Immobilie erstellt: ${property.id}`);
Schritt 3: Mieter und Mietvertrag hinzufügen
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());
Schritt 4: Belegung abfragen
const units = await fetch(
`https://api.appfolio.com/v1/properties/${property.id}/units?status=vacant`,
{ headers },
).then(r => r.json());
console.log(`Freie Einheiten: ${units.data.length} von ${units.meta.total}`);
Fehlerbehandlung
| Problem | Ursache | Behebung |
|---|---|---|
401 Unauthorized | Abgelaufenes oder ungültiges Token | Erneut mit Client Credentials authentifizieren |
404 Not Found | Falsche Immobilien-/Mieter-ID | Überprüfen, ob die Ressourcen-ID existiert, bevor Sie darauf verweisen |
422 Unprocessable | Fehlende Pflichtfelder | errors[]-Array im Antworttext prüfen |
409 Conflict | Doppelter Mietvertrag für Einheit | Vor Erstellung vorhandene Mietverträge abfragen |
429 Too Many Requests | Ratenlimit überschritten | Mit dem Wert des Retry-After-Headers zurückhalten |
Ausgabe
Ein erfolgreicher Durchlauf erstellt eine Immobilie mit Einheiten, fügt einen Mieter hinzu, bindet sie über einen Mietvertrag und meldet Leerstandszahlen. Die Konsolenausgabe bestätigt jede Ressourcen-ID bei der Erstellung.
Beispiele
Führen Sie für eine Mietvertragserstellungsänderung den Vorgang gegen eine benannte synthetische Sandbox-Einheit und Mieter mit einem stabilen Idempotenz-Key aus. Lesen Sie die Immobilie und die aktuellen Mietverträge, führen Sie den Kandidatenschreibvorgang einmal aus, lesen Sie dann den resultierenden Mietvertrag zurück und erfassen Sie nur IDs, Daten und den Abgleichsstatus. Führen Sie dieselbe Anforderung erneut aus, um nachzuweisen, dass kein zweiter Mietvertrag erstellt wird. Wenn der Anbietervertrag, der Endpunkt, die Autorisierung oder das Ergebnis des vorherigen Schreibvorgangs nicht überprüft werden können, stoppen Sie vor jedem Schreibvorgang und leiten Sie den Fall zur Abstimmung an den Portfolio-Betreiber weiter.
Ressourcen
Nächste Schritte
Fahren Sie mit appfolio-core-workflow-b für Wartungsanfragen und Zahlungsverfolgung fort.