Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
396 lines (314 loc) · 8.34 KB

API_DOCUMENTATION.md

File metadata and controls

396 lines (314 loc) · 8.34 KB

FinSync360 API Documentation

Complete API documentation for the FinSync360 ERP system with production endpoints and authentication requirements.

🌐 Production Environment

All services are deployed and operational with 100% integration test success.

Service URLs

Integration Test Results

  • ✅ Backend API: 7/7 endpoints passing (100%)
  • ✅ ML Service: 3/3 endpoints passing (100%)
  • ✅ Cross-service communication: 1/1 tests passing (100%)
  • 🎯 Overall: 11/11 tests passing (100% success rate)

🔐 Authentication

All API endpoints (except health checks) require JWT authentication.

Authentication Flow

  1. Register/Login

    POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

  2. Use Token

    Authorization: Bearer <jwt_token>

📡 Backend API Endpoints

Base URL: https://finsync-backend-d34180691b06.herokuapp.com

System Endpoints

Health Check ✅

GET /health
# Response: 200 OK
{
  "status": "OK",
  "timestamp": "2025-07-29T06:33:12.386Z",
  "uptime": 63.946218302,
  "environment": "development"
}

Authentication Endpoints ✅

User Registration

POST /api/auth/register
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com", 
  "password": "password123",
  "company": "Acme Corp"
}

# Response: 201 Created (on success)
# Response: 400 Bad Request (validation errors)

User Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "password123"
}

# Response: 200 OK (on success)
# Response: 400 Bad Request (validation errors)

Get User Profile

GET /api/auth/profile
Authorization: Bearer <jwt_token>

# Response: 200 OK (authenticated)
# Response: 401 Unauthorized (no/invalid token)

Business Endpoints ✅

Transactions (Vouchers)

# Get all transactions
GET /api/transactions
Authorization: Bearer <jwt_token>

# Get single transaction
GET /api/transactions/:id
Authorization: Bearer <jwt_token>

# Create transaction
POST /api/transactions
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "voucherType": "sales",
  "date": "2025-07-29",
  "party": "customer_id",
  "items": [
    {
      "item": "item_id",
      "quantity": 10,
      "rate": 100.00
    }
  ],
  "narration": "Sales transaction"
}

# Update transaction
PUT /api/transactions/:id
Authorization: Bearer <jwt_token>

# Delete transaction
DELETE /api/transactions/:id
Authorization: Bearer <jwt_token>

# All endpoints return:
# Response: 200 OK (success)
# Response: 401 Unauthorized (no/invalid auth)
# Response: 404 Not Found (invalid ID)

Budgets

# Get all budgets
GET /api/budgets
Authorization: Bearer <jwt_token>

# Response: 200 OK
{
  "success": true,
  "count": 2,
  "data": [
    {
      "id": "1",
      "name": "Monthly Operating Expenses",
      "category": "expense",
      "amount": 50000,
      "spent": 32000,
      "remaining": 18000,
      "period": "monthly",
      "startDate": "2025-01-01",
      "endDate": "2025-01-31"
    }
  ]
}

# Create budget
POST /api/budgets
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "name": "Marketing Budget",
  "category": "expense",
  "amount": 25000,
  "period": "monthly",
  "startDate": "2025-01-01",
  "endDate": "2025-01-31"
}

# Update budget
PUT /api/budgets/:id
Authorization: Bearer <jwt_token>

# Delete budget
DELETE /api/budgets/:id
Authorization: Bearer <jwt_token>

# All endpoints return:
# Response: 200 OK (success)
# Response: 401 Unauthorized (no/invalid auth)

Other Protected Endpoints ✅

All these endpoints require authentication and return 401 without valid JWT:

  • GET|POST|PUT|DELETE /api/vouchers - Voucher management
  • GET|POST|PUT|DELETE /api/inventory - Inventory management
  • GET|POST|PUT|DELETE /api/payments - Payment processing
  • GET|POST|PUT|DELETE /api/parties - Customer/Supplier management
  • GET /api/companies - Company management
  • GET /api/users - User management
  • GET /api/reports - Report generation
  • GET /api/notifications - Notification management

