🚀 QOSS Backend API

OpenAPI 3.0 Documentation

📚 Swagger UI | ReDoc | RapiDoc | JSON Spec | YAML Spec

🔐 Authentication

POST /api/v1/auth/login
Authenticate user and get JWT token
POST /api/v1/auth/register
Register a new user account
POST /api/v1/auth/verify
Verify JWT token validity
POST /api/v1/auth/refresh
Refresh access token

🏢 Companies Protected

GET /api/v1/companies
List all companies (with pagination)
POST /api/v1/companies
Create a new company
GET /api/v1/companies/:id
Get company by ID
PUT /api/v1/companies/:id
Update company
DELETE /api/v1/companies/:id
Delete company

🌐 Domains Protected

GET /api/v1/domains
List all domains
POST /api/v1/domains
Create a new domain
GET /api/v1/domains/:id
Get domain by ID
PUT /api/v1/domains/:id
Update domain
DELETE /api/v1/domains/:id
Delete domain

📦 Modules Protected

GET /api/v1/modules
List all modules
POST /api/v1/modules
Create a new module
GET /api/v1/modules/:id
Get module by ID
PUT /api/v1/modules/:id
Update module
DELETE /api/v1/modules/:id
Delete module

⚡ Features Protected

GET /api/v1/features
List all features
POST /api/v1/features
Create a new feature
GET /api/v1/features/:id
Get feature by ID
PUT /api/v1/features/:id
Update feature
DELETE /api/v1/features/:id
Delete feature

📱 B2C (Business to Customer) Protected

📊 Table Structure

b2c_transactions - M-Pesa B2C payment records
• transaction_id (UUID) - Primary key
• company_id (INT) - FK to companies
• phone_number (VARCHAR) - Recipient phone
• amount (DECIMAL) - Payment amount
• status (VARCHAR) - pending, success, failed
• created_at (TIMESTAMP) - Transaction timestamp

🔌 API Endpoints

POST /api/v1/b2c/send-payment
Initiate B2C payment to phone number
GET /api/v1/b2c/transactions
List all B2C transactions for company
GET /api/v1/b2c/transactions/:id
Get B2C transaction details
POST /api/v1/b2c/callback
M-Pesa B2C payment callback handler

🎨 Frontend Components (qoss-web)

Components:
• B2CPaymentForm - Send payment form component
• B2CTransactionsList - Transaction history table
• B2CTransactionDetail - Transaction details modal
• B2CAnalytics - B2C payment analytics dashboard
Pages:
• src/pages/B2C.jsx - Main B2C page
• Route: /dashboard/b2c

� M-Pesa Credentials Protected

GET /api/v1/safaricom-credentials/company/:company_id
List all M-Pesa credentials for a company
POST /api/v1/safaricom-credentials/company/:company_id
Create a new M-Pesa credential
GET /api/v1/safaricom-credentials/:id
Get credential by ID
PUT /api/v1/safaricom-credentials/:id
Update credential
DELETE /api/v1/safaricom-credentials/:id
Deactivate credential
POST /api/v1/safaricom-credentials/:id/activate
Activate credential
GET /api/v1/safaricom-credentials/company/:company_id/paybill/:paybill_number
List credentials by paybill number
GET /api/v1/safaricom-credentials/company/:company_id/type/:type
List credentials by type (paybill, buygoods, b2c)
GET /api/v1/safaricom-credentials/company/:company_id/paybill/:paybill_number/type/:type/active
Get active credential for paybill/type combination

�👥 Users Protected

GET /api/v1/users
List all users
GET /api/v1/users/:id
Get user by ID
PUT /api/v1/users/:id
Update user

🐛 Error Tracking Protected

POST /api/v1/errors/capture
Capture a new error event
GET /api/v1/errors/issues
List all error issues
GET /api/v1/errors/issues/:id
Get error issue details
GET /api/v1/errors/stats
Get error statistics

📊 Lead Management Protected

GET /api/v1/lead-management/config
Retrieve lead management configuration
PUT /api/v1/lead-management/config
Update configuration settings
GET /api/v1/lead-management/scoring-rules
List scoring rules (paginated)
POST /api/v1/lead-management/scoring-rules
Create new scoring rule
PUT /api/v1/lead-management/scoring-rules/{id}
Update specific rule
DELETE /api/v1/lead-management/scoring-rules/{id}
Delete rule

� M-Pesa Callbacks

POST /api/v1/mpesa/callback/payment
M-Pesa payment callback handler
POST /api/v1/mpesa/callback/balance
M-Pesa balance inquiry callback handler
POST /api/v1/mpesa/callback/transaction-status
M-Pesa transaction status callback handler
POST /api/v1/mpesa/callback/reversal
M-Pesa reversal callback handler
POST /api/v1/mpesa/callback/timeout
M-Pesa transaction timeout callback handler
POST /api/v1/mpesa/callback/validation
M-Pesa validation callback handler
POST /api/v1/mpesa/callback/confirmation
M-Pesa confirmation callback handler
POST /api/v1/mpesa/callback/reconciliation
M-Pesa reconciliation callback handler
POST /api/v1/mpesa/callback/settlement
M-Pesa settlement callback handler
POST /api/v1/mpesa/callback/fraud-alert
M-Pesa fraud alert callback handler
POST /api/v1/mpesa/callback/regulatory-report
M-Pesa regulatory report callback handler

�📊 Metrics

GET /health
Health check endpoint
GET :9090/metrics
Prometheus metrics (separate port)