Paquete de Depuración de AppFolio
Descripción General
Este paquete de depuración recopila evidencia de diagnóstico de las integraciones con la API de gestión de propiedades de AppFolio para la escalación de soporte y el análisis de causa raíz. Captura la conectividad de la API contra los endpoints de propiedades, inquilinos y órdenes de trabajo, el estado de autenticación utilizando el par de credenciales del cliente, los registros de errores recientes de las canalizaciones de integración y la información de la versión del SDK. El tarball resultante proporciona a los ingenieros de soporte todo lo que necesitan para diagnosticar fallos de conectividad, rechazos de autenticación y problemas de sincronización de datos sin requerir acceso en vivo a su entorno.
Requisitos Previos
- Tener instalados
curl,jq,tar - Tener configuradas las variables de entorno
APPFOLIO_CLIENT_IDyAPPFOLIO_CLIENT_SECRET(par de autenticación básica) - Tener configurada
APPFOLIO_BASE_URLapuntando a la base de su API Stack (por ejemplo,https://suempresa.appfolio.com/api/v1)
Instrucciones
- Obtenga la aprobación del incidente y defina la ventana de tiempo afectada, el portafolio y las sondas seguras de solo lectura; no recopile cuerpos de inquilinos, arrendamientos, pagos o registros sin procesar solo porque estén disponibles.
- Cree el paquete con el estado de configuración redactado, el estado/latencia del proveedor, las cabeceras de límite de velocidad y solo las versiones de los paquetes; mantenga las credenciales fuera de argv.
- Revise cada archivo antes de compartirlo, cifre o utilice el canal de soporte aprobado para el archivo, y elimine la copia local de acuerdo con la política del incidente.
- Si la evidencia requiere registros sensibles, deténgase y obtenga una exportación mínima aprobada por separado en lugar de expandir este paquete de depuración de propósito general.
Script de Recopilación de Depuración
#!/bin/bash
set -euo pipefail
BUNDLE="debug-appfolio-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"
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"
probe() {
endpoint="$1"
curl -s -o /dev/null -w 'HTTP %{http_code} in %{time_total}s\n' \
--netrc-file "$NETRC_FILE" "${APPFOLIO_BASE_URL}/${endpoint}?per_page=1" \
|| printf 'UNREACHABLE\n'
}
# Verificación del entorno
echo "=== Environment ===" > "$BUNDLE/environment.txt"
echo "Base URL: ${APPFOLIO_BASE_URL:-NOT SET}" >> "$BUNDLE/environment.txt"
echo "Client ID: ${APPFOLIO_CLIENT_ID:+SET (redactado)}" >> "$BUNDLE/environment.txt"
echo "Client Secret: ${APPFOLIO_CLIENT_SECRET:+SET (redactado)}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo 'no instalado')" >> "$BUNDLE/environment.txt"
echo "Timestamp: $(date -u)" >> "$BUNDLE/environment.txt"
# Metadatos de conectividad de la API únicamente: nunca escribir cuerpos de API en este paquete.
echo "=== API Health ===" > "$BUNDLE/api-health.txt"
probe properties >> "$BUNDLE/api-health.txt"
# Sonda del endpoint de órdenes de trabajo
echo "=== Work Orders ===" > "$BUNDLE/work-orders.txt"
probe work_orders >> "$BUNDLE/work-orders.txt"
# Sonda del endpoint de inquilinos
echo "=== Tenants ===" > "$BUNDLE/tenants.txt"
probe tenants >> "$BUNDLE/tenants.txt"
# Solo inventario de registros; los registros sin procesar pueden contener datos de inquilinos y financieros.
echo "=== Log Inventory ===" > "$BUNDLE/app-logs.txt"
find /var/log/appfolio-sync -maxdepth 1 -type f -printf '%f %s bytes\n' 2>/dev/null \
|| echo "No se encontraron registros de sincronización" >> "$BUNDLE/app-logs.txt"
# Cabeceras de límite de velocidad
echo "=== Rate Limits ===" > "$BUNDLE/rate-limits.txt"
curl -sI --netrc-file "$NETRC_FILE" \
"${APPFOLIO_BASE_URL}/properties?per_page=1" 2>/dev/null | grep -i "x-rate\|retry-after\|x-ratelimit" >> "$BUNDLE/rate-limits.txt" || echo "No hay cabeceras de límite de velocidad" >> "$BUNDLE/rate-limits.txt"
# Versiones de paquetes
echo "=== Dependencies ===" > "$BUNDLE/deps.txt"
npm ls 2>/dev/null | grep -i appfolio >> "$BUNDLE/deps.txt" || echo "No se encontraron paquetes npm de AppFolio" >> "$BUNDLE/deps.txt"
tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"
Análisis del Paquete
tar -xzf debug-appfolio-*.tar.gz
cat debug-appfolio-*/environment.txt # Verificar que las credenciales están configuradas
cat debug-appfolio-*/api-health.txt # Comprobar el estado HTTP y la latencia
cat debug-appfolio-*/rate-limits.txt # Confirmar que no hay límite de velocidad
jq '.errors' debug-appfolio-*/work-orders.txt 2>/dev/null # Analizar las cargas de error
Problemas Comunes
| Síntoma | Revisar en el Paquete | Solución |
|---|---|---|
| 401 en todos los endpoints | environment.txt muestra client ID/secret NO CONFIGURADOS | Configure APPFOLIO_CLIENT_ID y APPFOLIO_CLIENT_SECRET en el entorno |
| 403 Prohibido en inquilinos | tenants.txt HTTP 403 | Falta el alcance de la API Stack; solicite permiso de lectura de inquilinos en el portal de socios de AppFolio |
| 429 Demasiadas Solicitudes | rate-limits.txt muestra la cabecera retry-after | Reduzca la velocidad e implemente reintentos exponenciales; AppFolio permite 120 solicitudes/min |
| Tiempo de espera en órdenes de trabajo | api-health.txt muestra tiempo > 30s | Reduzca el parámetro per_page; filtre por updated_since para acotar el conjunto de resultados |
| Lista de propiedades vacía | api-health.txt devuelve [] | Verifique que APPFOLIO_BASE_URL apunte al portafolio correcto; compruebe los filtros de grupo de propiedades |
| Error de certificado SSL | api-health.txt muestra error SSL de curl | Actualice el paquete de CA: sudo update-ca-certificates; compruebe la configuración del proxy |
Salida
- Un paquete revisable y redactado de presencia de configuración, estado y latencia de endpoints, cabeceras de límite de velocidad, inventario de registros y metadatos de dependencias
- Un acuse de recibo de entrega a soporte que nombra el alcance del incidente y las exclusiones de datos sensibles, en lugar de empaquetar registros de inquilinos, pagos o aplicaciones sin procesar
- Una decisión de cierre por fallo cuando la evidencia requerida no se puede recopilar de forma segura
Manejo de Errores
Trate un fallo de sonda como evidencia de una sonda fallida, no como permiso para capturar respuestas más grandes o eludir los controles de credenciales. Para 401/403, verifique la configuración del cliente gestionado con el propietario de la credencial; para 429, conserve las cabeceras de límite de velocidad y detenga más sondas; para 5xx o tiempo de espera, recopile solo la evidencia de tiempo/estado redactada y consulte la página de estado del proveedor. Si el soporte necesita un registro específico de inquilino o pago, utilice una exportación mínima aprobada por separado con sus propios controles de retención y acceso.
Ejemplos
Para un tiempo de espera de sincronización en producción, cree un paquete que cubra la ventana de tiempo afectada y una sonda segura de solo lectura de propiedades. Confirme que contiene estado/latencia, cabeceras de límite de velocidad, versiones de dependencias y metadatos de archivos de registro, pero ningún cuerpo de respuesta, credencial, dato de inquilino o financiero. Revise el archivo antes de subirlo al canal de soporte cifrado aprobado. Si la revisión encuentra una carga útil sin procesar o un secreto, elimine el archivo, rote según corresponda y regenere un paquete minimizado antes de la escalación.
Verificación Automatizada de Salud
async function checkAppFolioHealth(): Promise<{
status: string;
latencyMs: number;
endpoints: Record<string, number>;
}> {
const baseUrl = process.env.APPFOLIO_BASE_URL;
const creds = Buffer.from(
`${process.env.APPFOLIO_CLIENT_ID}:${process.env.APPFOLIO_CLIENT_SECRET}`
).toString("base64");
const headers = { Authorization: `Basic ${creds}` };
const endpoints = ["properties", "tenants", "work_orders"];
const results: Record<string, number> = {};
const start = Date.now();
for (const ep of endpoints) {
const res = await fetch(`${baseUrl}/${ep}?per_page=1`, { headers });
results[ep] = res.status;
}
return {
status: Object.values(results).every((s) => s === 200) ? "healthy" : "degraded",
latencyMs: Date.now() - start,
endpoints: results,
};
}
Recursos
Próximos Pasos
Consulte appfolio-rate-limits.