YeboHub

Appearance

YeboMart Routes — Complete API Map ​

All API endpoints with methods, authentication requirements, and middleware.

Base URL ​

Production: https://api.yebomart.com/api/v1

Route Index ​

typescript
// src/routes/index.ts
router.use('/auth', authRoutes);
router.use('/shops', shopRoutes);
router.use('/products', productRoutes);
router.use('/sales', saleRoutes);
router.use('/stock', stockRoutes);
router.use('/users', userRoutes);
router.use('/staff', userRoutes);       // Alias
router.use('/reports', reportRoutes);
router.use('/ai', aiRoutes);
router.use('/license', licenseRoutes);
router.use('/expenses', expenseRoutes);
router.use('/customers', customerRoutes);
router.use('/audit', auditRoutes);
router.use('/admin', adminRoutes);
router.use('/upload', uploadRoutes);
router.use('/returns', returnRoutes);
router.use('/suppliers', supplierRoutes);
router.use('/pricing', pricingRoutes);
router.use('/billing', billingRoutes);

Authentication Routes ​

Base: /api/v1/auth

MethodEndpointAuthMiddlewareDescription
POST/register—authLimiter, validateRequestRegister new shop
POST/login—authLimiter, validateRequestOwner login
POST/login/user—authLimiter, validateRequestStaff PIN login
POST/refresh—authLimiter, validateRequestRefresh tokens
GET/me✓authMiddlewareGet current user

Request/Response Examples ​

typescript
// POST /auth/register
{
  "name": "Best Tuckshop",
  "ownerName": "John Dlamini",
  "phone": "+26876123456",
  "password": "securepin",
  "businessType": "tuckshop",
  "assistantName": "Sibo"
}

// Response
{
  "success": true,
  "data": {
    "shop": { "id": "...", "name": "Best Tuckshop", "tier": "LITE" },
    "accessToken": "eyJ...",
    "refreshToken": "eyJ..."
  }
}

Shop Routes ​

Base: /api/v1/shops

MethodEndpointAuthMiddlewareDescription
GET/types——List business types
GET/config✓authMiddlewareGet shop config
GET/:id✓authMiddlewareGet shop details
PATCH/:idOwnerownerAuth, validateRequestUpdate shop
GET/:id/stats✓authMiddlewareGet shop stats

Product Routes ​

Base: /api/v1/products

MethodEndpointAuthMiddlewareDescription
GET/✓authMiddleware, validateQueryList products
POST/ManagermanagerAuth, checkProductLimit, validateRequestCreate product
GET/categories✓authMiddlewareList categories
GET/exportManagermanagerAuthExport CSV
POST/bulk/importManagermanagerAuth, validateRequestBulk import
POST/bulk/updateManagermanagerAuth, validateRequestBulk update
GET/barcode/:barcode✓authMiddlewareLookup by barcode
GET/:id✓authMiddlewareGet product
PATCH/:idManagermanagerAuth, validateRequestUpdate product
DELETE/:idManagermanagerAuthSoft delete

Query Parameters ​

typescript
// GET /products
{
  page: number;       // Default: 1
  limit: number;      // Default: 20, max: 100
  search: string;     // Search name, barcode, SKU
  category: string;   // Filter by category
  lowStock: boolean;  // Only low stock items
  isActive: boolean;  // Default: true
}

Sales Routes ​

Base: /api/v1/sales

MethodEndpointAuthMiddlewareDescription
GET/✓authMiddleware, validateQueryList sales
POST/✓authMiddleware, posLimiter, trackUsage, validateRequestCreate sale
GET/daily-summary✓authMiddlewareToday's summary
GET/search/receipt✓authMiddlewareFind by receipt
POST/email-receipt✓authMiddlewareEmail receipt
GET/:id✓authMiddlewareGet sale
POST/:id/voidManagermanagerAuth, validateRequestVoid sale

Create Sale Request ​

typescript
// POST /sales
{
  "items": [
    { "productId": "clx...", "quantity": 2, "discount": 0 },
    { "productId": "clx...", "quantity": 1 }
  ],
  "paymentMethod": "CASH",
  "amountPaid": 100,
  "discount": 5
}

Stock Routes ​

Base: /api/v1/stock

MethodEndpointAuthMiddlewareDescription
GET/✓authMiddlewareGet stock levels
GET/alerts✓authMiddlewareLow stock alerts
GET/movements✓authMiddleware, validateQueryMovement history
POST/adjustManagermanagerAuth, trackUsage, validateRequestAdjust stock
POST/receiveManagermanagerAuth, trackUsage, validateRequestBulk restock

Stock Adjustment Request ​

typescript
// POST /stock/adjust
{
  "productId": "clx...",
  "type": "DAMAGED",
  "quantity": -3,
  "note": "Broken during delivery"
}

AI Routes ​

Base: /api/v1/ai

MethodEndpointAuthMiddlewareDescription
POST/chat✓authMiddleware, requireFeature('ai_assistant'), checkAiUsage, aiLimiter, validateRequestChat with AI
POST/voice✓authMiddleware, requireFeature('ai_assistant'), checkAiUsage, aiLimiter, validateRequestVoice query
GET/insights✓authMiddleware, checkAiUsage, aiLimiterGet insights
GET/slow-movers✓authMiddleware, checkAiUsage, aiLimiterSlow products
GET/summary✓authMiddleware, checkAiUsage, aiLimiterBusiness summary

AI Chat Request ​

typescript
// POST /ai/chat
{
  "message": "What products aren't selling?"
}

// Response
{
  "success": true,
  "data": {
    "message": "3 products are barely moving:\n• Old Chips - 2 sold...",
    "assistantName": "Yebo"
  }
}

Report Routes ​

Base: /api/v1/reports

