BluEclipse
☰
BluEclipse platform infrastructure
Different Couriers. Different APIs. One Delivery Layer.
Integrating one courier is a task. Integrating several is an architecture decision — and getting it wrong means every checkout, tracking page and backend function slowly fills up with provider-specific special cases.
- Category
- Logistics and API infrastructure
- Core technologies
- TypeScript, Node.js, REST APIs, webhooks, Firebase, Google Maps and third-party courier APIs
- Built for
- Vendorah's logistics infrastructure
BluEclipse's Multi-Courier Infrastructure gives an application one delivery model to work with, and keeps the differences between courier providers inside a layer built to absorb them.
Adding one courier to an application is straightforward. You read their documentation, write the integration, and move on. Adding several is a different problem entirely, because the second provider does not simply double the work — it changes what kind of work it is.
Every provider is free to have its own opinion about:
- Addresses
- Parcel dimensions
- Quotations
- Service types
- Collection requests
- Tracking numbers
- Status updates
- Labels
- Delivery confirmation
- Authentication
- Errors
- Webhooks
Without somewhere to put those differences, they do not stay put. They spread. The checkout flow starts asking which provider an order is going through. Tracking pages grow separate status handling. Backend functions begin passing around different shapes depending on who is carrying the parcel. Every provider you add makes every part of the application slightly worse, and the cost of adding the next one goes up rather than down.
The rest of the platform should not know who is carrying the parcel
That sentence is the entire design. Each courier integration translates between a provider's own API and one common internal delivery model, so the application works in terms of what it is trying to do rather than who it is talking to.
Platform
Checkout
Orders
Tracking
Transactions
Unified delivery layerOne model: quote, ship, track, confirm
Provider adapters
Aramex
ShipLogic
Business-managed delivery
Customer collection
Above the layer, the operations are always the same ones, in the same order:
- Quote
- Select service
- Create shipment
- Collect
- Track
- Deliver
- Confirm
Below it, each adapter deals with whatever its provider actually requires. Courier-specific complexity does not disappear — that would be a nice claim and an untrue one — it is simply confined to the one place built to hold it.
Translating vocabulary
Providers rarely describe the same thing the same way. One calls a shipment a consignment; another works in waybills. Service levels, parcel structures, tracking states, pricing responses, collection details and address formats can all differ, and none of those differences mean anything to the business logic that has to react to them.
One provider may report a delivery as DEL, another as Delivered, another through a numeric status code. The application should not contain three branches for that. External events are translated into one internal status, and the rest of the platform only ever sees the internal one.
Every status you fail to normalise at the boundary becomes a conditional somewhere it does not belong.
Comparing options instead of committing to one
Once several providers speak the same internal language, something becomes possible that a single integration cannot offer: comparison. Shipment details can be sent to supported providers, the available services collected, the responses normalised, and the options handed back to the application in one consistent format.
That is the foundation for choosing on estimated delivery time, service type, availability or price — and it makes the courier a decision the platform makes per shipment, rather than a dependency baked into checkout.
One shipment, one internal record
When an option is selected, the same infrastructure coordinates creation with the relevant provider while the application keeps its own delivery record. That record is what ties the shipment to:
- Customer
- Seller
- Order
- Parcel information
- Courier provider
- Tracking reference
- Service type
- Current status
- Delivery events
Keeping it internal is what stops logistics from drifting out of the data model and becoming an external process the application merely links to. A shipment that exists only in a courier's system is something you look up. A shipment that exists in yours is something you can build on.
Tracking as one stream
Tracking gets considerably more useful the moment the platform stops redirecting people to a courier's website. Courier events can instead be processed by the backend and translated into internal delivery states, so the lifecycle reads the same regardless of who is carrying the parcel:
- Shipment created
- Awaiting collection
- Collected
- In transit
- Out for delivery
- Delivered
Where providers support them, webhooks carry those events rather than the backend polling constantly for changes. An incoming status change can be matched to its shipment, applied to the delivery state, and allowed to trigger whatever should follow — a notification, an order update, an internal workflow, or a change in the financial state of a protected transaction.
That last one is the difference between a tracking screen and infrastructure. A delivery event that only updates a page is information. A delivery event that can move a transaction is part of the system.
Logistics connected to transactions
In Vendorah's architecture, delivery and payment are not separate universes. For protected transactions, confirmation that an order actually arrived may form part of the conditions required before that transaction is allowed to progress toward completion or payout.
- Order
- Shipment
- Tracking
- Delivery
- Transaction completion
- Payout
The courier layer feeds trusted delivery information back into that lifecycle instead of leaving two systems running alongside each other with no understanding of one another. It is the same argument as normalising statuses, one level up: information is only worth collecting if something can act on it.
Not every order goes through a courier
The infrastructure was also built around a fact that is easy to design past: plenty of orders never touch a national courier at all. Vendorah supports courier delivery, business-managed delivery and customer collection, which meant modelling fulfilment as the general case and the courier waybill as one specific instance of it.
Had it been built the other way round — assuming every transaction produces a waybill — the two fulfilment models that do not would each have become an exception threaded through the order and transaction logic.
Delivery starts before the API call
Address data, distance calculations, route information, delivery areas and fulfilment availability all shape which options should be offered in the first place. Google Maps integration provides that geographic layer, letting the platform work with structured locations and route-aware workflows — which matters most when third-party couriers and local business delivery are being offered side by side in the same checkout.
More than a shipping API
A major goal was that adding another courier should not require rebuilding the commerce platform. A new provider arrives as another adapter against the same internal model: the integration still has to understand that provider's API, but checkout, orders, tracking interfaces and transaction workflows carry on talking to the layer exactly as before.
That is what separates integrating a courier from building logistics infrastructure. Orders know about shipments. Customers get tracking. Vendors manage fulfilment. The transaction system reacts to delivery. Notifications follow automatically. And the next provider is a day of work rather than a refactor.
South African businesses tend to need several logistics options depending on location, parcel size, cost, urgency and customer preference — so the workflows here are built around providers and delivery models relevant to that market, including integrations such as Aramex and broader work around ShipLogic.
Built by BluEclipse. Developed as part of the Vendorah platform infrastructure.
For commerce platforms
If courier-specific logic has started leaking into your checkout and your order model, the fix is an abstraction, and it is cheaper now than after the next provider.
For technology clients
API normalisation, webhook processing, real-time tracking and delivery confirmation wired into the systems that depend on it.