Documentation

API Reference

This section provides complete documentation for all backend REST API endpoints. The Tax Management System backend is built with Spring Boot and provides RESTful services for tax calculations, configuration management, and AI-powered queries.

Base URL

All API endpoints are prefixed with the base URL of your backend server:

http://localhost:8080

Authentication

Currently, the system uses basic authentication. Include credentials in the Authorization header:

Authorization: Basic <base64-encoded-credentials>

Response Format

All responses use JSON format. Successful responses return HTTP status codes in the 2xx range. Errors return 4xx or 5xx status codes with error details.

Endpoints

Tax Calculation Endpoints

Calculate Tax

Calculate tax for a given policy scenario.

Endpoint: POST /tax/calculate

Request Body:

{
  "referenceNumber": "POL-12345",
  "policyStartDate": "2024-01-15",
  "policyEndDate": "2025-01-14",
  "policyCurrency": "GBP",
  "policyCoverages": [
    {
      "coverageCode": "MOTOR",
      "countryCode": "GB",
      "premium": 500.00,
      "premiumCurrency": "GBP",
      "coverageDetails": {
        "vehicleValue": 25000,
        "driverAge": 35
      },
      "coverageStartDate": "2024-01-15",
      "coverageEndDate": "2025-01-14",
      "taxEffectiveDate": "2024-01-15"
    }
  ],
  "transactionType": "NEW_BUSINESS"
}

Response:

{
  "referenceNumber": "POL-12345",
  "calculationReference": "CALC-67890",
  "policyStartDate": "2024-01-15",
  "policyEndDate": "2025-01-14",
  "policyCurrency": "GBP",
  "requestId": "REQ-11111",
  "taxes": [
    {
      "coverageCode": "MOTOR",
      "coverageReferenceNumber": "POL-12345-1",
      "taxCode": "UK_MOTOR_IPT",
      "taxAmount": 60.00,
      "taxCurrency": "GBP",
      "additionalInformation": []
    }
  ]
}

Field Descriptions:

  • referenceNumber - Unique policy reference
  • policyStartDate / policyEndDate - Policy period
  • policyCurrency - Currency for policy amounts
  • policyCoverages - Array of coverages to tax
    • coverageCode - Coverage type code
    • countryCode - Country code for tax determination
    • premium - Premium amount
    • premiumCurrency - Premium currency
    • coverageDetails - Coverage-specific input fields
    • additionalPremiums - Optional additional premiums
  • transactionType - Optional transaction type

Get Tax Calculation

Retrieve a previously calculated tax result.

Endpoint: GET /tax/calculate/{calculationReference}

Path Parameters:

  • calculationReference - The calculation reference from a previous calculation

Response: Same as Calculate Tax response

Tax Information Endpoints

Get Tax Info

Retrieve tax configuration information for a specific country and coverage.

Endpoint: GET /tax/info

Query Parameters:

  • countryCode (required) - Country code (e.g., GB, US)
  • coverageCode (required) - Coverage code (e.g., MOTOR)
  • includeInactive (optional, default: false) - Include inactive configurations

Response:

{
  "taxConfigurations": [
    {
      "id": "tax-config-123",
      "name": "UK Motor Insurance IPT",
      "taxCode": "UK_MOTOR_IPT",
      "countryCodes": ["GB"],
      "currency": "GBP",
      "calculationBasedOn": "premium",
      "calculationType": "percentage",
      "payableBy": "insurer",
      "administeredBy": "insurer",
      "status": "active",
      "taxCoverageGroups": [...]
    }
  ],
  "coverageInputs": [
    {
      "name": "vehicleValue",
      "type": "number",
      "mandatory": true
    }
  ]
}

AI Query Endpoints

Query Tax Information

Ask natural language questions about tax configurations.

Endpoint: POST /tax/query

Request Body:

{
  "question": "What is the IPT rate for motor insurance in the UK?",
  "countryCode": "GB",
  "taxCode": "UK_MOTOR_IPT",
  "includeHistorical": false
}

Response:

{
  "answer": "Based on the UK Motor Insurance configuration, the standard IPT rate is 12%. This applies to premiums and is payable by the insurance company.",
  "sourceConfigurationIds": ["tax-config-123"],
  "context": "Tax Configurations:\n\nConfiguration: UK Motor Insurance IPT...",
  "model": "gpt-4"
}

Field Descriptions:

  • question (required) - Natural language question
  • countryCode (optional) - Filter by country
  • taxCode (optional) - Filter by tax code
  • includeHistorical (optional) - Include historical configurations

Admin - Coverage Configuration Endpoints

Create Coverage Configuration

Create a new coverage configuration.

Endpoint: POST /admin/coverage-configurations

Request Body:

{
  "name": "Motor Insurance",
  "code": "MOTOR",
  "description": "Motor vehicle insurance coverage",
  "inputs": [
    {
      "name": "vehicleValue",
      "type": "number",
      "defaultValue": "0",
      "mandatory": true
    }
  ],
  "countrySpecificInputs": [
    {
      "countryCode": "GB",
      "inputs": [
        {
          "name": "ukRegistrationNumber",
          "type": "string",
          "mandatory": true
        }
      ]
    }
  ],
  "additionalPremiumTypes": [
    {
      "name": "Windscreen Cover",
      "code": "WINDSCREEN",
      "countries": ["GB", "IE"]
    }
  ],
  "notes": "Standard motor insurance coverage"
}

Response: Created coverage configuration object

Update Coverage Configuration

Update an existing coverage configuration.

Endpoint: PUT /admin/coverage-configurations/{id}

Path Parameters:

  • id - Coverage configuration ID

Request Body: Same as create

Response: Updated coverage configuration object

Get All Coverage Configurations

Retrieve all coverage configurations.

