Last mile · Kazakhstan
Fast Delivery — courier platform for Kaspi stores
A logistics platform for Kaspi.kz stores: order import, courier dispatch, routes, thermal labels, returns, and public shipment tracking.
At the time of this case study
110 000+
- orders in the system
- 110,000+
- stores
- ≈90
- workspaces
- 4
- interface languages
- 2
One product · four roles
Logistics across four interfaces
Each participant has a different pace and data need, yet the order remains a single record from Kaspi import to confirmed handoff.
- 01
Map control
Dispatcher
The city as a working map
Real-time couriers, zone-based assignment, Active / Archive views, and operating analytics.
- 02
Order desk
Store
From import to label
New Kaspi orders, statuses, returns, and thermal labels containing the actual item data.
- 03
Courier flow
Courier
A day route in the pocket
Sequenced stops, QR acceptance, a handoff code, and delivery confirmation.
- 04
Public tracking
Recipient
Status without an account
A public tracking page opens by order number and shows the current delivery state.
Order route
The digital flow ends with a physical handoff
- 01
Kaspi Shop API
- 02
Store workspace
- 03
Items and label
- 04
Zone and courier
- 05
QR acceptance
- 06
Handoff code
- 07
Confirmation
- 08
Public status
Integration field notes
Kaspi Shop API had to be learned through the live merchant portal
Observed API behavior shaped the architecture more than the available documentation. Four findings became explicit system rules.
One phoneAlias across hundreds of orders
The field was a shared Kaspi proxy line with an extension after the comma, not the buyer’s direct phone number.
The product code lives elsewhere
It comes from a separate items endpoint and is loaded lazily right before label printing.
History has a hard boundary
Kaspi API returns only the latest 14 days of history; earlier orders are unavailable through it.
The error hides the cause
A wrong X-Merchant-Uid returns the same 401 as an expired token, so the status code alone does not reveal the cause.
Geography + physical operations
The map, zones, and label belong to one order model
PostGIS stores spatial rules, Leaflet gives dispatchers a live operating picture, and PDFs, barcodes, and QR codes connect the digital order to the physical parcel.
- PostGIS
- assignment zones and spatial data
- Leaflet
- courier and order map
- PDF + barcodes
- thermal printing at the store
- Telegram alerts
- technical signals for the team
Product stack
Backend, web interfaces, and printing work as one system
Backend & operations
- NestJS
- TypeScript
- PostgreSQL
- PostGIS
- TypeORM
- Redis
- BullMQ
- pdfkit
- bwip-js
- qrcode
- Telegram Bot API
Interfaces & map
- Next.js 15
- App Router
- TanStack Query
- next-intl
- Leaflet
- Tailwind CSS
- Radix UI
Need to connect an online order to an offline operation?