# FPL Products API Documentation

## Overview

The FPL (Financial Product Lending) Products API provides loan product information based on a user's N-Score. This API helps determine which loan products are available to users based on their creditworthiness score.

**Base URL**: `https://fpl.nanope.ai`

**API Version**: v1

---

## Endpoint

### Get Products by User ID and N-Score

Retrieve loan products available for a user based on their N-Score.

**Endpoint**: `/api/lms/products/userid`

**Method**: `GET`

**Full URL**: `https://fpl.nanope.ai/api/lms/products/userid`

---

## Request

### Query Parameters

| Parameter | Type | Required | Description | Example |
|-----------|------|----------|-------------|---------|
| `n_score` | float | Yes | User's N-Score (creditworthiness score) | `41` |

### Example Request

```bash
GET https://fpl.nanope.ai/api/lms/products/userid?n_score=41
```

```javascript
// JavaScript/Fetch example
fetch('https://fpl.nanope.ai/api/lms/products/userid?n_score=41')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

```python
# Python example
import requests

url = "https://fpl.nanope.ai/api/lms/products/userid"
params = {"n_score": 41}
response = requests.get(url, params=params)
data = response.json()
print(data)
```

---

## Response

### Success Response

**Status Code**: `200 OK`

**Content-Type**: `application/json`

**Response Body**:
```json
{
  "message": "Single matching plan found successfully",
  "n_score": 41.0,
  "products": [
    {
      "ADVANCE_PAYMENT_LIMIT": "",
      "ADVISORY_FEE": "350.0",
      "CREATED_DATE": "Mon, 24 Nov 2025 19:03:09 GMT",
      "DEFAUL_SKIP": "",
      "DESCRIPTION": "",
      "GST": "81.0",
      "IMG_URL": "https://genesis-tech.s3.us-west-2.amazonaws.com/1genrative_57fa9136-2baf-4888-8e50-9b31bf70088d.png",
      "INTREST": "250.0",
      "IS_ACTIVE": "Y",
      "IS_DELETED": "N",
      "LATE_FEE": "0",
      "LOAN_TERM": "33",
      "PAYBACK_TERM": 1,
      "PAYFULL": true,
      "PAYMIN": "",
      "PLAN": "",
      "PLAN_CATEGORY": "Regular",
      "PLATFORM_FEE": "50.0",
      "PROCESSING_FEE": "50.0",
      "_class": "com.service.nano.entity.LoanMaster",
      "_id": "6924abed3ced4a7cec0c13f9",
      "additionalInfo": [],
      "dailyPaymentAmount": "175.18",
      "description": "Start your nanope journey",
      "features": [],
      "interestRateRange": {
        "min": 6
      },
      "loanAmountRange": {
        "max": 9000,
        "min": 5000
      },
      "planActive": true,
      "planName": "Plan 1",
      "plans": [
        {
          "amount": 5000,
          "dailyPayback": 176.7,
          "nscoreMax": 41,
          "nscoreMin": 39,
          "planName": "Plan 1"
        }
      ],
      "principalAmount": "5000.0",
      "productName": "STARTER LOAN",
      "totalCharges": "781.0",
      "totalPayback": "5781.0"
    }
  ],
  "total": 1
}
```

---

## Response Fields

### Top-Level Fields

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Status message indicating the result of the query (e.g., "Single matching plan found successfully") |
| `n_score` | float | The N-Score value used in the query |
| `total` | integer | Total number of matching products found |
| `products` | array | Array of loan product objects matching the N-Score criteria |

### Product Object Fields

#### Core Product Information

| Field | Type | Description |
|-------|------|-------------|
| `_id` | string | Unique identifier for the loan product (MongoDB ObjectId) |
| `_class` | string | Entity class name (e.g., "com.service.nano.entity.LoanMaster") |
| `productName` | string | Name of the loan product (e.g., "STARTER LOAN") |
| `planName` | string | Name of the specific plan |
| `planActive` | boolean | Whether the plan is currently active |
| `description` | string | Description of the loan product |
| `PLAN_CATEGORY` | string | Category of the plan (e.g., "Regular") |

#### Financial Details

| Field | Type | Description |
|-------|------|-------------|
| `principalAmount` | string | Principal loan amount (e.g., "5000.0") |
| `dailyPaymentAmount` | string | Daily payment amount required |
| `totalCharges` | string | Total charges including all fees and interest |
| `totalPayback` | string | Total amount to be paid back (principal + charges) |
| `INTREST` | string | Interest amount |
| `ADVISORY_FEE` | string | Advisory fee charged |
| `PLATFORM_FEE` | string | Platform fee charged |
| `PROCESSING_FEE` | string | Processing fee charged |
| `GST` | string | GST (Goods and Services Tax) amount |
| `LATE_FEE` | string | Late payment fee (if applicable) |

#### Loan Terms

| Field | Type | Description |
|-------|------|-------------|
| `LOAN_TERM` | string | Loan term in days |
| `PAYBACK_TERM` | number | Payback term |
| `PAYFULL` | boolean | Whether full payment is required |
| `PAYMIN` | string | Minimum payment amount (if applicable) |
| `ADVANCE_PAYMENT_LIMIT` | string | Advance payment limit (if applicable) |

#### Loan Amount and Interest Ranges

| Field | Type | Description |
|-------|------|-------------|
| `loanAmountRange` | object | Range of loan amounts available |
| `loanAmountRange.min` | number | Minimum loan amount |
| `loanAmountRange.max` | number | Maximum loan amount |
| `interestRateRange` | object | Interest rate range |
| `interestRateRange.min` | number | Minimum interest rate percentage |
| `interestRateRange.max` | number | Maximum interest rate percentage (if available) |

#### Sub-Plans Array

| Field | Type | Description |
|-------|------|-------------|
| `plans` | array | Array of sub-plans within the product |
| `plans[].planName` | string | Name of the sub-plan |
| `plans[].amount` | number | Loan amount for this sub-plan |
| `plans[].dailyPayback` | number | Daily payback amount for this sub-plan |
| `plans[].nscoreMin` | number | Minimum N-Score required for this plan |
| `plans[].nscoreMax` | number | Maximum N-Score eligible for this plan |

#### Status and Metadata

| Field | Type | Description |
|-------|------|-------------|
| `IS_ACTIVE` | string | Active status ("Y" for active, "N" for inactive) |
| `IS_DELETED` | string | Deletion status ("Y" for deleted, "N" for not deleted) |
| `CREATED_DATE` | string | Creation date in GMT format (e.g., "Mon, 24 Nov 2025 19:03:09 GMT") |
| `IMG_URL` | string | URL to the product image/logo |
| `DESCRIPTION` | string | Additional description (may be empty) |
| `PLAN` | string | Plan identifier (may be empty) |
| `DEFAUL_SKIP` | string | Default skip option (if applicable) |

#### Additional Information

| Field | Type | Description |
|-------|------|-------------|
| `additionalInfo` | array | Additional information array (typically empty) |
| `features` | array | Array of product features (typically empty) |

---

## Error Responses

### 400 Bad Request

Invalid or missing `n_score` parameter.

**Response**:
```json
{
  "message": "Invalid n_score parameter",
  "code": 400
}
```

### 404 Not Found

No products found for the given N-Score.

**Response**:
```json
{
  "message": "No products found for the given N-Score",
  "n_score": 41.0,
  "products": [],
  "total": 0
}
```

### 500 Internal Server Error

Server error occurred while processing the request.

**Response**:
```json
{
  "message": "Internal server error",
  "code": 500
}
```

---

## Business Logic

### N-Score Matching

- Products are returned based on whether the user's N-Score falls within the range specified in each plan's `nscoreMin` and `nscoreMax` fields
- Only products with `IS_ACTIVE="Y"` and `IS_DELETED="N"` are returned
- The API matches the provided N-Score against the `nscoreMin` and `nscoreMax` values in the `plans` array

### Example Matching Logic

For `n_score=41`:
- Plan with `nscoreMin=39` and `nscoreMax=41` → **MATCH**
- Plan with `nscoreMin=42` and `nscoreMax=50` → **NO MATCH**
- Plan with `nscoreMin=35` and `nscoreMax=45` → **MATCH**

---

## Data Types and Formats

### Monetary Values

- All monetary values (amounts, fees, charges) are returned as **strings** (e.g., "5000.0", "350.0")
- Convert to numeric types in your application for calculations

### Dates

- Dates are returned in GMT format: `"Mon, 24 Nov 2025 19:03:09 GMT"`
- Parse using standard date parsing libraries

### Boolean Values

- Boolean fields (`planActive`, `PAYFULL`) are returned as actual boolean types (`true`/`false`)

### Status Flags

- Status flags (`IS_ACTIVE`, `IS_DELETED`) use string values: `"Y"` or `"N"`

---

## Usage Examples

### Example 1: Get Products for N-Score 41

```bash
curl -X GET "https://fpl.nanope.ai/api/lms/products/userid?n_score=41"
```

### Example 2: JavaScript/TypeScript

```typescript
interface FPLProduct {
  _id: string;
  productName: string;
  planName: string;
  principalAmount: string;
  totalPayback: string;
  loanAmountRange: {
    min: number;
    max: number;
  };
  plans: Array<{
    amount: number;
    nscoreMin: number;
    nscoreMax: number;
    dailyPayback: number;
  }>;
}

