Revenue Management APIs

The Revenue Management APIs provide functionality for revenue forecasting, profit analysis, financial reporting, and NetSuite integration in the Stratpoint Timesheet Application. These APIs are designed for complex business financial operations with extensive filtering, revenue recognition, and profit margin analysis.

Authentication Headers

All revenue management endpoints require authentication:

Authorization: Bearer {jwt_token}
galingsa: timesheetweb
Content-Type: application/json

Revenue Forecasting and Analysis

Revenue Forecast Report

Retrieves comprehensive revenue forecast data with advanced filtering and grouping options.

POST /api/v2/revenue/forecastReport

Permission Required: Permission ID 109

Request Body:

{
  "startYearMonth": "2024-01",
  "endYearMonth": "2024-12",
  "utilizationFactor": 0.85,
  "mainGroupField": "business_unit",
  "selectBusinessUnit": "1,2,3",
  "selectClient": "1,2",
  "selectClientLocation": ["Local", "Foreign"],
  "selectCompany": "1,2",
  "selectProject": "1,2,3",
  "selectProjectStatus": "1,2",
  "selectProjectType": "1,2",
  "selectReportStatus": "1,2",
  "selectSowSigned": ["yes", "no"],
  "selectBusinessLine": "1,2",
  "selectProbabilityOfClosing": "1,2,3",
  "selectEngagementManager": "123,456",
  "selectSalesPerson": "789,101",
  "considerCoca": true,
  "newBusiness": "1,2"
}

Validation Rules: - startYearMonth: Required, format YYYY-MM - endYearMonth: Required, format YYYY-MM, must be after start date - utilizationFactor: Required numeric, minimum 0 - mainGroupField: Required, one of: company_booking, business_unit, netsuite_project, client

Response:

