Un cliente entra en tu sitio y abre un ticket para saber el estado del pedido. Tu agente de soporte recibe ese ticket y necesita acceder al historial de compras del cliente. Aquí tenemos, en general, tres escenarios: el malo, el bueno y el ideal.

Malo. El agente sale de tu CRM, inicia sesión en la plataforma de e-commerce, escribe el documento / correo / número de pedido y busca. Copia la información y le responde al cliente.

Bueno. Tu CRM ya tiene alguna app de e-commerce (que bajaste del marketplace o que armó tu equipo de desarrollo) para que el agente no tenga que cambiar de pestaña y vea los datos del cliente y del pedido en la misma pantalla en la que responde el ticket. Esa app habla directo con la API del e-commerce. Funciona bien. Tan bien que tu chatbot pasa a consumir la misma API, y tu portal de soporte gana una página donde el propio cliente escribe el número de pedido y consulta el estado.

Esto funciona muy bien. Hasta el día en que deja de funcionar. Algo se rompe, la app se muere y te quedas sin saber por qué. Ahí tienes 100 agentes parados, o improductivos, porque volvieron al escenario malo: abrir la página del e-commerce y consultar pedido por pedido. Después de algunos años trabajando con APIs de terceros, ya vi bastante esta película. Clientes llamando de madrugada, el fin de semana, queriendo entender qué está pasando.

También está la situación menos catastrófica: la empresa decide cambiar de e-commerce. Ahí empieza el proceso de mapear todas las dependencias y cambiar las APIs una por una. En nuestro escenario hipotético, sería meter mano en el portal, en el chatbot y probablemente rehacer la app, porque la que existe fue hecha a medida para aquel e-commerce. Y el chatbot es el más complicado de todos: la complejidad explota con la propagación de propiedades y las lógicas condicionales. Es ahí donde el middleware empieza a tener sentido.

Mapa del sistema
Consumidores Sistemas de registro

Sidebar del CRM

Portal del cliente

Chatbot

Webhooks

Middleware

Un contrato, un solo lugar

Normalizar Monitoreo Métricas Límite de tasa Alertas Secretos
Azure App Service · api.suaempresa.com

CRM

E‑commerce

VTEX · Magento · Wake
Alterna entre los dos escenarios. Sin middleware, cada canal tiene que conectarse a cada sistema. Con uno, todos pasan por un único punto de entrada.

El escenario ideal

Ideal. Es lo que muestra el dibujo de arriba: una interfaz única, una capa de abstracción. Tu chatbot, tu portal y tu app no necesitan saber cuál es tu e-commerce. Eso te da libertad para cambiar de sistema sin impacto en quien depende de él. De paso, ganas monitoreo, métricas de uso y de tiempo de respuesta, y alertas en el instante en que algo cambia o deja de funcionar.

Obviamente esto tiene un precio: más complejidad y un nuevo punto de falla. Pero le deja la vida mucho mejor a quien mantiene el sistema, y ese desacoplamiento facilita muchísimo el mantenimiento de tu CRM. El secreto está en un único contrato: los canales piden los pedidos de este cliente y reciben siempre el mismo formato, no importa lo que esté por detrás.

Haz clic por las tiendas de aquí abajo. El payload crudo cambia de formato en cada una, y la tarjeta que el agente ve arriba ni parpadea.

Cambia la tienda
Consumidor Nunca cambia

Sidebar del CRM

ClienteAna Souza
Último pedidoR$ 249,90
EstadoCliente activo
Middleware

Normaliza VTEX en un único formato

Normalizar Monitoreo Logs Límite de tasa
Tienda VTEX 
{
  "clientProfileData": {
    "firstName": "Ana"
  },
  "value": 24990,
  "orderId": "v1234-01"
}
Haz clic en una tienda. Su API responde con un formato distinto cada vez, pero el sidebar nunca cambia, porque el middleware habla un solo contrato.

Consejos importantes al construir un middleware

Hosting en la nube

No quieres correr el riesgo de que el sistema se caiga porque alguien tropezó con un cable de tu data center, o porque se cortó la luz y el internet. La nube cuesta, sin duda, pero estamos en Brasil, y nada funciona 100%. La nube también se cae, claro que se cae; solo que la probabilidad es mucho menor.

