Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

Diagnostique e corrija erros comuns de integração da API AppFolio.

O que é tons-of-skills-marketplace?

Esta skill ajuda desenvolvedores e agentes de IA a diagnosticar e resolver rapidamente falhas de integração com a API Stack da AppFolio, que gerencia integrações de administração de propriedades como triagem de inquilinos, ordens de serviço, gestão de aluguéis e contabilidade. Ela abrange erros de autenticação (401/403), limites de taxa (429), validação de dados (422/409) e falhas de servidor (500/503), com foco especial em erros 404 causados por URLs base incorretas por portfólio. A skill fornece uma referência de erros, um classificador TypeScript, um guia de depuração e padrões de recuperação, tudo projetado para funcionar com registros de incidentes anonimizados. Suporta plataformas como Claude Code, Cursor e Codex, e é ideal para qualquer agente que integre ou mantenha sistemas com a API da AppFolio.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/HEAD/plugins/saas-packs/appfolio-pack/skills/appfolio-common-errors

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Erros Comuns da AppFolio

Visão Geral

A API Stack da AppFolio alimenta integrações de administração de propriedades para triagem de inquilinos, ordens de serviço, gestão de aluguéis e contabilidade. Cada portfólio opera sob seu próprio subdomínio ({empresa}.appfolio.com), o que significa que uma única integração pode precisar lidar com várias URLs base. Os erros geralmente resultam de configuração de autenticação incorreta, URLs base incorretas por portfólio e violações de lógica de negócios, como registros duplicados de inquilinos ou datas de aluguel conflitantes. Falhas na pesquisa de inquilinos (404) são o problema mais frequente, normalmente causado por direcionamento ao subdomínio de portfólio errado. Esta referência cobre falhas de nível HTTP, erros de validação específicos da administração de propriedades e padrões de recuperação para os problemas mais comuns.

Pré-requisitos

  • Um registro de incidente anonimizado contendo o identificador do portfólio, endpoint, código de status, ID de correlação da requisição e janela de tempo; nunca copie cargas de inquilinos ou aluguéis para um ticket compartilhado.
  • Acesso ao endpoint correto do portfólio (sandbox ou produção) e um proprietário de credenciais que possa rotacionar ou validar credenciais sem expô-las em logs ou argumentos de comando.
  • Uma política de retry limitada, um mecanismo de idempotência para gravações e um caminho de escalação conhecido do operador para estados incertos de inquilino, aluguel ou ordem de serviço.

Instruções

  1. Classifique a resposta por autenticação, limite de taxa, validação ou falha de servidor e preserve apenas os campos de diagnóstico anonimizados.
  2. Verifique a URL base do portfólio antes de alterar credenciais ou tentar novamente um 404; um ID de inquilino válido em outro portfólio não é evidência de ausência.
  3. Para 409 ou falhas de gravação parcial, consulte o registro canônico e use a chave de idempotência da operação ou revisão do operador antes de emitir outra gravação.
  4. Respeite Retry-After para 429 e pare após o orçamento de retry configurado; pause o lote em 5xx ou resultados de gravação desconhecidos.

Referência de Erros

CódigoMensagemCausaCorreção
401Não autorizadoPar client_id/secret inválido ou rotacionadoRegenerar credenciais no portal de parceiros AppFolio Stack
403ProibidoConta não aprovada como parceiro StackCompletar inscrição de parceiro em appfolio.com/stack
404Inquilino não encontradoURL base do portfólio errada ou inquilino excluídoVerificar se a URL base é {empresa}.appfolio.com/api/v1
409Conflito de aluguelDatas de aluguel sobrepostas para a mesma unidadeVerificar aluguéis existentes na unidade antes de criar novo
422Falha de validaçãoCampos obrigatórios ausentes na ordem de serviço ou inquilinoIncluir todos os campos obrigatórios: unit_id, description, priority
429Muitas requisiçõesExcedido o limite de 120 requisições/minutoImplementar backoff exponencial começando com atraso de 1s
500Erro interno do servidorProblema na plataforma AppFolioTentar novamente após 30s; verificar status.appfolio.com
503Serviço indisponívelJanela de manutenção (tipicamente fins de semana)Tentar novamente com backoff; inscrever-se no calendário de manutenção

