Courier Integration Service

The CIS acts as the single source of truth for all third-party courier-related communication. It receives fulfillment requests from the Main Platform, dispatches them to the appropriate courier API, and processes incoming webhooks to update order statuses in real time.

• Feature 1 - Multi-Courier Support (Bosta, ShipBlu and more).
• Feature 2 - Webhook Ingestion & Status Synchronization.
• Feature 3 - Order Dispatching.
• Feature 4 - Error Logging & Retry Mechanisms.
• Feature 5 - Rate Limiting & Security Hardening.

1. Fulfillment Trigger - The Main Platform sends a "shipment dispatch" request to the CIS.
2. Courier Dispatch - The CIS forwards the request to the correct courier provider API.
3. Waybill Generation/Fetching - The CIS generates a waybill for the shipment; either fetches the third-party waybill or generates a Turuq waybill.
4. Webhook Receipt - The courier sends status update webhooks back to the CIS.
5. Status Update - The CIS processes the webhook and updates the order status on the Main Platform.

• Reliability - Ensuring webhook delivery and retry logic for failed courier API calls.
• Status Mapping - Normalizing different courier status codes into Turuq's unified order lifecycle.
• Concurrency - Handling high-volume concurrent webhook events without race conditions.
• Timeout Management - Preventing H12 Heroku timeouts via async processing patterns.

• Runtime: Node.js
• Framework: NestJS
• Language: TypeScript
• Database: MongoDB
• Authentication: Clerk
• Validation: class-validator, class-transformer

• v1.0.0 - Initial release with Bosta courier support.
• v1.0.2 - Bug Fixes for Bosta's modified auth.
• v1.1.0 - Added RBAC and multi-worker support.
• v1.1.1 - Added ShipBlu Support and Hybrid Waybill Strategy.