Instalação e Autenticação do AppFolio
Visão Geral
Configure a autenticação da API AppFolio Stack. O AppFolio usa HTTP Basic Auth com um client ID e client secret, fornecidos através do programa de parceiros Stack. Não existe SDK público npm — use chamadas REST API diretas.
Pré-requisitos
- Conta de parceiro AppFolio Stack (appfolio.com/stack)
- Client ID e Client Secret do AppFolio
- Node.js 18+ ou Python 3.10+
Instruções
Passo 1: Obter Credenciais da API
# As credenciais da API AppFolio Stack vêm do programa de parceiros
# 1. Candidate-se em appfolio.com/stack/become-a-partner
# 2. Conclua a revisão de integração
# 3. Receba a URL base fornecida pelo provedor e instruções de entrega de credenciais.
# Armazene os valores no gerenciador de segredos aprovado. Commit apenas este modelo
# não secreto se o desenvolvimento local exigir um:
cat > .env.example << 'ENVFILE'
APPFOLIO_CLIENT_ID=
APPFOLIO_CLIENT_SECRET=
APPFOLIO_BASE_URL=
ENVFILE
# .env permanece ignorado; preencha-o apenas através de um fluxo de segredo local aprovado.
Passo 2: Criar Cliente da API
// src/appfolio-client.ts
import axios, { AxiosInstance } from 'axios';
class AppFolioClient {
private api: AxiosInstance;
constructor() {
this.api = axios.create({
baseURL: process.env.APPFOLIO_BASE_URL,
auth: {
username: process.env.APPFOLIO_CLIENT_ID!,
password: process.env.APPFOLIO_CLIENT_SECRET!,
},
headers: { 'Content-Type': 'application/json' },
timeout: 30000,
});
}
async verifyConnection(): Promise<boolean> {
try {
const response = await this.api.get('/properties');
console.log(`Conectado! Encontradas ${response.data.length} propriedades`);
return true;
} catch (error: any) {
console.error(`Falha na conexão: ${error.response?.status} ${error.message}`);
return false;
}
}
get http(): AxiosInstance { return this.api; }
}
export { AppFolioClient };
Passo 3: Verificar Conexão
# Diagnóstico rápido e editado sem colocar Basic Auth em argv.
NETRC_FILE="$(mktemp)"
trap 'rm -f "$NETRC_FILE"' EXIT
chmod 600 "$NETRC_FILE"
APPFOLIO_HOST="${APPFOLIO_BASE_URL#https://}"
APPFOLIO_HOST="${APPFOLIO_HOST%%/*}"
printf 'machine %s login %s password %s\n' "$APPFOLIO_HOST" \
"$APPFOLIO_CLIENT_ID" "$APPFOLIO_CLIENT_SECRET" > "$NETRC_FILE"
curl -s -o /dev/null -w '%{http_code}\n' --netrc-file "$NETRC_FILE" \
"${APPFOLIO_BASE_URL}/properties"
Endpoints da API
| Recurso | Endpoint | Métodos |
|---|---|---|
| Propriedades | /api/v1/properties | GET |
| Unidades | /api/v1/units | GET |
| Inquilinos | /api/v1/tenants | GET |
| Contratos de Locação | /api/v1/leases | GET, POST |
| Faturas | /api/v1/bills | GET, POST |
| Fornecedores | /api/v1/vendors | GET |
| Proprietários | /api/v1/owners | GET |
| Relatórios | /api/v1/reports | GET |
Saída
- Credenciais fornecidas pelo provedor injetadas através do limite de segredo aprovado
- Cliente REST TypeScript com Basic Auth
- Resultado de conectividade editado para o endpoint de leitura segura aprovado
Exemplos
Para um primeiro ensaio de autenticação, injete uma credencial de sandbox e a URL base fornecida pelo provedor através do mecanismo de segredo local, depois faça uma requisição somente leitura para uma página de propriedade sintética aprovada. Registre apenas o código de status e o veredito da configuração do cliente; não imprima o payload da propriedade, client ID, secret ou caminho/host completo em logs compartilhados. Se o contrato, URL base, vinculação de segredo ou resultado de status não forem verificados, pare antes de qualquer fluxo de escrita e faça o proprietário da credencial corrigir a configuração.
Tratamento de Erros
| Erro | Causa | Solução |
|---|---|---|
401 Não Autorizado | Credenciais inválidas | Verifique client_id/secret do AppFolio |
403 Proibido | Não é um parceiro Stack | Complete a inscrição de parceiro |
404 Não Encontrado | URL base errada | Use o formato sua-empresa.appfolio.com |
| Timeout | Problema de rede | Verifique se o firewall permite HTTPS para appfolio.com |
Recursos
Próximos Passos
Prossiga para appfolio-hello-world para sua primeira consulta de propriedade.