Manipulador de Erros

interface AppFolioError {
  code: number;
  message: string;
  category: "auth" | "rate_limit" | "validation" | "server";
}

function classifyAppFolioError(status: number, body: string): AppFolioError {
  if (status === 401 || status === 403) {
    return { code: status, message: body, category: "auth" };
  }
  if (status === 429) {
    return { code: 429, message: "Rate limit exceed", category: "rate_limit" };
  }
  if (status === 404 || status === 409 || status === 422) {
    return { code: status, message: body, category: "validation" };
  }
  return { code: status, message: body, category: "server" };
}

Guia de Depuração

Erros de Autenticação

A AppFolio usa HTTP Basic Auth com client_id:client_secret. Verifique se as credenciais não estão codificadas em URL. Cada portfólio tem sua própria URL base -- confirme se você está direcionando o subdomínio correto {empresa}.appfolio.com. As credenciais são rotacionadas com alterações na aprovação do parceiro.

Erros de Limite de Taxa

A API Stack impõe 120 requisições/minuto por chave de API. Agrupe pesquisas de inquilinos em vez de chamadas individuais. Use o valor do cabeçalho Retry-After quando presente. Endpoints em massa (ex.: /properties?page=1&per_page=100) reduzem significativamente a contagem de chamadas. Os limites de taxa são por chave, não por portfólio, então integrações com múltiplos portfólios compartilham o mesmo orçamento.

Erros de Validação

A criação de ordem de serviço requer unit_id, description e priority. A criação de inquilino requer first_name, last_name e email. A criação de aluguel falha com 409 se as datas se sobrepuserem a um aluguel ativo existente na mesma unidade -- consulte os aluguéis atuais primeiro. As datas de mudança devem estar no formato ISO 8601 válido. IDs de unidade são específicos do portfólio e não podem ser reutilizados entre subdomínios.

Tratamento de Erros

CenárioPadrãoRecuperação
Pesquisa de inquilino retorna 404Pesquisar por email antes de criarUsar endpoint /tenants?email=
Ordem de serviço 422Campo priority ausenteDefinir como normal se não especificado
Conflito de data de aluguelAluguel ativo sobrepostoEncerrar aluguel existente antes de criar novo
Falha parcial em importação em massaAlguns registros rejeitadosAnalisar array de erros, tentar novamente apenas registros com falha
Token de autenticação expirado no meio do lote401 em chamadas subsequentesReautenticar e retomar do último deslocamento

Diagnóstico Rápido

# Verificar conectividade da API sem colocar credenciais Basic Auth em argv.
NETRC_FILE="$(mktemp)"
trap 'rm -f "$NETRC_FILE"' EXIT
chmod 600 "$NETRC_FILE"
APPFOLIO_HOST="${APPFOLIO_BASE_URL#https://}"
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}" --netrc-file "$NETRC_FILE" \
  "${APPFOLIO_BASE_URL}/api/v1/properties"

Saída

  • Uma classificação anonimizada da falha e o contexto do portfólio verificado
  • Uma decisão de recuperação limitada: configuração correta, atraso/retry, reconciliação, rotação através do proprietário da credencial, ou escalação de um resultado de gravação desconhecido
  • Um recibo de incidente que identifica o lote afetado sem reter dados de inquilino, aluguel ou credenciais

Exemplos

Quando uma importação de ordem de serviço recebe 429, pare de despachar novos registros, mantenha o cursor do lote e as chaves de idempotência, e aguarde a janela de retry fornecida pelo servidor antes de retomar no mesmo registro. Para um conflito de aluguel 409, consulte o aluguel atual da unidade através do portfólio correto e encaminhe o resultado para um operador autorizado, em vez de encerrar ou substituir um aluguel automaticamente. Se a leitura de acompanhamento não estiver disponível ou o resultado de uma gravação anterior for desconhecido, coloque esse registro em quarentena e continue apenas com trabalho seguro não relacionado.

