Um cliente entra no seu site e abre um chamado para saber o status do pedido. Seu agente de atendimento recebe esse chamado e precisa acessar o histórico de compras do cliente. Aqui temos, em geral, três cenários: o ruim, o bom e o ideal.

Ruim. O agente sai do seu CRM, faz login na plataforma de e-commerce, digita o CPF / e-mail / número do pedido e pesquisa. Copia as informações e responde o cliente.

Bom. Seu CRM já tem algum app de e-commerce (que você baixou do marketplace ou que seu time de desenvolvimento construiu) para que o atendente não precise trocar de aba e veja os dados do cliente e do pedido na mesma tela em que responde o ticket. Esse app fala direto com a API do e-commerce. Funciona bem. Tão bem que seu chatbot passa a consumir a mesma API, e seu portal de atendimento ganha uma página onde o próprio cliente digita o número do pedido e consulta o status.

Isso funciona muito bem. Até o dia em que para de funcionar. Algo quebra, o app morre e você fica sem saber por quê. Aí são 100 atendentes parados, ou improdutivos, porque voltaram ao cenário ruim: abrir a página do e-commerce e consultar pedido por pedido. Depois de alguns anos trabalhando com APIs de terceiros, já vivi bastante esse filme. Cliente ligando de madrugada, no fim de semana, querendo entender o que está acontecendo.

Tem também a situação menos catastrófica: a empresa decide trocar de e-commerce. Aí começa o processo de mapear todas as dependências e trocar as APIs uma a uma. No nosso cenário hipotético, seria mexer no portal, no chatbot e provavelmente refazer o app, porque o que existe foi feito sob medida para aquele e-commerce. E o chatbot é o mais complicado de todos: a complexidade explode com a propagação de propriedades e as lógicas condicionais. É aí que o middleware começa a fazer sentido.

Mapa do sistema
Consumidores Sistemas de registro

Sidebar do CRM

Portal do cliente

Chatbot

Webhooks

Middleware

Um contrato, um lugar

Normalizar Monitoramento Métricas Limite de taxa Alertas Segredos
Azure App Service · api.suaempresa.com

CRM

E‑commerce

VTEX · Magento · Wake
Alterne entre os dois cenários. Sem middleware, cada canal precisa se conectar a cada sistema. Com ele, todos passam por um único ponto de entrada.

O cenário ideal

Ideal. É o que o desenho acima mostra: uma interface única, uma camada de abstração. Seu chatbot, seu portal e seu app não precisam saber qual é o seu e-commerce. Isso te dá liberdade para trocar de sistema sem impacto em quem depende dele. De quebra, você ganha monitoramento, métricas de uso e de tempo de resposta, e alertas no instante em que algo muda ou para de funcionar.

Obviamente isso tem um preço: mais complexidade e um novo ponto de falha. Mas deixa a vida de quem mantém o sistema muito melhor, e esse desacoplamento facilita demais a manutenção do seu CRM. O segredo está num único contrato: os canais pedem os pedidos deste cliente e recebem sempre o mesmo formato, não importa o que esteja por trás.

Clique pelas lojas aqui embaixo. O payload bruto muda de formato a cada uma, e o card que o atendente vê em cima nem pisca.

Troque a loja
Consumidor Nunca muda

Sidebar do CRM

ClienteAna Souza
Último pedidoR$ 249,90
StatusCliente ativo
Middleware

Normaliza VTEX em um único formato

Normalizar Monitoramento Logs Limite de taxa
Loja VTEX 
{
  "clientProfileData": {
    "firstName": "Ana"
  },
  "value": 24990,
  "orderId": "v1234-01"
}
Clique em uma loja. A API responde com um formato diferente a cada vez, mas o sidebar nunca muda, porque o middleware fala um único contrato.

Dicas importantes ao construir um middleware

Hospedagem na nuvem

Você não quer correr o risco de o sistema parar porque alguém tropeçou num fio do seu data center, ou porque a luz e a internet caíram. Nuvem custa, com certeza, mas estamos no Brasil, e nada funciona 100%. Nuvem também cai, claro que cai; só que a probabilidade é bem menor.