MethodEndpointAuthMiddlewareDescription
GET/summaryManagerauthMiddleware, managerAuthOverview stats
GET/dailyManagerauthMiddleware, managerAuthDaily report
GET/weeklyManagerauthMiddleware, managerAuthWeekly report
GET/productsManagerauthMiddleware, managerAuthProduct performance
GET/staffManagerauthMiddleware, managerAuthStaff performance

User/Staff Routes ​

Base: /api/v1/users (aliased as /api/v1/staff)

MethodEndpointAuthMiddlewareDescription
GET/✓authMiddlewareList staff
POST/OwnerownerAuth, checkUserLimit, validateRequestCreate staff
GET/:id✓authMiddlewareGet staff
GET/:id/stats✓authMiddlewareStaff stats
GET/:id/detail✓authMiddlewareStaff details
PATCH/:id✓authMiddleware, validateRequestUpdate staff
DELETE/:idOwnerownerAuthDelete staff

Customer Routes ​

Base: /api/v1/customers

MethodEndpointAuthMiddlewareDescription
GET/✓authMiddlewareList customers
POST/✓authMiddleware, validateRequestCreate customer
GET/:id✓authMiddlewareGet customer
PATCH/:idManagermanagerAuthUpdate customer
POST/:id/credit✓authMiddleware, validateRequestAdd credit

Return Routes ​

Base: /api/v1/returns

MethodEndpointAuthMiddlewareDescription
GET/✓authMiddleware, validateQueryList returns
POST/✓authMiddleware, validateRequestCreate return
GET/:id✓authMiddlewareGet return
POST/:id/processManagermanagerAuth, validateRequestProcess return

Supplier Routes ​

Base: /api/v1/suppliers

MethodEndpointAuthMiddlewareDescription
GET/✓authMiddlewareList suppliers
POST/ManagermanagerAuth, validateRequestCreate supplier
GET/:id✓authMiddlewareGet supplier
PATCH/:idManagermanagerAuthUpdate supplier
DELETE/:idManagermanagerAuthDelete supplier
POST/:id/productsManagermanagerAuthLink product
GET/:id/orders✓authMiddlewareSupplier's POs

Billing Routes ​

Base: /api/v1/billing

MethodEndpointAuthMiddlewareDescription
GET/plansOptionaloptionalAuthGet pricing plans
POST/checkout✓authMiddlewareCreate checkout
POST/webhook—express.rawStripe webhook

Checkout Request ​

typescript
// POST /billing/checkout
{
  "tier": "BUSINESS",
  "successUrl": "https://app.yebomart.com/billing/success",
  "cancelUrl": "https://app.yebomart.com/billing"
}

// Response
{
  "success": true,
  "data": {
    "sessionId": "cs_test_...",
    "url": "https://checkout.stripe.com/..."
  }
}

Admin Routes ​

Base: /api/v1/admin

MethodEndpointAuthMiddlewareDescription
POST/login—validateRequestAdmin login
GET/dashboardAdminauthenticateAdminDashboard stats
GET/shopsAdminauthenticateAdminList all shops
GET/shops/:idAdminauthenticateAdminGet shop
PATCH/shops/:id/statusAdminauthenticateAdminUpdate status
DELETE/shops/:idAdminauthenticateAdminDelete shop
PUT/subscriptions/:idAdminauthenticateAdminUpdate subscription
GET/usersAdminauthenticateAdminList all users
GET/users/:idAdminauthenticateAdminGet user
GET/subscriptionsAdminauthenticateAdminList subscriptions

License Routes ​

Base: /api/v1/license

MethodEndpointAuthMiddlewareDescription
GET/status✓authMiddlewareLicense status
POST/activate✓authMiddlewareActivate license
POST/trial✓authMiddlewareStart trial

Pricing Routes (Public) ​

Base: /api/v1/pricing

MethodEndpointAuthMiddlewareDescription
GET/countries——List supported countries
GET/plans——All pricing plans
GET/plans/:country——Country-specific plans

Upload Routes ​

Base: /api/v1/upload

MethodEndpointAuthMiddlewareDescription
POST/image✓authMiddleware, multerUpload image
DELETE/image/:key✓authMiddlewareDelete image

Expense Routes ​

Base: /api/v1/expenses

MethodEndpointAuthMiddlewareDescription
GET/✓authMiddlewareList expenses
POST/ManagermanagerAuth, validateRequestCreate expense
GET/:id✓authMiddlewareGet expense
PATCH/:idManagermanagerAuthUpdate expense
DELETE/:idManagermanagerAuthDelete expense

Audit Routes ​

Base: /api/v1/audit

MethodEndpointAuthMiddlewareDescription
GET/ManagerauthMiddleware, managerAuthList audit logs
GET/:idManagerauthMiddleware, managerAuthGet log entry

Rate Limits ​

typescript
// Different limits for different route types
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15 minutes
  max: 10,                    // 10 requests per window
  message: 'Too many auth attempts'
});

const posLimiter = rateLimit({
  windowMs: 60 * 1000,       // 1 minute
  max: 60,                    // 60 sales per minute
  message: 'POS rate limit exceeded'
});

const aiLimiter = rateLimit({
  windowMs: 60 * 1000,       // 1 minute
  max: 10,                    // 10 AI queries per minute
  message: 'AI rate limit exceeded'
});

Error Responses ​

All errors follow the standard format:

typescript
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "phone", "message": "Phone is required" }
    ]
  }
}

Common Error Codes ​

CodeHTTP StatusDescription
VALIDATION_ERROR400Request validation failed
UNAUTHORIZED401Missing or invalid token
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
CONFLICT409Resource conflict (duplicate)
RATE_LIMITED429Too many requests
SERVER_ERROR500Internal server error

One chat. Everything done.

© 2026 Omevision Ltd.