Recursos

Próximos Passos

Consulte appfolio-debug-bundle.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page for positioning, plan a conversion-optimized page layout, or design a launch page. Examples: "landing page for product launch", "conversion-optimized layout for SaaS

jeremylongshore/tons-of-skills-marketplace

Use when asked to design growth-optimized landing pages, activation funnel layouts, or experiment-friendly page structures. Examples: "growth-optimized landing", "activation funnel layout", "A/B testable page

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page, design page layout for conversion, or plan landing page information architecture. Examples: "landing page structure for SaaS", "conversion-optimized layout

jeremylongshore/tons-of-skills-marketplace

Generate polished demo videos from a single prompt. Use when the user asks to create a demo video, product walkthrough, feature showcase, or animated presentation. Trigger with "make a demo video", "create a product video", "demo walkthrough", or "feature showcase video".

jeremylongshore/tons-of-skills-marketplace

Track cryptocurrency portfolio with real-time valuations, allocation analysis, and P&L tracking. Use when checking portfolio value, viewing holdings breakdown, analyzing allocations, or exporting portfolio data. Trigger with phrases like "show my portfolio", "check crypto holdings", "portfolio allocation", "track my crypto", or "export portfolio".

jeremylongshore/tons-of-skills-marketplace

Runs the full release workflow for the current project. Commits any uncommitted changes, pushes to remote, creates and merges a PR if on a feature branch, determines the next semver version from conventional commits, creates an annotated git tag and GitHub release with generated notes, cleans up merged branches, and returns to a clean main. Use when the user says promote, ship, release, commit and push, tag and release, or get back to main.

jeremylongshore/tons-of-skills-marketplace

Agent skill at plugins/productivity/content-multiplier/skills/channel-formats/SKILL.md

jeremylongshore/tons-of-skills-marketplace

Operate an evidence-backed editorial queue, balance topic and format coverage, schedule approved drafts, and reconcile backlog state with the publishing system. Use when choosing or scheduling the next blog work. Trigger with "show the editorial calendar" or "pick the next topic".

jeremylongshore/tons-of-skills-marketplace

Configure CI/CD pipeline for AppFolio property management integrations. Trigger: "appfolio CI".

jeremylongshore/tons-of-skills-marketplace

Build property management dashboard with AppFolio API data. Trigger: "appfolio property dashboard".

jeremylongshore/tons-of-skills-marketplace

Automate tenant management and lease operations with AppFolio. Trigger: "appfolio tenant management".

jeremylongshore/tons-of-skills-marketplace

Collect AppFolio API debug evidence for support tickets. Trigger: "appfolio debug".

jeremylongshore/tons-of-skills-marketplace

Deploy AppFolio integration service to cloud infrastructure. Trigger: "deploy appfolio".

jeremylongshore/tons-of-skills-marketplace

Query AppFolio properties, units, and tenants via REST API. Trigger: "appfolio hello world".

jeremylongshore/tons-of-skills-marketplace

Configure AppFolio Stack API authentication with OAuth 2.0. Use when setting up property management API access, registering as an AppFolio Stack partner, or configuring client credentials for API calls. Trigger: "install appfolio", "setup appfolio", "appfolio auth", "appfolio API key".

jeremylongshore/tons-of-skills-marketplace

Set up local development for AppFolio property management API integration. Trigger: "appfolio local dev".

jeremylongshore/tons-of-skills-marketplace

Production readiness checklist for AppFolio integrations. Trigger: "appfolio production checklist".

jeremylongshore/tons-of-skills-marketplace

Handle AppFolio API rate limits with throttling and backoff. Trigger: "appfolio rate limit".

jeremylongshore/tons-of-skills-marketplace

Reference architecture for AppFolio property management integration. Trigger: "appfolio architecture".

jeremylongshore/tons-of-skills-marketplace

Apply production-ready patterns for AppFolio REST API integration. Trigger: "appfolio patterns".

Habilidades Relacionadas