Ambiente de homologação / sandbox

Chame do jeito que as pessoas entendam do que se trata. Junte isso a um bom processo de CI/CD e o desenvolvimento fica muito mais leve: menos risco, deploy sem estresse. No controle de versão, trunk-based development. Se o seu time ainda usa Gitflow, mude o processo, ou mude de time.

Rate limit

Fique de olho no rate limit do seu CRM e das APIs externas. Um middleware sem limite de requisições pode travar a sua operação inteira. Desconfie de tudo e de todos: já tive cliente que fez um DDoS sem querer no próprio middleware e derrubou tudo.

Erros são informação

Num dos nossos primeiros projetos, a integração “funcionava”. Toda chamada voltava 200, o sidebar enchia de dados, todo mundo feliz. O que ninguém percebeu por um tempo: sempre que a API respondia com um 4xx ou 5xx, o código silenciosamente transformava aquilo em null e seguia em frente. O caminho feliz era impecável. O debug era doloroso. Levamos algumas semanas até corrigir isso e passar a devolver e tratar todos os tipos de erro que as APIs retornavam.

Retornar null numa falha não faz o erro sumir. Só o esconde num lugar onde você não vai olhar até o seu cliente reclamar.

IDs de ambiente chumbados

Aqui valem os aprendizados do Programador Pragmático. Não acople o seu middleware aos IDs dos ambientes em que ele roda. Em geral o sandbox e a produção têm os mesmos campos, mas cada campo carrega um ID diferente em cada ambiente. Seu código deve descobrir esses IDs de forma autônoma, o que facilita muito a manutenção.

Hostname

Tem uma decisão aqui que custa nada no primeiro dia e um fim de semana para consertar depois: o hostname. Todo App Service te entrega um nome padrão tipo seu-app.azurewebsites.net. Está ali, funciona, é tentador. Deixe o sidebar, o chatbot e principalmente os webhooks de entrada apontarem para ele e você chumbou, sem perceber, toda a sua integração a um servidor específico.

Aprendemos isso do jeito que todo mundo aprende: na dor. Uma migração do servidor para outra região mudou esse hostname padrão, e a gente sabia que essa troca teria que ser feita em todos os clientes que já consumiam esse middleware, um por um. A solução é simples, trivial e funciona: coloque um domínio próprio na frente desde o primeiro dia, algo como api.suaempresa.com, e aponte todo mundo para lá. Por trás desse nome, você move o app entre planos, regiões e instâncias, o que for; ninguém de fora percebe. O nome é o contrato, e você fica livre para trocar o servidor de lugar à vontade. Pois é, o pessoal que inventou o DNS lá nos anos 80 sabia das coisas.

Busque um middleware quando

  • mais de um consumidor precisa dos dados: sidebar, portal, chatbot e webhooks;
  • há mais de um backend, ou uma chance real de você trocar de fornecedor;
  • a API externa é limitada por taxa ou instável e precisa de tratamento cuidadoso e centralizado (essa é para você, Reclame Aqui e Movidesk);
  • você precisa de uma trilha de auditoria do que foi pedido e do que foi respondido;
  • existem segredos (chaves de API, tokens) que nunca podem chegar a um cliente. Você não vai colocar a sua chave de API num app Android para alguém descompilar o APK e ganhar acesso a todo o seu CRM.

Você pode ignorar, por enquanto, quando há um único consumidor, um único fornecedor que você não vai largar e nenhum segredo além do que o cliente pode guardar com segurança. Mas software nunca acaba: em algum momento, um canal novo vai aparecer: o novo portal do cliente, ou o app mobile que o marketing está doido para lançar. O importante é saber disso e tomar a decisão certa em cada momento.

O problema não é construir um middleware que você não precisava. É construir tarde demais, depois que três consumidores já chumbaram a API do e-commerce no código. Aí mudar fica caro.