AppFolio — Gerenciamento de Propriedades e Inquilinos
Visão Geral
Fluxo de trabalho principal para integração de gerenciamento de propriedades com AppFolio. Abrange todo o ciclo de vida da propriedade: criar e atualizar registros de propriedades, gerenciar perfis de inquilinos e contratos de locação, e consultar dados de ocupação. Utiliza a API AppFolio Stack com credenciais de cliente OAuth 2.0 para acesso servidor a servidor. Todos os endpoints retornam JSON e suportam paginação via parâmetros cursor para grandes portfólios.
Pré-requisitos
- Um contrato de parceiro/API AppFolio vigente que confirme a URL base do portfólio atribuído, método de autenticação, escopos aprovados e capacidades de escrita; não inferir esses dados de um tutorial ou de outro portfólio.
- Um sandbox separado com propriedades, unidades e registros sintéticos de inquilinos, além de um proprietário de credencial e um orçamento de requisições aprovado.
- Chaves de idempotência e um processo de rollback/reconciliação aprovado pelo operador para escritas de propriedades, inquilinos e contratos, que podem gerar consequências legais e de faturamento reais.
Instruções
- Confirme a URL base e o fluxo de autenticação fornecidos pelo provedor para o portfólio alvo antes de copiar qualquer configuração de cliente para um ambiente.
- Execute o caminho de criação/atualização apenas com fixtures sintéticas do sandbox e chaves de idempotência; recupere registros canônicos antes de tentar novamente uma escrita incerta.
- Valide a propriedade, datas do contrato e disponibilidade da unidade antes de criar um contrato de locação, e emita apenas IDs de registros e evidências de status resumidas.
- Promova um fluxo com capacidade de escrita somente após um ensaio encenado que comprove rollback, reconciliação e o limite de escopo de privilégio mínimo.
Passo 1: Autenticar e Inicializar o 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' };
Passo 2: Criar ou Atualizar uma Propriedade
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}`);
Passo 3: Adicionar um Inquilino e Contrato de Locação
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());
Passo 4: Consultar Ocupação
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}`);
Tratamento de Erros
| Problema | Causa | Correção |
|---|---|---|
401 Unauthorized | Token expirado ou inválido | Reautenticar com credenciais de cliente |
404 Not Found | ID de propriedade/inquilino incorreto | Verificar se o ID do recurso existe antes de referenciar |
422 Unprocessable | Campos obrigatórios ausentes | Verificar array errors[] no corpo da resposta |
409 Conflict | Contrato duplicado para a unidade | Consultar contratos existentes antes de criar |
429 Too Many Requests | Limite de taxa excedido | Aguardar usando o valor do cabeçalho Retry-After |
Saída
Uma execução bem-sucedida cria uma propriedade com unidades, adiciona um inquilino, vincula-os por meio de um contrato de locação e relata contagens de vacância. A saída do console confirma o ID de cada recurso na criação.
Exemplos
Para uma alteração de criação de contrato, execute contra uma unidade sintética nomeada do sandbox e um inquilino com uma chave de idempotência estável. Leia a propriedade e os contratos atuais, execute a escrita candidata uma vez, depois leia o contrato resultante e registre apenas IDs, datas e o status de reconciliação. Reexecute a mesma requisição para provar que ela não cria um segundo contrato. Se o contrato do provedor, endpoint, autorização ou resultado da escrita anterior não puder ser verificado, pare antes de qualquer escrita e envie o caso para o operador do portfólio para reconciliação.
Recursos
Próximos Passos
Continue com appfolio-core-workflow-b para solicitações de manutenção e rastreamento de pagamentos.