Otimização da Integração de APIs

1. Contexto e Ambiente Técnico

O cliente operava três sistemas de fornecedores diferentes, cada um com sua própria API:

• Sistema A (prontuário): API REST legada, autenticação via API Key em header, retornava XML em vez de JSON, sem paginação nos endpoints de listagem.
• Sistema B (agendamento): API REST moderna com OAuth 2.0 e retorno JSON, mas com rate limiting agressivo de 60 requisições/minuto.
• Sistema C (faturamento): Integração via SOAP, mantida por um terceiro, com contrato de SLA de 4 horas para suporte.

A comunicação entre os três era feita por um script PHP agendado via cron job a cada 5 minutos, que fazia polling em todos os sistemas e tentava sincronizar dados. Esse script tinha crescido de forma orgânica ao longo de 3 anos, sem documentação e com tratamento de erros ausente na maioria dos fluxos.

2. Diagnóstico: O Que Estava Errado

Antes de propor qualquer solução, realizamos uma semana de análise técnica. Os principais achados foram:

2.1 Polling desnecessário e gargalo de rede

O cron job consultava o Sistema B a cada 5 minutos, independentemente de haver alterações ou não. Com um volume de 200 agendamentos diários, 96% das chamadas retornavam lista vazia — puro desperdício de banda e de cota de rate limiting. Quando a cota era extrapolada, o sistema B bloqueava requisições por 1 hora, criando um "buraco" onde novos agendamentos simplesmente não chegavam ao prontuário.

2.2 Ausência de idempotência nos escritos

O script não verificava se um registro já havia sido criado antes de tentar criá-lo novamente. Em caso de timeout durante a gravação, o cron seguinte rodava e criava o registro duplicado. Encontramos pacientes com até 4 prontuários distintos no sistema.

2.3 Falhas silenciosas

Erros de integração eram apenas impressos no stdout do cron, sem nenhum alerta, log estruturado ou notificação. A equipe só descobria falhas quando um funcionário relatava inconsistência manualmente.

3. Decisões de Arquitetura

Com o diagnóstico em mãos, apresentamos ao cliente duas opções de arquitetura:

Opção A — Middleware centralizado (escolhida)

Desenvolver uma camada intermediária (API Gateway próprio) que absorve as chamadas de todos os sistemas, normaliza formatos (converte XML→JSON onde necessário), aplica cache e distribui eventos via fila assíncrona. Custo de implementação maior, mas desacopla completamente os sistemas legados.

Opção B — Refactoring incremental do script

Corrigir os problemas mais críticos do script existente sem mudar a arquitetura. Menor custo inicial, porém as limitações estruturais (polling, falta de observabilidade) permaneceriam.

O cliente optou pela Opção A após análise de custo-benefício: o custo de um incidente de perda de dados (registro médico crítico ausente) era incomparavelmente maior do que o investimento na arquitetura correta.

4. Implementação

4.1 Substituição de polling por webhooks

O Sistema B suportava webhooks (que o cliente nunca havia configurado). Registramos um endpoint no nosso middleware para receber eventos em tempo real: POST /webhook/agendamento. Cada novo agendamento ou alteração dispara a notificação imediatamente, eliminando os ciclos de polling e a extrapolação de rate limit.

Para o Sistema A, que não suportava webhooks, implementamos um change data capture via consulta diferencial: ao invés de buscar todos os registros, buscamos apenas os alterados desde o último timestamp registrado — reduzindo o volume de dados em ~94%.

4.2 Camada de cache inteligente

Dados de referência (tabelas de CID, convênios, médicos cadastrados) mudavam raramente mas eram consultados em toda transação. Implementamos cache Redis com TTL de 4 horas para esses dados, servindo-os localmente sem hit na API externa. Para dados transacionais, usamos ETag/Last-Modified para validação condicional — a API só retorna o payload completo quando houve mudança.

4.3 Idempotência e filas assíncronas

Toda operação de escrita passou a gerar uma chave de idempotência baseada em hash do payload + timestamp da origem. Antes de executar qualquer insert, o middleware consulta um registro de operações já processadas. Reprocessamentos (por retry automático) são ignorados silenciosamente. As filas de mensagens garantem que eventos sejam processados exatamente uma vez, mesmo em caso de falha parcial.

4.4 Observabilidade

Implementamos logging estruturado em JSON com correlação de request IDs entre sistemas, métricas de latência por endpoint e alertas automáticos via e-mail quando a taxa de erro supera 1% em janelas de 5 minutos. O cliente passou a ter visibilidade real do que acontece nas integrações pela primeira vez.

5. Resultados Mensurados (após 30 dias em produção)

Além das métricas acima, o cliente relatou eliminação completa de reclamações de pacientes sobre dados incorretos e redução de 2 horas semanais de trabalho manual de reconciliação que a equipe administrativa realizava.

6. Lições Aprendidas

• Polling tem custo oculto: não apenas em latência, mas em cota de API e em carga no banco de dados do sistema consultado. Webhooks ou change data capture são sempre preferíveis quando o volume é alto.
• Idempotência não é opcional em integrações: redes falham, servidores reiniciam, timeouts acontecem. Todo sistema de integração precisa lidar com reprocessamento graciosamente.
• Observabilidade antes de otimização: sem métricas de baseline, não é possível saber se as mudanças estão gerando melhoria real. Medir primeiro é sempre o passo correto.
• Dívida técnica tem juros compostos: o script de cron que "funcionava" custou ao cliente meses de inconsistências e horas de trabalho manual. Refactoring tardio sempre sai mais caro.