Flocci API Documentation

📋 Table of Contents

🔐 Authentication

• POST /api/signup - User registration
• POST /api/login - User authentication
• GET /api/auth/session - Session validation
• POST /api/auth/session - Logout
• GET /api/auth/google - Google OAuth
• GET /api/auth/callback - OAuth callback

💳 Payments

• POST /api/payments/initiate - Start payment
• POST /api/payments/callback - PayU callback
• GET /api/payments/success - Success page
• GET /api/payments/failure - Failure page

👑 Admin

• GET /api/admin/dashboard - Analytics
• GET /api/admin/monitoring - System health
• GET /api/admin/rate-limits - Rate limits

📧 Contact

• POST /api/contact - General contact
• POST /api/company/contact - Company contact
• POST /api/careers - Job applications

🔑 Authentication

Session-based Authentication

Most endpoints require authentication via session tokens:

{
  "Authorization": "Bearer <session_token>"
}

🛡️ Admin Endpoints

Admin endpoints require users with admin privileges:

/api/admin/dashboard - Payment analytics
/api/admin/monitoring - System health
/api/admin/rate-limits - Rate limit management

⚡ Rate Limits

All endpoints are protected by rate limiting to ensure fair usage:

{
  "/api/login": {
    "requests": 5,
    "window": "5 minutes"
  },
  "/api/signup": {
    "requests": 3,
    "window": "5 minutes"
  },
  "/api/payments/initiate": {
    "requests": 10,
    "window": "5 minutes"
  },
  "/api/": {
    "requests": 100,
    "window": "1 minute"
  },
  "/api/admin/": {
    "requests": 300,
    "window": "1 minute"
  }
}

🚨 Error Responses

HTTP Status Codes

{
  "200": "Success - Request completed successfully",
  "400": "Bad Request - Invalid input data or validation error",
  "401": "Unauthorized - Authentication required or invalid token",
  "403": "Forbidden - Insufficient permissions (admin required)",
  "404": "Not Found - Resource or endpoint not found",
  "429": "Too Many Requests - Rate limit exceeded",
  "500": "Internal Server Error - Server-side error"
}

Error Response Format

{
  "error": "Error message description",
  "code": "ERROR_CODE",
  "details": "Additional error details if available"
}

🧪 Testing

📦 Postman Collection

Import the Postman collection for easy API testing:

/Flocci-Backend-API.postman_collection.json

Contains all endpoints with pre-configured requests and examples.

🔧 Test Script

Run the automated test script:

./test-api.sh

Automated bash script to test all endpoints with sample data.

🚀 Quick Start

1. Authentication Flow

Start by registering or logging in to get a session token

2. Use Session Token

Include the session token in the Authorization header for protected endpoints

3. Test Payments

Use the payments/initiate endpoint to test PayU integration

4. Admin Access

Ensure your user has admin privileges for admin endpoints