Logistics, Delivery & Proof of Delivery (PoD) Architecture
Pakashop employs a robust logistics management and Proof of Delivery (PoD) system. This system integrates individual delivery agents, independent courier company fleets, and platform administrators under a secure validation model compliant with the Zambian Electronic Communications and Transactions (ECT) Act No. 4 of 2021.
1. Legal Compliance (Zambia ECT Act 2021)
Under the Zambian ECT Act, electronic signatures are granted the same legal status and admissibility as wet ink signatures. Pakashop's Proof of Delivery implements a two-tier framework to ensure compliance:
- Standard Electronic Signatures: Captured dynamically on the Delivery Agent's device using a touch-canvas digital signature pad.
- Advanced Electronic Signatures: Enhanced on the server side using SHA-256 tamper-evident cryptographic hashing. This binds the captured signature image, order details, and precise timestamp into an immutable record.
PoD Hash = SHA-256(orderId + signatureImageBase64 + signatoryName + capturedAt)
If any transaction details or signatures are altered post-confirmation, the recalculated hash fails to match the stored hash, immediately alerting operators to potential tampering.
2. Onboarding Workflow & Role Enforcement
To preserve platform integrity and separate commercial interests, the platform enforces strict role constraints and application state checks.
Role Constraints
- Platform Admins: Cannot register as delivery partners or merchants.
- Shop Owners (Merchants): Cannot apply to become delivery agents to prevent shipping conflicts of interest.
- Existing Delivery Agents: Locked out from applying again. If an application status is
PENDINGorACTIVE, they cannot submit a duplicate application.
The Application States
The application lifecycle is tracked via the DeliveryAgent database status field:
3. Two-Tier Proof of Delivery Flow
Deliveries are confirmed directly on the agent's device via a two-tier verification workflow:
Tier 1: PIN Verification
- Upon ordering, the buyer receives a unique 6-digit PIN via SMS/Email.
- At delivery, the agent enters this PIN. The monolith validates it. If correct, it returns
signatureRequired: truealong with a generatedsignatureIdtoken.
Tier 2: Signature Capture
- A canvas modal appears. The signing recipient inputs their full name and optional telephone number (essential for proxy/receptionist deliveries).
- The user signs on the touch pad.
- On save, the Base64 image and stroke logs are sent to the capture API. The backend computes the secure hash and advances the order state to
DELIVERED.
4. Courier Company Fleet Management
Courier Companies operate as independent delivery partners. They have access to a custom logistics operations dashboard where they can manage their own fleet:
- PACRA Business Validation: During registration, companies must provide their legal registered name and business registration number, subject to admin verification.
- Sub-agent Onboarding: Courier admins can invite and bind individual drivers to their company. Adding a sub-agent upgrades the driver user's role to
DELIVERY_AGENTand automatically links them to the parent company. - Removal Pipeline: Courier admins can dissolve bindings, removing sub-agents from their company fleet instantly.
5. Technical API Directory
Frontend Wrapper Library (src/lib/delivery.js)
Decoupled functions wrapping logistics backend endpoints:
| Function | Method & Endpoint | Description |
|---|---|---|
submitDeliveryApplication | POST /api/v1/delivery/apply | Submits agent or company applications. |
getMyAgentProfile | GET /api/v1/delivery/agent/me | Retrieves current user's delivery partner profile. |
agentToggleAvailability | PATCH /api/v1/delivery/agent/availability | Toggles driver availability state. |
agentGetDeliveries | GET /api/v1/delivery/agent/deliveries | Fetches active shipments assigned to the driver. |
agentConfirmDelivery | POST /api/v1/delivery/agent/confirm | Performs Tier-1 PIN verification. |
captureDigitalSignature | POST /api/v1/delivery/signature/:id/capture | Performs Tier-2 digital signature capture. |
courierGetAgents | GET /api/v1/delivery/courier/agents | Lists courier company sub-agents. |
courierAddAgent | POST /api/v1/delivery/courier/agents | Registers a sub-agent to the company. |
courierRemoveAgent | DELETE /api/v1/delivery/courier/agents/:id | Deletes a company sub-agent. |
adminGetApplications | GET /api/v1/delivery/admin/applications | Lists pending delivery partner applications. |
adminGetAgents | GET /api/v1/delivery/admin/agents | Lists all verified delivery agents. |
adminApproveAgent | PATCH /api/v1/delivery/admin/agents/:id/approve | Approves a pending application. |
adminRejectAgent | PATCH /api/v1/delivery/admin/agents/:id/reject | Rejects application with a specific reason. |
adminSuspendAgent | PATCH /api/v1/delivery/admin/agents/:id/suspend | Suspends an active delivery partner. |
adminActivateAgent | PATCH /api/v1/delivery/admin/agents/:id/activate | Re-activates a suspended delivery partner. |
6. Frontend Route Directory
/apply/delivery-agent: Partner onboarding page (dual-tab, drag-and-drop document uploaders)./agent/dashboard: Field driver view (availability controls, secure shipments feed, PIN/signature validation panels)./courier/dashboard: Fleet operator portal (metrics widgets, sub-agents listing directory, register driver forms)./platform-admin/delivery/applications: Admin panel (review pipelines, type filters, document previews, re-activation controls, custom rejection reason modal sheets).