interface FPLResponse {
  message: string;
  n_score: number;
  total: number;
  products: FPLProduct[];
}

async function getFPLProducts(nScore: number): Promise<FPLResponse> {
  const response = await fetch(
    `https://fpl.nanope.ai/api/lms/products/userid?n_score=${nScore}`
  );
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  return await response.json();
}

// Usage
getFPLProducts(41)
  .then(data => {
    console.log(`Found ${data.total} products`);
    data.products.forEach(product => {
      console.log(`Product: ${product.productName}`);
      console.log(`Amount Range: ${product.loanAmountRange.min} - ${product.loanAmountRange.max}`);
    });
  })
  .catch(error => console.error('Error:', error));
```

### Example 3: Python

```python
import requests
from typing import Dict, List, Any

def get_fpl_products(n_score: float) -> Dict[str, Any]:
    """
    Get FPL products for a given N-Score.
    
    Args:
        n_score: User's N-Score
        
    Returns:
        Dictionary containing products and metadata
    """
    url = "https://fpl.nanope.ai/api/lms/products/userid"
    params = {"n_score": n_score}
    
    try:
        response = requests.get(url, params=params)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching products: {e}")
        return {}

# Usage
products_data = get_fpl_products(41)
print(f"Message: {products_data.get('message')}")
print(f"Total products: {products_data.get('total')}")