Ambiente de homologación / sandbox

Llámalo como la gente entienda de qué se trata. Súmale un buen proceso de CI/CD y el desarrollo se vuelve mucho más liviano: menos riesgo, deploy sin estrés. En el control de versiones, trunk-based development. Si tu equipo todavía usa Gitflow, cambia el proceso, o cambia de equipo.

Rate limit

Mantén un ojo en el rate limit de tu CRM y de las APIs externas. Un middleware sin límite de solicitudes puede trabar tu operación entera. Desconfía de todo y de todos: ya tuve un cliente que le hizo un DDoS sin querer a su propio middleware y tiró todo abajo.

Los errores son información

En uno de nuestros primeros proyectos, la integración “funcionaba”. Toda llamada volvía 200, el sidebar se llenaba de datos, todos felices. Lo que nadie notó por un tiempo: siempre que la API respondía con un 4xx o 5xx, el código silenciosamente transformaba eso en null y seguía adelante. El camino feliz era impecable. El debug era doloroso. Nos llevó algunas semanas corregir eso y pasar a devolver y tratar todos los tipos de error que las APIs retornaban.

Devolver null en una falla no hace que el error desaparezca. Solo lo esconde en un lugar donde no vas a mirar hasta que tu cliente reclame.

IDs de ambiente hardcodeados

Aquí valen los aprendizajes del Programador Pragmático. No acoples tu middleware a los IDs de los ambientes en los que se ejecuta. En general el sandbox y la producción tienen los mismos campos, pero cada campo lleva un ID distinto en cada ambiente. Tu código debe descubrir esos IDs de forma autónoma, lo que facilita muchísimo el mantenimiento.

Hostname

Hay una decisión aquí que no cuesta nada el primer día y cuesta un fin de semana arreglar después: el hostname. Todo App Service te entrega un nombre por defecto tipo tu-app.azurewebsites.net. Está ahí, funciona, es tentador. Deja que el sidebar, el chatbot y sobre todo los webhooks de entrada apunten ahí y ya dejaste amarrada, sin darte cuenta, toda tu integración a un servidor específico.

Aprendimos esto como lo aprende todo el mundo: a los golpes. Una migración del servidor a otra región cambió ese hostname por defecto, y sabíamos que ese cambio tendría que hacerse en todos los clientes que ya consumían ese middleware, uno por uno. La solución es simple, trivial y funciona: pon un dominio propio adelante desde el primer día, algo como api.tuempresa.com, y apunta a todo el mundo ahí. Detrás de ese nombre, mueves la app entre planes, regiones e instancias, lo que sea; nadie de afuera se entera. El nombre es el contrato, y quedas libre para mover el servidor de lugar cuando quieras. Y sí, la gente que inventó el DNS allá en los años 80 sabía lo que hacía.

Busca un middleware cuando

  • más de un consumidor necesita los datos: sidebar, portal, chatbot y webhooks;
  • hay más de un backend, o una chance real de que cambies de proveedor;
  • la API externa está limitada por tasa o es inestable y necesita un tratamiento cuidadoso y centralizado (esta va para ustedes, Reclame Aqui y Movidesk);
  • necesitas una traza de auditoría de lo que se pidió y de lo que se respondió;
  • existen secretos (claves de API, tokens) que nunca pueden llegar a un cliente. No vas a poner tu clave de API en una app Android para que alguien descompile el APK y se quede con acceso a todo tu CRM.

Puedes ignorarlo, por ahora, cuando hay un único consumidor, un único proveedor que no vas a dejar y ningún secreto más allá de lo que el cliente puede guardar con seguridad. Pero el software nunca termina: en algún momento va a aparecer un canal nuevo: el nuevo portal del cliente, o la app para celular que marketing se muere por lanzar. Lo importante es saberlo y tomar la decisión correcta en cada momento.

El problema no es construir un middleware que no necesitabas. Es construirlo demasiado tarde, después de que tres consumidores ya dejaron la API del e-commerce amarrada en el código. Ahí cambiar sale caro.