Lista de Verificação de Prontidão para AppFolio
Visão Geral
A AppFolio gerencia propriedades, inquilinos, contratos de locação e ordens de serviço para operações imobiliárias. Uma integração de produção lida com PII sensível de inquilinos, transações financeiras e fluxos de trabalho de manutenção. Falhas aqui significam perda de coleta de aluguel, ordens de serviço não processadas ou exposição de dados de inquilinos sob a CCPA. Esta lista de verificação garante que sua integração com a API da AppFolio seja resiliente, compatível e observável.
Pré-requisitos
- Um contrato de parceiro de produção verificado, URL base, mecanismo de autenticação, escopos de endpoint permitidos e proprietários nomeados para decisões de negócios, segurança, operações e rollback.
- Um ensaio em sandbox concluído usando dados sintéticos, credenciais gerenciadas separadas, um orçamento de requisição e um plano registrado de rollback/reconciliação.
- Evidências para observabilidade, minimização de PII, writes idempotentes e roteamento de alertas—não um item de lista de verificação que meramente afirma que esses controles existem.
Instruções
- Valide a configuração real do cliente emitida pelo provedor através do gerenciador de segredos; não use um endpoint ou esquema de autenticação padrão no código de release.
- Execute as verificações de prontidão em staging e, em seguida, um ensaio controlado com características de produção que realize apenas leituras seguras autorizadas.
- Revise cada controle falho, ignorado ou não verificável como um impedimento; preserve recibos editados para credenciais, endpoints, monitoramento e recuperação.
- Libere progressivamente apenas com um proprietário testado de rollback e reconciliação; pause os caminhos de escrita se o estado de pagamento, ordem de serviço, inquilino ou locação for desconhecido.
Autenticação e Segredos
-
APPFOLIO_API_KEYarmazenada no gerenciador de segredos (não em arquivos de ambiente) - ID do cliente e segredo separados do código da aplicação
- Cronograma de rotação de chaves documentado (recomendado a cada 90 dias)
- Credenciais separadas para ambientes dev/staging/prod
- Credenciais da API com escopo limitado às permissões mínimas necessárias
Integração da API
- URL base de produção e método de autenticação verificados contra o contrato de parceiro atual
- Tratamento de limite de taxa com backoff exponencial
- Paginação implementada para endpoints de lista de propriedades e inquilinos
- Criação de ordem de serviço testada com todos os campos obrigatórios
- Upload de documento de locação validado para formatos suportados
- Endpoints de webhook configurados para eventos de inquilino e pagamento
- Chaves de idempotência usadas para criação de pagamento e ordem de serviço
Tratamento de Erros e Resiliência
- Disjuntor configurado para interrupções da API AppFolio
- Repetição com backoff para respostas 429/5xx
- Tratamento de PII de inquilino verificado conforme CCPA/FCRA
- Validação de dados em todas as respostas da API antes do armazenamento
- Degradação graciosa quando a sincronização de propriedades não está disponível
- Detecção de ordem de serviço duplicada evita recriação em retentativa
Monitoramento e Alertas
- Latência da API rastreada por endpoint (propriedades, inquilinos, ordens de serviço)
- Alertas de taxa de erro definidos (limite: >3% em 5 minutos)
- Falha na sincronização de pagamento aciona alerta P1 imediato
- Falhas na criação de ordem de serviço relatadas dentro de 5 minutos
- Reconciliação diária das contagens de propriedades sincronizadas vs. origem
Script de Validação
async function checkAppFolioReadiness(): Promise<void> {
const checks: { name: string; pass: boolean; detail: string }[] = [];
const client = createVerifiedAppFolioClient(); // client vinculado ao contrato de appfolio-security-basics
// Conectividade da API
try {
const res = await client.get('/properties?limit=1');
checks.push({ name: 'Conectividade da API', pass: res.status >= 200 && res.status < 300, detail: `HTTP ${res.status}` });
} catch (e: any) { checks.push({ name: 'Conectividade da API', pass: false, detail: e.message }); }
// A construção do cliente prova que a credencial gerenciada e o contrato do provedor estão disponíveis.
checks.push({ name: 'Configuração verificada do cliente', pass: true, detail: 'Carregada da configuração gerenciada' });
// Endpoint de ordens de serviço
try {
const res = await client.get('/work_orders?limit=1');
checks.push({ name: 'Ordens de Serviço', pass: res.status >= 200 && res.status < 300, detail: `HTTP ${res.status}` });
} catch (e: any) { checks.push({ name: 'Ordens de Serviço', pass: false, detail: e.message }); }
for (const c of checks) console.log(`[${c.pass ? 'PASS' : 'FAIL'}] ${c.name}: ${c.detail}`);
}
checkAppFolioReadiness();
Tratamento de Erros
| Verificação | Risco se Ignorado | Prioridade |
|---|---|---|
| Rotação de chave da API | Chaves expiradas interrompem a sincronização de propriedades | P1 |
| Falha na sincronização de pagamento | Coleta de aluguel perdida | P1 |
| Exposição de PII de inquilino | Violação da CCPA, responsabilidade legal | P1 |
| Duplicação de ordem de serviço | Despacho de manutenção duplicado | P2 |
| Tratamento de limite de taxa | Erros 429 durante importação em massa de propriedades | P3 |
Saída
- Um recibo editado de vai/não vai vinculando o cliente verificado, verificações de leitura segura, estado de monitoramento, aprovações dos proprietários e plano de rollback/reconciliação
- Uma lista de controles falhos ou não comprovados que bloqueia o lançamento até serem corrigidos
- Uma decisão de lançamento limitada que mantém caminhos sensíveis ou com capacidade de escrita desativados até que seu ensaio com características de produção tenha evidências
Exemplos
Para um lançamento de integração de ordem de serviço, execute a lista de verificação primeiro contra uma fixture de staging sintética e, em seguida, use o cliente gerenciado com características de produção para uma única leitura segura autorizada. Confirme a rota de alerta, a edição de PII e os controles de idempotência/reconciliação enquanto todos os writes permanecem desabilitados. Se uma credencial, contrato de endpoint, verificação de prontidão ou exercício de rollback não puder ser verificado, declare não vai, mantenha a revisão anterior e tenha o proprietário designado para corrigir antes de um novo ensaio.
Recursos
Próximos Passos
Consulte appfolio-security-basics para proteção de dados de inquilinos e controle de acesso.