A API de um software de manutenção é a porta pela qual outros sistemas leem e gravam dados no CMMS sem passar pela tela: criar uma ordem de serviço, consultar o histórico de um equipamento, enviar uma requisição ao ERP, exportar indicadores para o BI. Hoje, na maior parte dos casos, ela segue o padrão REST, com dados trocados em formato JSON pela internet.
Todo fornecedor diz que “tem API”. A frase não diz quase nada. O que interessa é o que a API cobre, como ela é protegida, quanto ela aguenta e quem vai construir a integração em cima dela. Este artigo traz as perguntas certas para separar uma resposta da outra.
Para que a manutenção precisa de API?
Nem toda empresa vai usar, e tudo bem. Mas os usos mais comuns na indústria são estes:
- Integração com o ERP. Materiais, requisições, compras, centros de custo e patrimônio, quando não existe integração nativa para o ERP da empresa. Visão geral no guia completo de integração CMMS e ERP.
- Business intelligence. Levar OS, apontamentos e paradas para o Power BI ou para o data lake corporativo. Veja CMMS e Power BI.
- Abertura de chamados por outros sistemas. Um sistema de supervisão, um portal interno ou o sistema de qualidade abrindo uma solicitação de serviço quando algo sai do padrão.
- Cadastros de RH. Técnicos admitidos e desligados atualizados automaticamente.
- Migração e cargas em massa. Importar milhares de equipamentos e planos de uma vez. Sobre isso, veja migração de dados para CMMS.
Os conceitos, em linguagem de PCM
Você não precisa programar para avaliar uma API, mas precisa entender o vocabulário que o TI vai usar na reunião.
| Termo | O que é | Por que importa para a manutenção |
|---|---|---|
| Endpoint | Um “endereço” da API para um tipo de dado (ordens de serviço, ativos, materiais) | A lista de endpoints mostra o que dá e o que não dá para integrar |
| Leitura e escrita | Se a API só consulta ou também cria e altera registros | Uma API só de leitura serve para BI, mas não para receber requisições do ERP |
| Autenticação | Como a integração prova quem é (token, OAuth 2.0) | Define se dá para dar a cada integração um acesso próprio e revogável |
| Webhook | A API avisa outro sistema quando algo acontece (OS encerrada, por exemplo) | Sem webhook, o outro sistema precisa perguntar a cada poucos minutos se algo mudou |
| Paginação | Resultados grandes vêm em partes | Afeta cargas de histórico de anos de OS |
| Limite de chamadas | Quantas requisições por minuto a API aceita | Importa em cargas iniciais e em integrações com muito volume |
| Ambiente de teste | Uma cópia separada para testar sem mexer na produção | Sem ele, todo teste de integração é feito com dado real |
| Versionamento | Como a API muda sem quebrar quem já usa | Define se uma atualização do fornecedor pode derrubar sua integração |
Perguntas para fazer ao fornecedor
Leve esta lista para a demonstração e peça as respostas por escrito. Elas valem tanto para comparar fornecedores quanto para registrar o que foi prometido.
Cobertura
- Quais objetos a API expõe: ordens de serviço, solicitações, ativos, planos, materiais, apontamentos de horas, checklists, anexos?
- Para cada um, é possível ler, criar, alterar e encerrar?
- Campos personalizados que criamos aparecem na API?
Documentação e teste
- A documentação é pública ou entregue no contrato? Tem exemplos de chamadas?
- Existe ambiente de teste (sandbox) separado da produção? Tem custo?
Segurança
- Como funciona a autenticação? Dá para criar uma credencial por integração, com permissões limitadas?
- As chamadas ficam registradas (quem, quando, o quê)?
- Como se revoga uma credencial vazada?
Limites e desempenho
- Qual o limite de chamadas por minuto ou por dia? O que acontece quando passa?
- Como fazer uma carga inicial de, por exemplo, 30 mil OS históricas?
Eventos e mudanças
- Existem webhooks? Para quais eventos?
- Como a API é versionada? Com quanto tempo de antecedência mudanças incompatíveis são avisadas?
Comercial
- O uso da API está incluído no plano ou é cobrado à parte?
- Quem constrói a integração: o fornecedor, um parceiro ou a nossa TI?
- Ao fim do contrato, como exportamos todos os nossos dados, inclusive anexos?
Essas perguntas podem entrar como critérios numa planilha de avaliação de CMMS, ao lado de funcionalidades e usabilidade.
Quer tirar isso da planilha?O Sismetro junta ordens de serviço, preventivas, estoque e indicadores num só lugar, com app para os técnicos e integração com o ERP Senior.
Sinais de alerta
- “Temos API”, mas não há documentação para mostrar. Pode existir, mas não está madura para uso por terceiros.
- A sugestão é acessar direto o banco de dados. Funciona até a primeira atualização de versão. E, num sistema em nuvem, raramente é permitido.
- Uma credencial única para tudo. Se o BI, o ERP e o portal usam o mesmo usuário, não dá para saber quem fez o quê nem cortar o acesso de um sem derrubar os outros.
- Nenhum registro de chamadas. Quando a integração falhar (e ela vai falhar um dia), não haverá como investigar.
- API só de leitura vendida como integração com ERP. Ler dados do CMMS é metade do caminho; o ERP também precisa mandar cadastros e status.
Um teste prático que vale mais que a apresentação
Se a API é decisiva para a sua escolha, peça um teste curto. Um exemplo de roteiro de uma hora com o TI da empresa e o técnico do fornecedor, no ambiente de teste:
- Gerar uma credencial nova com permissão só para ordens de serviço.
- Criar uma OS para um equipamento existente, via API.
- Consultar essa OS e alterar a prioridade.
- Encerrar a OS pela tela e ver se o evento aparece (por webhook ou por consulta).
- Puxar as OS encerradas no mês, com paginação.
- Revogar a credencial e confirmar que ela parou de funcionar.
Um fornecedor com API madura passa por esse roteiro sem drama. Se o teste precisar ser remarcado três vezes, isso também é informação.
CMMS na nuvem, ERP dentro da fábrica: quem chama quem?
Uma pergunta que costuma aparecer tarde demais. Se o CMMS está na nuvem e o ERP roda num servidor dentro da empresa, o CMMS não consegue simplesmente “chamar” o ERP: o firewall da fábrica bloqueia conexões de fora, e com razão. As saídas mais comuns são três: um agente instalado na rede da empresa que busca e envia dados para a nuvem, uma VPN entre os ambientes ou a publicação controlada de serviços do ERP para endereços autorizados. Cada uma tem implicações de segurança que o TI precisa aprovar.
Pergunte ao fornecedor qual desses modelos ele usa em clientes com ERP local e quem instala e monitora o componente que fica dentro da sua rede. O tema da hospedagem está em CMMS na nuvem ou local.
API não é integração pronta
Ter API significa que a integração é possível, não que ela existe. Alguém precisa especificar os fluxos, desenvolver, testar e manter. Por isso, quando há integração nativa para o seu ERP, ela costuma sair mais barata e mais rápida do que uma construção sob medida sobre API. O Sismetro, por exemplo, tem integração nativa com o ERP Senior; para outros sistemas, pergunte à equipe quais recursos de integração se aplicam ao seu caso. A divisão de dados entre os sistemas está em integração CMMS e ERP: o que deve conversar.
Próximo passo: liste os sistemas com os quais a manutenção precisa conversar nos próximos dois anos (ERP, BI, RH, qualidade) e, para cada um, escreva se o fluxo é de leitura, de escrita ou dos dois. Essa lista transforma a pergunta genérica “tem API?” em perguntas que o fornecedor consegue responder com precisão.
Perguntas frequentes
O que é API em um software de manutenção?
É a interface que permite a outros sistemas ler e gravar dados no CMMS sem usar a tela, por exemplo para criar ordens de serviço, consultar ativos ou exportar dados para o BI. Na maioria dos casos segue o padrão REST com dados em JSON.
Todo CMMS precisa ter API?
Não necessariamente. Se a empresa usa um ERP com integração nativa e os relatórios do próprio sistema atendem, a API pode nem ser usada. Ela passa a ser decisiva quando há ERP sem integração pronta, BI corporativo ou outros sistemas que precisam abrir ou consultar ordens de serviço.
Qual a diferença entre API e integração nativa?
A integração nativa é um fluxo pronto entre dois sistemas específicos, mantido pelo fornecedor. A API é a ferramenta que permite construir integrações sob medida, que alguém precisa desenvolver e manter.
O que é webhook e por que perguntar sobre ele?
Webhook é o aviso automático que a API envia a outro sistema quando um evento acontece, como o encerramento de uma OS. Sem ele, o outro sistema precisa consultar a API a cada poucos minutos para descobrir mudanças, o que é menos eficiente e gera atraso.
