04 / Case Study
ONDC Logistics Network Integration
Protocol-compliant order, fulfillment, and grievance APIs certifying a logistics provider onto India's Open Network for Digital Commerce.
The problem
ONDC is a shared, government-backed protocol for e-commerce — joining it means implementing a specification exactly, not just building an API that works for one client. Every participant on the network has to interoperate with every other participant's implementation, and certification requires proving that against real partner traffic.
Architecture
NestJS and TypeORM over MySQL, structured around the ONDC protocol's own domains rather than around the business. Pre-order covers search, quotation (the pricing step behind /select), init, confirm, and BPP fulfillment. Post-order covers order, status, fulfillment status, tracking, cancellation, updates, and support. IGM handles grievances as issue and issue-status flows, and RSP handles receiver-side reconciliation. Every inbound request is cryptographically signature-verified before it reaches any business logic, and a trio of stage, transaction-stage, and transaction services record each step of an order's protocol lifecycle so the whole exchange is reconstructable after the fact.
The piece that made this tractable is a separate adapter layer sitting between the protocol surface and the aggregator's own carrier API, with its own exception filter and logging interceptor. Protocol vocabulary lives on one side of that boundary and the carrier's existing API on the other. Without it, ONDC compliance would have meant rewriting a working logistics platform to speak a new dialect; with it, certification became an integration problem instead of a migration.
Decisions
Build to the spec, verify against partners
Rather than integrate against one counterparty, the work meant implementing the protocol generically and then certifying it in practice with 5+ partner organisations, since ONDC compliance is defined by interoperability, not a single integration test.
Audit trail as a first-class concern
Stage and transaction-stage services plus daily-rotated audit logging exist because a protocol built for regulatory-grade commerce needs every state transition traceable after the fact, not just at request time. When a partner disputes what was sent, the answer has to be retrievable months later.
Translate at the edge, don't rewrite the core
An adapter layer with its own error handling and logging maps between ONDC's vocabulary and the carrier's existing API. Keeping the translation at the boundary meant the logistics platform underneath never had to become ONDC-shaped — which is why the integration shipped at all.