A customer lands on your site and opens a ticket to check an order. Your support agent picks it up and needs the customer's purchase history. There are, broadly, three ways this goes: the bad, the good, and the ideal.
Bad. The agent leaves your CRM, logs into the e-commerce platform, types in the document number / email / order number, and searches. Copies the details, pastes them back, answers the customer.
Good. Your CRM already has an e-commerce app (one you installed from a marketplace, or one your dev team built), so the agent never switches tabs and sees the customer and order data on the same screen where they answer the ticket. That app talks straight to the e-commerce API. It works well. So well that your chatbot starts calling the same API, and your support portal gets a page where the customer types an order number and checks the status themselves.
This works great. Until the day it doesn't. Something breaks, the app dies, and you have no idea why. Now you've got 100 agents idle, or unproductive, because they've fallen back to the bad scenario: open the store's page and look up orders one by one. After a few years working with third-party APIs, I've seen this movie plenty. Clients calling at 2 a.m., on weekends, wanting to know what's going on.
Then there's the less catastrophic version: the company decides to switch e-commerce platforms. Now begins the slog of mapping every dependency and swapping APIs one by one. In our hypothetical, that means touching the portal, the chatbot, and probably rebuilding the app, because what you have was tailored to that one store. And the chatbot is the worst of them: the complexity explodes with property propagation and conditional logic. This is where a middleware starts to make sense.
CRM sidebar
Customer portal
Chatbot
Webhooks
One contract, one place
api.suaempresa.comCRM
E‑commerce
VTEX · Magento · WakeThe ideal scenario
Ideal. It's what the diagram above shows: one interface, one layer of abstraction. Your chatbot, your portal, and your app don't need to know which e-commerce you run. That gives you the freedom to swap the system out with no impact on the things that depend on it. As a bonus, you get monitoring, usage and response-time metrics, and alerts the moment something changes or stops working.
Obviously this has a price: more complexity and a new point of failure. But it makes life far better for whoever keeps the system running, and that decoupling makes your CRM enormously easier to maintain. The trick is a single contract: the channels ask for this customer's orders and always get back the same shape, no matter what sits behind it.
Click through the stores below. The raw payload changes shape with each one, and the card the agent sees on top never flinches.
CRM sidebar
Normalizes VTEX into one shape
{
"clientProfileData": {
"firstName": "Ana"
},
"value": 24990,
"orderId": "v1234-01"
}
Important tips when building a middleware
Cloud hosting
You don't want the system to go down because someone tripped over a cable in your data center, or the power and internet dropped. The cloud costs money, sure, but we're in Brazil, and nothing works 100% of the time. The cloud can go down too, of course it can; the odds are just far lower.
A staging / sandbox environment
Call it whatever makes it obvious what it is. Pair it with a solid CI/CD process and development gets much lighter: less risk, deploys without the stress. For version control, trunk-based development. If your team still runs Gitflow, change the process, or change teams.
Rate limits
Keep an eye on the rate limits of your CRM and your external APIs. A middleware with no request limits of its own can lock up your entire operation. Trust nothing and no one: I've had a client accidentally DDoS its own middleware and bring everything down.
Errors are information
On one of our first projects, the integration “worked.” Every call came back 200, the sidebar filled with data, everyone was happy. What nobody noticed for a while: whenever the API answered with a 4xx or 5xx, the code quietly turned it into null and moved on. The happy path was flawless. Debugging was agony. It took us a few weeks to fix it and start returning and handling every kind of error the APIs threw back.
Returning null on failure doesn't make the error go away. It just hides it somewhere you won't look until your customer complains.
Don't hard-code environment IDs
This one comes straight from The Pragmatic Programmer. Don't couple your middleware to the IDs of the environments it runs in. Sandbox and production usually have the same fields, but each field carries a different ID in each environment. Your code should discover those IDs on its own, which makes maintenance enormously easier.
The hostname
There's one decision here that costs nothing on day one and a weekend to fix later: the hostname. Every App Service hands you a default name like your-app.azurewebsites.net. It's right there, it works, it's tempting. Let the sidebar, the chatbot, and especially the inbound webhooks point at it, and you've quietly welded your whole integration to one specific server.
We learned this the way everyone learns it: the hard way. A server migration to another region changed that default hostname, and we knew that change would have to be made in every client already consuming that middleware, one by one. The fix is simple, trivial, and it works: put a custom domain you own in front from day one, something like api.yourcompany.com, and point everyone there. Behind that name you can move the app between plans, regions, and instances, whatever you like; nobody on the outside notices. The name is the contract, and you're free to move your server around as much as you want. Turns out the folks who invented DNS back in the 80s knew what they were doing.
Reach for a middleware when
- more than one consumer needs the data: sidebar, portal, chatbot, and webhooks;
- there's more than one backend, or a real chance you'll switch vendors;
- the external API is rate-limited or flaky and needs careful, central handling (this one's for you, Reclame Aqui and Movidesk);
- you need an audit trail of what was asked and what was answered;
- there are secrets (API keys, tokens) that must never reach a client. You're not going to drop your API key into an Android app for someone to decompile the APK and walk away with access to your whole CRM.
You can skip it, for now, when there's a single consumer, a single vendor you have no plans to leave, and no secrets beyond what the client can safely hold. But software is never finished: sooner or later a new channel shows up: the new customer portal, or the mobile app marketing is itching to launch. What matters is knowing that, and making the right call at each moment.
The problem isn't building a middleware you didn't need. It's building it too late, after three consumers have already hard-coded the e-commerce API. That's when change gets expensive.