🤖 ML Service Endpoints

Base URL: https://finsync-ml-2bba4152b555.herokuapp.com

System Endpoints ✅

Service Information

GET /
# Response: 200 OK
{
  "service": "FinSync360 ML Service",
  "version": "1.0.0",
  "status": "running",
  "docs": "/docs",
  "health": "/api/v1/health"
}

Health Check

GET /api/v1/health
# Response: 200 OK
{
  "status": "healthy",
  "service": "FinSync360 ML Service",
  "version": "1.0.0",
  "timestamp": "2025-07-29T06:34:57.235947"
}

Prediction Endpoints ✅

Payment Delay Prediction

POST /api/v1/payment-delay
Content-Type: application/json

{
  "customer_id": "customer_123",
  "amount": 10000,
  "due_date": "2025-08-15",
  "assessment_type": "payment"
}

# Response: 422 Unprocessable Entity (validation error without proper data)
# Response: 200 OK (with valid data and authentication)

Bulk Payment Predictions

POST /api/v1/payment-delay/bulk
Content-Type: application/json

{
  "customers": ["customer_1", "customer_2"],
  "assessment_type": "payment"
}

Inventory Forecasting

POST /api/v1/inventory-forecast
Content-Type: application/json

{
  "item_id": "item_123",
  "forecast_days": 30
}

Risk Assessment

POST /api/v1/risk-assessment
Content-Type: application/json

{
  "customer_id": "customer_123",
  "assessment_type": "credit"
}

Model Management Endpoints

Model Status

GET /api/v1/models/status
# Returns status of all ML models

Trigger Model Retraining

POST /api/v1/models/retrain
Content-Type: application/json

{
  "model_types": ["payment_prediction", "risk_assessment"]
}

🧪 Testing the APIs

Integration Test Suite

Run the comprehensive integration test:

cd mobile
node test-full-integration.js

# Expected output:
# 🎯 Overall: 11/11 tests passed (100%)
# 🎉 All integration tests passed! FinSync360 is ready for production.

Manual Testing Examples

# Test backend health
curl https://finsync-backend-d34180691b06.herokuapp.com/health

# Test ML service health  
curl https://finsync-ml-2bba4152b555.herokuapp.com/api/v1/health

# Test authentication requirement
curl https://finsync-backend-d34180691b06.herokuapp.com/api/transactions
# Expected: {"success":false,"message":"Not authorized to access this route"}

# Test ML prediction endpoint
curl -X POST https://finsync-ml-2bba4152b555.herokuapp.com/api/v1/payment-delay \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "test"}'
# Expected: Validation error response

🔒 Security Features

  • JWT Authentication: All business endpoints protected
  • Input Validation: Comprehensive request validation
  • CORS Protection: Configured for production domains
  • Rate Limiting: API rate limiting implemented
  • HTTPS: All production endpoints use HTTPS
  • Environment Isolation: Separate development/production configs

📊 Error Responses

Common HTTP Status Codes

  • 200 OK - Successful request
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request data/validation errors
  • 401 Unauthorized - Missing or invalid authentication
  • 404 Not Found - Resource not found
  • 422 Unprocessable Entity - Validation errors (ML service)
  • 500 Internal Server Error - Server error

Error Response Format

{
  "success": false,
  "message": "Error description",
  "errors": [
    {
      "type": "field",
      "msg": "Validation error message",
      "path": "field_name",
      "location": "body"
    }
  ]
}

🚀 Production Deployment Status

All services are successfully deployed and operational:

  • ✅ Backend API deployed on Heroku
  • ✅ ML Service deployed on Heroku
  • ✅ MongoDB Atlas database connected
  • ✅ All authentication endpoints working
  • ✅ All business endpoints protected and functional
  • ✅ ML prediction endpoints operational
  • ✅ 100% integration test success rate

The FinSync360 API is ready for production use!