for product in products_data.get('products', []):
    print(f"\nProduct: {product.get('productName')}")
    print(f"Principal: {product.get('principalAmount')}")
    print(f"Total Payback: {product.get('totalPayback')}")
    
    # Access sub-plans
    for plan in product.get('plans', []):
        print(f"  Plan: {plan.get('planName')}")
        print(f"  Amount: {plan.get('amount')}")
        print(f"  N-Score Range: {plan.get('nscoreMin')} - {plan.get('nscoreMax')}")
```

---

## Integration Notes

### Rate Limiting

- Check with the API provider for rate limiting policies
- Implement appropriate retry logic and exponential backoff

### Caching

- Consider caching product data as it may not change frequently
- Implement cache invalidation based on your use case

### Error Handling

- Always handle network errors and HTTP error status codes
- Validate response structure before accessing nested fields
- Handle cases where `products` array might be empty

### Security

- This endpoint appears to be public (no authentication shown)
- If authentication is required, check with the API provider for required headers or tokens

---

## Changelog

### Version 1.0
- Initial API documentation
- Documented `/api/lms/products/userid` endpoint
- Added comprehensive field descriptions
- Included usage examples

---

## Support

For issues or questions regarding this API:
- Contact the FPL service team
- Check the main API documentation for related endpoints

---

**Last Updated**: November 2025