Endpoint: GET /admin/coverage-configurations

Response: Array of coverage configuration objects

Get Coverage Configuration

Retrieve a specific coverage configuration.

Endpoint: GET /admin/coverage-configurations/{id}

Path Parameters:

  • id - Coverage configuration ID

Response: Coverage configuration object

Admin - Tax Configuration Endpoints

Create Tax Configuration

Create a new tax configuration.

Endpoint: POST /admin/tax-configurations

Request Body:

{
  "name": "UK Motor Insurance IPT",
  "taxCode": "UK_MOTOR_IPT",
  "countryCodes": ["GB"],
  "currency": "GBP",
  "calculationBasedOn": "premium",
  "calculationType": "percentage",
  "payableBy": "insurer",
  "administeredBy": "insurer",
  "status": "active",
  "taxCoverageGroups": [
    {
      "name": "Motor Coverages",
      "coverageIds": ["coverage-123"],
      "taxTable": [
        {
          "effectiveFromDate": "2024-01-01",
          "rules": [
            {
              "ruleType": "simple",
              "isDefault": true,
              "amount": 12,
              "amountType": "percentage",
              "appliesToStandardPremium": true
            }
          ]
        }
      ]
    }
  ],
  "customProperties": [],
  "notes": "Standard UK IPT for motor insurance"
}

Response: Created tax configuration object

Update Tax Configuration

Update an existing tax configuration.

Endpoint: PUT /admin/tax-configurations/{id}

Path Parameters:

  • id - Tax configuration ID

Request Body: Same as create

Response: Updated tax configuration object

Delete Tax Configuration

Delete a tax configuration.

Endpoint: DELETE /admin/tax-configurations/{id}

Path Parameters:

  • id - Tax configuration ID

Response: HTTP 204 No Content

Get All Tax Configurations

Retrieve all tax configurations.

Endpoint: GET /admin/tax-configurations

Response: Array of tax configuration objects

Get Tax Configuration

Retrieve a specific tax configuration.

Endpoint: GET /admin/tax-configurations/{id}

Path Parameters:

  • id - Tax configuration ID

Response: Tax configuration object

Get Coverage Inputs for Tax Configuration

Retrieve coverage inputs applicable to a tax configuration.

Endpoint: GET /admin/tax-configurations/{id}/coverage-inputs

Path Parameters:

  • id - Tax configuration ID

Response: Array of coverage input objects

Admin - Rate Update Endpoints

Update Tax Rates

Update tax rates for a configuration (bulk rate updates).

Endpoint: POST /admin/rate-updates

Request Body:

{
  "taxConfigurationId": "tax-config-123",
  "effectiveFromDate": "2024-06-01",
  "rateUpdates": [
    {
      "coverageGroupId": "group-123",
      "ruleId": "rule-456",
      "newAmount": 13.5,
      "newAmountType": "percentage"
    }
  ]
}

Response: Updated tax configuration object

Error Responses

All endpoints may return error responses:

400 Bad Request

Invalid request data or validation errors.

{
  "error": "Validation failed",
  "errors": {
    "premium": "must be greater than 0",
    "countryCode": "must be a valid ISO country code"
  }
}

404 Not Found

Resource not found.

{
  "error": "Tax configuration not found",
  "message": "Tax configuration with id 'xyz' not found"
}

500 Internal Server Error

Server-side error.

{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

Data Types

Common Types

Country Code

ISO 3166-1 alpha-2 country code (e.g., GB, US, DE).

Currency Code

ISO 4217 currency code (e.g., GBP, USD, EUR).

Date Format

ISO 8601 date format (YYYY-MM-DD).

Enum Values

Calculation Based On:

  • premium - Based on premium amount
  • limit - Based on policy limit

Calculation Type:

  • percentage - Percentage-based calculation
  • fixed - Fixed amount calculation

Payable By / Administered By:

  • insurer - Insurance company
  • policyholder - Policyholder

Status:

  • active - Currently active
  • inactive - Not active
  • draft - Draft status

Rule Type:

  • simple - Simple flat amount rule
  • complex - Rule with conditions
  • function - Custom function rule

Amount Type:

  • percentage - Percentage value
  • fixed - Fixed currency amount
  • perMille - Per thousand (0.1%)
  • factor - Multiplier factor

Operators:

  • EQUAL_TO - Equality comparison
  • NOT_EQUAL_TO - Inequality comparison
  • GREATER_THAN - Greater than comparison
  • GREATER_THAN_OR_EQUAL_TO - Greater than or equal comparison
  • LESS_THAN - Less than comparison
  • LESS_THAN_OR_EQUAL_TO - Less than or equal comparison

Rate Limiting

Currently, there are no rate limits enforced. Consider implementing rate limiting for production deployments.

Pagination

List endpoints (GET all) return all results without pagination. For large datasets, consider implementing pagination.

Versioning

The API is currently at version 1.0. Future versions may be indicated by URL path versioning (e.g., /api/v2/...).

Testing

Use the Tax Calculator in the admin interface to test tax calculations, or use tools like curl or Postman to test API endpoints directly.

Example curl Commands

# Calculate tax
curl -X POST http://localhost:8080/tax/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "referenceNumber": "POL-12345",
    "policyStartDate": "2024-01-15",
    "policyEndDate": "2025-01-14",
    "policyCurrency": "GBP",
    "policyCoverages": [{
      "coverageCode": "MOTOR",
      "countryCode": "GB",
      "premium": 500.00,
      "premiumCurrency": "GBP"
    }]
  }'

# Get tax info
curl -X GET "http://localhost:8080/tax/info?countryCode=GB&coverageCode=MOTOR"

# AI query
curl -X POST http://localhost:8080/tax/query \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the IPT rate for motor insurance in the UK?",
    "countryCode": "GB"
  }'