AppFolio — Ordens de Serviço e Manutenção
Visão Geral
Gerencie o ciclo de vida completo de ordens de serviço de manutenção através da API Stack do AppFolio.
Use este fluxo de trabalho quando inquilinos enviarem solicitações de manutenção, quando precisar atribuir
fornecedores a ordens de serviço abertas, acompanhar o progresso dos reparos em todas as propriedades ou finalizar
trabalhos concluídos com registros de custos. Este é o fluxo de trabalho secundário — para painéis de propriedade
e locação, veja appfolio-core-workflow-a.
Pré-requisitos
- Um contrato AppFolio verificado e um portfólio sandbox com registros sintéticos de propriedade, unidade, fornecedor e ordem de serviço; não teste a automação de manutenção contra uma unidade de produção ocupada.
- Uma identidade de serviço com privilégios mínimos, suporte a idempotência para ações de criação/fechamento, e um caminho de escalonamento aprovado para manutenção crítica de segurança.
- Uma política de minimização de dados: armazene e transmita apenas os fatos de manutenção necessários para realizar o trabalho, nunca preferências de inquilinos, códigos de acesso ou informações detalhadas de ocupação em notas ou registros genéricos de fornecedores.
Instruções
Etapa 1: Criar uma Ordem de Serviço a partir de uma Solicitação de Manutenção
const workOrder = await client.workOrders.create({
property_id: 'prop_4821',
unit_id: 'unit_12B',
category: 'plumbing',
priority: 'high',
description: 'Vazamento sintético de encanamento reportado na unidade sandbox',
requested_by: 'tenant_8934',
due_date: '2026-04-10',
});
console.log(`Ordem de serviço ${workOrder.id} criada — status: ${workOrder.status}`);
Etapa 2: Atribuir um Fornecedor
const assignment = await client.workOrders.assign(workOrder.id, {
vendor_id: 'vendor_plumb_01',
scheduled_date: '2026-04-08',
time_window: '09:00-12:00',
notes: 'Confirme o agendamento através do canal de ordem de serviço aprovado.',
});
console.log(`Atribuído a ${assignment.vendor_name} em ${assignment.scheduled_date}`);
Etapa 3: Acompanhar o Status da Ordem de Serviço
const open = await client.workOrders.list({
property_id: 'prop_4821',
status: ['open', 'in_progress', 'scheduled'],
sort: 'priority_desc',
});
open.items.forEach(wo =>
console.log(`#${wo.id} [${wo.priority}] ${wo.category} — ${wo.status} (vencimento ${wo.due_date})`)
);
Etapa 4: Fechar Ordem de Serviço com Registro de Custos
const closed = await client.workOrders.close(workOrder.id, {
resolution: 'Substituído o sifão e apertado a linha de abastecimento. Sem mais vazamentos.',
labor_cost: 175.00,
materials_cost: 42.50,
completed_date: '2026-04-08',
attachments: ['receipt_plumb_0408.pdf'],
});
console.log(`Fechada #${closed.id} — custo total: $${closed.total_cost}`);
Tratamento de Erros
| Problema | Causa | Correção |
|---|---|---|
401 Unauthorized | Credenciais de API expiradas ou inválidas | Atualize client_id/secret no painel Stack |
404 Work Order Not Found | ID da ordem de serviço errado ou já excluída | Verifique o ID com workOrders.list() |
422 Missing required fields | Categoria ou property_id omitidos | Inclua todos os campos obrigatórios conforme esquema |
409 Conflict | Ordem de serviço já fechada | Verifique o status antes de tentar fechar |
429 Rate Limited | Excedido 120 requisições/minuto | Adicione backoff exponencial com atraso base de 1s |
Saída
Uma execução bem-sucedida cria uma ordem de serviço, atribui a um fornecedor com uma janela de serviço agendada e a fecha com registros de custos e notas de resolução. O administrador da propriedade obtém uma trilha de auditoria completa, desde a solicitação até a conclusão.
Exemplos
Para um fluxo de trabalho de encanamento em sandbox, crie uma ordem de serviço sintética com uma chave de idempotência estável, atribua um fornecedor sandbox e leia seu status antes de qualquer transição. Anexe apenas um recibo de teste não sensível, depois feche a ordem uma vez e verifique o total e o registro de auditoria sem registrar detalhes do inquilino ou de acesso. Repita a mesma solicitação para provar que ordens de serviço duplicadas e registros de custos duplicados são rejeitados. Se a atribuição do fornecedor, classificação de segurança, estado anterior ou resultado do fechamento forem incertos, deixe a ordem aberta e encaminhe-a ao operador de propriedade autorizado para revisão.
Recursos
Próximos Passos
Veja appfolio-sdk-patterns para configuração de autenticação e auxiliares de paginação.