MainaE677/-etims-integration-platform

A multi-tenant backend that integrates with Kenya Revenue Authority's eTIMS (Electronic Tax Invoice Management System) via its OSCU/VSCU system-to-system API. ## Demo A full walkthrough: onboard a tenant, submit an invoice, watch it fail safely when it can't reach a real KRA sandbox, and see that failure surface at every layer of the system. **1. Onboard a tenant** ```powershell Invoke-RestMethod -Uri "localhost" -Method Post ` -ContentType "application/json" ` -Body '{"kraPin": "P000123456A", "businessName": "Test Traders Ltd"}' ``` ``` id : 3c2c8ea0-7656-419d-a602-40b43ba0e9b4 kraPin : P000123456A businessName : Test Traders Ltd apiKey : etk_AeNsdI98hszHBFwyRxPNHD1K3bDs4sM-ksgjibiTiLY status : PENDING_ONBOARDING ``` **2. Submit an invoice** — accepted and queued immediately: ```powershell Invoke-RestMethod -Uri "localhost" -Method Post ` -ContentType "application/json" ` -Headers @{"X-API-Key"="etk_..."} ` -Body '{"externalReference": "ORDER-1001", "totalAmount": 1160.00, "vatAmount": 160.00}' ``` ``` id : b8b83b14-ebe9-4f29-95a6-03e03f341187 externalReference : ORDER-1001 status : PENDING totalAmount : 1160.00 vatAmount : 160.00 submissionAttempts : 0 ``` **3. It fails safely** — since no real KRA sandbox is configured, the worker retries with backoff, exhausts its attempts, and the message lands on the dead-letter queue instead of being lost: **4. The dashboard confirms it** — the same failure is visible through the platform's own API, not just buried in a queue: ```powershell Invoke-RestMethod -Uri "localhost" ` -Headers @{"X-API-Key"="etk_..."} ``` ``` countsByStatus failedInvoiceIds -------------- ---------------- @{FAILED=1} {b8b83b14-ebe9-4f29-95a6-03e03f341187} ``` This is the behavior the retry/DLQ design exists for: a tax-compliance system should never silently lose an invoice, even when the downstream API is unreachable.