{
  "header": {
    "status": 200,
    "title": "Revenue",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "allowSaveSnapshot": true,
    "data": [
      {
        "companyBookingId": 1,
        "companyBookingName": "Stratpoint Technologies Inc.",
        "children": [
          {
            "clientId": 123,
            "clientName": "ABC Corporation",
            "projects": [
              {
                "projectId": 456,
                "projectName": "Enterprise Portal Development",
                "forecastRevenue": "150000.00",
                "actualRevenue": "125000.00",
                "projectedRevenue": "180000.00",
                "utilizationFactor": 0.85,
                "monthlyBreakdown": [
                  {
                    "yearMonth": "2024-01",
                    "forecastRevenue": "12500.00",
                    "actualRevenue": "11000.00"
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "filters": {
      "businessUnits": [
        {
          "id": 1,
          "name": "Technology",
          "isActive": 1
        }
      ]
    }
  }
}

Save Revenue Data

Saves revenue forecast or actual revenue data.

POST /api/v2/revenue/save

Get Revenue Details

Retrieves detailed revenue information for a specific revenue record.

GET /api/v2/revenue/getDetails/{revenueId}

Parameters: - revenueId: Revenue record ID (required)

Fixed Price Revenue Operations

Search Fixed Price Revenue

Retrieves fixed price revenue data with filtering.

POST /api/v2/revenue/fixed_price/search

Get Fixed Price Revenue Filters

Retrieves filter options for fixed price revenue reports.

POST /api/v2/revenue/fixed_price/searchfilters

Revenue Snapshot and Change Management

Save Snapshot Revenue Changes

Creates snapshot of revenue changes for tracking historical data.

GET /api/v2/revenue/saveSnapShotRevenueChanges/{snapShotDate?}/{projectId?}

Parameters: - snapShotDate: Optional snapshot date - projectId: Optional project ID filter

Get Snapshot Report

Retrieves revenue snapshot report for analysis.

POST /api/v2/revenue/getSnapshotReport

Override Revenue Amount

Allows manual override of revenue amounts.

POST /api/v2/revenue/overrideAmount

Request Body:

{
  "revenueId": 123,
  "overrideAmount": "15000.00",
  "reason": "Client contract adjustment",
  "effectiveDate": "2024-01-15"
}

Business Unit and Contribution Analysis

BU Contribution Report

Retrieves business unit contribution analysis.

POST /api/v2/revenue/buContributionReport

BU Contribution Margin Report by Business Unit

Retrieves contribution margin report for specific business unit.

POST /api/v2/revenue/buContributionMarginReport/byBu

BU Contribution Margin Report for All Business Units

Retrieves contribution margin report for all business units.

POST /api/v2/revenue/buContributionMarginReport/allBu

Revenue Per Resource

Retrieves revenue contribution per resource.

POST /api/v2/revenue/buContributionMarginReport/revenuePerResource

Account Consolidated Revenue

Retrieves consolidated revenue data by account.

POST /api/v2/revenue/accountConsolidatedRevenue

NetSuite Integration

Export NetSuite Unbilled Revenue JE

Exports NetSuite journal entries for unbilled revenue.

POST /api/v2/revenue/exportNetSuiteUnbilledRevenueJE

Export NetSuite Unbilled Revenue JE Intra-Company

Exports NetSuite intra-company journal entries for unbilled revenue.

POST /api/v2/revenue/exportNetSuiteUnbilledRevenueJEIntraco

Finance Revenue Operations

Import Finance Revenue Report

Imports revenue data from external finance reports.

POST /api/v2/revenue/importFinanceRevenueReport/{reportType}

Parameters: - reportType: Type of finance report being imported

Get Finance Revenue Report

Retrieves finance revenue report data.

POST /api/v2/revenue/getFinanceRevenueReport

Profit Analysis APIs

Gross Net Profit Report

Retrieves comprehensive profit analysis with gross and net margins.

POST /api/v2/profits/grossNetProfitReport

Permission Required: Permission ID 118

Request Body:

{
  "startYearMonth": "2024-01",
  "endYearMonth": "2024-12",
  "selectBusinessUnit": "1,2,3",
  "selectClient": "1,2",
  "selectCompany": "1,2",
  "selectProject": "1,2,3",
  "selectProjectStatus": "1,2",
  "selectReportType": ["revenue", "budgeted", "assigned", "actual", "actualResource", "cumulative"]
}

Validation Rules: - startYearMonth: Required, format YYYY-MM - endYearMonth: Required, format YYYY-MM, must be after start date - selectReportType: Array of report types

Response:

{
  "header": {
    "status": 200,
    "title": "Profit",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "companyData": [
      {
        "companyBookingId": 1,
        "companyBookingName": "Stratpoint Technologies Inc.",
        "children": [
          {
            "clientId": 123,
            "clientName": "ABC Corporation",
            "projects": [
              {
                "projectId": 456,
                "projectName": "Enterprise Portal Development",
                "totalRevenue": "150000.00",
                "totalCost": "120000.00",
                "grossProfit": "30000.00",
                "grossMargin": 20.0,
                "netProfit": "25000.00",
                "netMargin": 16.67
              }
            ]
          }
        ]
      }
    ]
  }
}

Project Margin Report

Retrieves detailed project margin analysis.

POST /api/v2/profits/projectMarginReport

Project Margin Assigned vs Actual Report

Compares assigned versus actual project margins.

POST /api/v2/profits/projectmarginassignedactualreport

Year to Date Profit Margin

Retrieves year-to-date profit margin analysis.

POST /api/v2/profits/yearToDateProfitMargin

Supporting Data with User Promotion

Retrieves supporting data including user promotion impacts.

GET /api/v2/profits/getSupportingDataWithUserPromotion/{projectId}/{startDate}/{endDate}

Parameters: - projectId: Project ID (required) - startDate: Start date in YYYY-MM-DD format (required) - endDate: End date in YYYY-MM-DD format (required)

Project Manager Dashboard

PM Dashboard

Retrieves project manager dashboard data with various grouping options.

POST /api/v2/profits/pmDashboard/{reportGrouping}

Parameters: - reportGrouping: Grouping method for the dashboard

PM Dashboard Snapshot

Retrieves snapshot of project manager dashboard data.

GET /api/v2/profits/pmDashboardSnapShot/{reportGrouping}

Parameters: - reportGrouping: Grouping method for the snapshot

Business Rules and Financial Concepts

Revenue Recognition

Revenue recognition follows business rules: - Fixed Price Projects: Revenue recognized based on milestone completion - Time and Materials: Revenue recognized based on hours logged - Hybrid Projects: Combination of fixed price and T&M recognition

Utilization Factor

Utilization factor impacts revenue calculations: - Standard utilization: 0.85 (85%) - Affects projected revenue calculations - Used in capacity planning and forecasting

Grouping Options

Revenue reports can be grouped by: - Company Booking: Legal entity grouping - Business Unit: Organizational unit grouping - NetSuite Project: Financial system project grouping - Client: Customer-based grouping

Probability of Closing

Revenue forecasting considers probability factors: - High probability: 90-100% - Medium probability: 50-89% - Low probability: 10-49% - Unlikely: 0-9%

Error Handling

Common Error Responses

Access Denied:

{
  "header": {
    "status": 401,
    "title": "Revenue",
    "description": "Access not allowed"
  },
  "body": []
}

Validation Error:

{
  "header": {
    "status": 412,
    "title": "Revenue",
    "description": "Validation error encountered"
  },
  "body": {
    "errors": {
      "startYearMonth": ["The start year month field is required"],
      "utilizationFactor": ["The utilization factor must be a number"]
    }
  }
}

No Records Found:

{
  "header": {
    "status": 404,
    "title": "Revenue",
    "description": "No record found"
  },
  "body": []
}

Key Implementation Notes

1. Business-Centric Design: Revenue APIs focused on business financial operations rather than generic CRUD
2. Complex Filtering: Extensive filtering options with comma-separated integer arrays and business-specific filters
3. NetSuite Integration: Deep integration with NetSuite ERP for financial data export
4. Snapshot Capability: Revenue change tracking with historical snapshots
5. Permission-Based Access: Different permission levels for revenue viewing and profit analysis
6. Multi-dimensional Analysis: Revenue analysis by multiple business dimensions
7. Forecasting Focus: Heavy emphasis on revenue forecasting and projection
8. Profit Margin Analysis: Comprehensive profit analysis with multiple margin calculations

This Revenue Management API is designed for enterprise financial management with complex business rules, forecasting capabilities, and comprehensive profit analysis.