# Pebble Core Engine API Documentation

## Overview

Pebble Core Engine is a Flask-based REST API that provides authentication, user management, loan services, and API gateway functionality. The API uses JWT tokens for authentication and MongoDB for data storage.

**Base URL**: `http://localhost:5001` (Development)

**API Version**: v1, v2

---

## Table of Contents

1. [Authentication](#authentication)
2. [General Endpoints](#general-endpoints)
3. [Authentication Endpoints](#authentication-endpoints)
4. [User Management Endpoints](#user-management-endpoints)
5. [Loan Management Endpoints](#loan-management-endpoints)
6. [Gateway Endpoints](#gateway-endpoints)
7. [Error Codes](#error-codes)
8. [Data Models](#data-models)

---

## Authentication

Most endpoints require JWT authentication. Include the token in the request header:

```
x-access-token: <your_jwt_token>
```

### Token Generation

Tokens are generated upon successful login and are valid for 365 days by default.

---

## General Endpoints

### Test API

Test if the API is working.

**Endpoint**: `GET /api/test`

**Authentication**: Not required

**Response**:
```json
{
  "success": true,
  "message": "GET API is working",
  "data": {
    "id": 1,
    "name": "Test User",
    "role": "Admin"
  }
}
```

---

## Authentication Endpoints

### 1. Send OTP for Login

Send OTP to user's phone number for login.

**Endpoint**: `POST /auth/v1/POSTloginsendotp`

**Authentication**: Not required

**Request Body**:
```json
{
  "phone_number": "9999999990",
  "country_code": "+91"
}
```

**Response**:
```json
{
  "message": "OTP sent successfully",
  "code": 200,
  "res_data": {
    "identifier": "uuid-string",
    "type": "phone"
  },
  "status": "success"
}
```

**Error Responses**:
- `400`: Missing phone number
- `500`: Server error

---

### 2. Verify OTP for Login

Verify OTP and login/create user.

**Endpoint**: `POST /auth/v1/POSTloginverifyotp`

**Authentication**: Not required

**Request Body**:
```json
{
  "identifier": "uuid-string",
  "otp": "123456",
  "phone_number": "9999999990",
  "country_code": "+91",
  "device_type": "android",
  "language": "en"
}
```

**Response**:
```json
{
  "message": "OTP verified successfully, you may proceed",
  "code": 200,
  "res_data": {
    "user_id": "user_id_string",
    "existing_user": "Y"
  },
  "status": "success"
}
```

**Error Responses**:
- `400`: Invalid OTP or missing fields
- `500`: Server error

---

### 3. Verify OTP for Registration

Verify OTP during user registration.

**Endpoint**: `POST /auth/v1/POSTverifyotp`

**Authentication**: Not required

**Request Body**:
```json
{
  "phone_number": "9999999990",
  "country_code": "+91",
  "password": "user_password",
  "username": "john_doe",
  "identifier": "uuid-string",
  "otp": "123456"
}
```

**Response**:
```json
{
  "message": "OTP verified successfully, you may proceed",
  "code": 200,
  "res_data": {
    "user_id": "user_id_string"
  },
  "status": "success"
}
```

**Error Responses**:
- `400`: Invalid OTP, missing fields
- `409`: User with phone number or username already exists
- `500`: Server error

---

### 4. Login User

Login with phone/password or phone/OTP.

**Endpoint**: `POST /auth/v1/login`

**Authentication**: Not required

**Request Body**:
```json
{
  "phone_number": "9999999990",
  "auth_type": "phone_password",
  "password": "user_password",
  "fcm_token": "fcm_token_string",
  "device_id": "device_id_string",
  "device_type": "android",
  "latitude": "12.9716",
  "longitude": "77.5946"
}
```

**Auth Types**:
- `phone_password`: Login with phone and password
- `phone_otp`: Login with phone and OTP (requires OTP verification first)

**Response**:
```json
{
  "code": 200,
  "statusMessage": "success",
  "message": "Login successful.",
  "data": {
    "token": "jwt_token_string",
    "user": {
      "user_id": "user_id_string",
      "username": "john_doe",
      "phone_number": "9999999990",
      "is_profile_complete": "Y",
      "n_score_status": "PENDING"
    }
  }
}
```

**Error Responses**:
- `400`: Invalid credentials or missing fields
- `401`: Phone number not found or invalid auth_type
- `500`: Server error

---

### 5. Register User

Complete user profile after OTP verification.

**Endpoint**: `POST /auth/v1/register`

**Authentication**: Not required

**Request Body**:
```json
{
  "user_id": "user_id_string",
  "username": "john_doe",
  "city": "Bangalore",
  "state": "Karnataka",
  "profile_image": "image_url",
  "password": "user_password",
  "fcm_token": "fcm_token_string",
  "device_id": "device_id_string",
  "device_version": "13",
  "device_name": "Samsung Galaxy",
  "latitude": "12.9716",
  "longitude": "77.5946"
}
```

**Response**:
```json
{
  "code": 200,
  "status": "success",
  "message": "Profile completed successfully",
  "res_data": {
    "user_id": "user_id_string",
    "username": "john_doe",
    "fullname": "john_doe"
  }
}
```

**Error Responses**:
- `400`: Missing required fields
- `404`: User not found
- `500`: Server error

---

### 6. Complete Profile

Complete user profile with additional details for N-Score calculation.

**Endpoint**: `POST /auth/v1/complete_profile`

**Authentication**: Not required

**Request Body**:
```json
{
  "user_id": "user_id_string",
  "family_size": 4,
  "annual_income": 500000,
  "business_location": "Bangalore",
  "gender": "Male",
  "marital_status": "Married",
  "working_members": 2,
  "no_of_child": 1,
  "current_city": "Bangalore",
  "current_pincode": "560001",
  "current_address": "123 Main Street",
  "permant_address": "456 Permanent Street",
  "permant_city": "Mumbai",
  "permant_pincode": "400001",
  "dob": "1990-01-01",
  "address": "123 Main Street",
  "profile_pic": "image_url"
}
```

**Required Fields**:
- `user_id`
- `family_size`
- `annual_income`
- `business_location`

**Response**:
```json
{
  "code": 200,
  "status": "success",
  "message": "Profile details saved successfully. Risk assessment queued.",
  "data": {
    "user_id": "user_id_string",
    "n_score_status": "PENDING"
  }
}
```

**Error Responses**:
- `400`: Missing required fields or invalid user_id
- `404`: User not found
- `500`: Server error

---

### 7. Get All Roles

Retrieve all available user roles.

**Endpoint**: `GET /auth/api/roles`

**Authentication**: Not required

**Response**:
```json
{
  "success": true,
  "message": "Roles fetched successfully",
  "data": [
    {
      "_id": "role_id_string",
      "ROLE_NAME": "Customer"
    }
  ]
}
```

**Error Responses**:
- `500`: Server error

---

## User Management Endpoints

### 8. Get User Details (v1)

Get comprehensive user details including KYC, loan information, and N-Score.

**Endpoint**: `GET /auth/v1/get_users_details/<user_id>`

**Authentication**: Not required

**Path Parameters**:
- `user_id` (string, required): User ID

**Response**:
```json
{
  "success": true,
  "n_score": 750.5,
  "user_details": {
    "user_id": "user_id_string",
    "full_name": "John Doe",
    "username": "john_doe",
    "phone_number": "9999999990",
    "country_code": "+91",
    "gender": "Male",
    "dob": "1990-01-01",
    "profile_pic": "image_url",
    "is_active": "Y",
    "aadhar_verified": true,
    "pan_verified": true,
    "upi_verified": true,
    "kyc_completed": true,
    "annual_income": 500000,
    "business_location": "Bangalore",
    "family_size": 4,
    "marital_status": "Married",
    "working_members": 2,
    "no_of_child": 1,
    "current_address": "123 Main Street",
    "current_city": "Bangalore",
    "current_pincode": "560001",
    "permant_address": "456 Permanent Street",
    "permant_city": "Mumbai",
    "permant_pincode": "400001"
  },
  "loan_details": {
    "loan_external_id": "loan_ext_id",
    "product_id": "product_id",
    "principal_amount": 100000,
    "total_repayment_expected": 120000,
    "installment_amount": 10000,
    "interest_rate": 12.5,
    "outstanding_balance": 80000,
    "paid_amount": 40000,
    "penalty_due": 0,
    "currency": "INR",
    "status": "ACTIVE",
    "sub_status": "CURRENT",
    "dpd": 0,
    "start_date": "2024-01-01",
    "maturity_date": "2024-12-31",
    "last_payment_date": "2024-06-01"
  }
}
```

**Note**: If user has no active loan, `fpl_products` array is returned instead of `loan_details`.

**Error Responses**:
- `404`: User not found
- `500`: Server error

---

### 9. Get User Details (v2)

Get user details (v2) - similar to v1 but with updated logic for loan/FPL products.

**Endpoint**: `GET /auth/v2/get_users_details/<user_id>`

**Authentication**: Not required

**Path Parameters**:
- `user_id` (string, required): User ID

**Response**: Same structure as v1, but `fpl_products` is returned only if no loan exists.

**Error Responses**:
- `404`: User not found
- `500`: Server error

---

## Loan Management Endpoints

### 10. Initialize Loan

Create a new loan for a user.

**Endpoint**: `POST /auth/v1/intialize_loan`

**Authentication**: Not required

**Request Body**:
```json
{
  "user_id": "user_id_string",
  "amount_disbursed": "100000",
  "payback_amount": "120000",
  "purpose": "Business Expansion",
  "initial_edi": "750",
  "type": "PERSONAL_LOAN"
}
```

**Required Fields**:
- `user_id`
- `amount_disbursed`
- `payback_amount`
- `purpose`
- `initial_edi`
- `type`

**Response**:
```json
{
  "status": "success",
  "message": "Loan created successfully",
  "loan_id": "loan_id_string"
}
```

**Error Responses**:
- `400`: Missing required fields
- `500`: Server error

---

## Gateway Endpoints

### 11. API Gateway Forwarder

Forward requests to microservices through the API gateway.

**Endpoint**: `/<service>/<path:path>`

**Base Path**: `/gateway`

**Supported Methods**: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`

**Path Parameters**:
- `service` (string, required): Service name (kyc, lpm, leh, game, ads)
- `path` (string, required): Path to forward to the service

**Example**:
```
GET /gateway/kyc/v1/verify
POST /gateway/lpm/v1/products
```

**Request**: All request headers (except `host`), query parameters, and body are forwarded to the downstream service.

**Response**: Returns the response from the downstream service with status code and headers.

**Error Responses**:
- `404`: Service not found
- `500`: Error forwarding request

**Available Services**:
- `kyc`: KYC Service
- `lpm`: LPM Service
- `leh`: LEH Service
- `game`: Game Service
- `ads`: Ads Service

**Note**: Service URLs are configured via environment variables:
- `GATEWAY_KYC_SERVICE`
- `GATEWAY_LPM_SERVICE`
- `GATEWAY_LEH_SERVICE`
- `GATEWAY_GAME_SERVICE`
- `GATEWAY_ADS_SERVICE`

---

## Error Codes

| Code | Description |
|------|-------------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request - Invalid input or missing required fields |
| 401 | Unauthorized - Authentication required or invalid credentials |
| 404 | Not Found - Resource not found |
| 409 | Conflict - Resource already exists |
| 500 | Internal Server Error |

### Error Response Format

```json
{
  "code": 400,
  "status": "fail",
  "message": "Error message description",
  "res_data": {}
}
```

---

## Data Models

### User Object

```json
{
  "_id": "user_id_string",
  "username": "john_doe",
  "fullname": "John Doe",
  "phone_number": "9999999990",
  "country_code": "+91",
  "password": "hashed_password",
  "role_id": "role_id_string",
  "profile_image": "image_url",
  "city": "Bangalore",
  "state": "Karnataka",
  "language": "en",
  "is_profile_complete": "Y",
  "n_score_status": "PENDING",
  "is_active": "Y",
  "created_date": "2024-01-01T00:00:00",
  "modified_date": "2024-01-01T00:00:00",
  "last_login_at": "2024-01-01T00:00:00",
  "fcm_token": "fcm_token_string",
  "devices": [
    {
      "device_type": "android",
      "device_id": "device_id_string",
      "device_name": "Samsung Galaxy",
      "device_version": "13",
      "latitude": "12.9716",
      "longitude": "77.5946"
    }
  ]
}
```

### OTP Request Object

```json
{
  "_id": "otp_id_string",
  "identifier": "uuid_string",
  "type": "phone",
  "otp": "123456",
  "contact": "9999999990",
  "country_code": "+91",
  "created_date": "2024-01-01T00:00:00"
}
```

### Loan Object

```json
{
  "_id": "loan_id_string",
  "CREATED_DATE": "2024-01-01T00:00:00",
  "USER_ID": "user_id_string",
  "DISPURSAL_DATE": "2024-01-01T00:00:00",
  "STATUS": "APPROVED",
  "AMOUNT_DISPURSED": "100000",
  "PAYBACK_AMOUNT": "120000",
  "PURPOSE": "Business Expansion",
  "_class": "com.service.nano.entity.LoanRequest",
  "INITIAL_EDI": "750",
  "TYPE": "PERSONAL_LOAN"
}
```

### User Details Object

```json
{
  "user_id": "user_id_string",
  "family_size": 4,
  "gender": "Male",
  "marital_status": "Married",
  "working_members": 2,
  "annual_income": 500000,
  "no_of_child": 1,
  "current_city": "Bangalore",
  "current_pincode": "560001",
  "current_address": "123 Main Street",
  "permant_address": "456 Permanent Street",
  "permant_city": "Mumbai",
  "permant_pincode": "400001",
  "business_location": "Bangalore",
  "calculation_status": "PENDING",
  "n_score": 750.5,
  "n_score_day": "2024-01-01",
  "created_date": "2024-01-01T00:00:00"
}
```

### KYC Object

```json
{
  "_id": "kyc_id_string",
  "user_id": "user_id_string",
  "aadhar_verified": true,
  "pan_verified": true,
  "upi_verified": true,
  "kyc_completed": true
}
```

---

## External API Integrations

### N-Score Calculation

The API integrates with an external N-Score calculation service:

**Endpoint**: `https://core.nanope.ai/api/nscore/calculate`

**Method**: POST

**Payload**:
```json
{
  "aadhar_verified": true,
  "pan_verified": true,
  "upi_verified": true,
  "kyc_completed": true,
  "annual_income": 500000,
  "business_location": "Bangalore",
  "dob": "1990-01-01",
  "family_size": 4,
  "gender": "Male",
  "marital_status": "Married",
  "working_members": 2
}
```

**Response**:
```json
{
  "total_score": 750.5,
  "nscore": 750.5
}
```

### FPL Products

The API integrates with FPL (Financial Product Lending) service:

**Endpoint**: `https://fpl.nanope.ai/api/lms/productsbyscore`

**Method**: GET

**Query Parameters**:
- `n_score` (float, required): User's N-Score

**Response**: Array of available financial products based on the score.

---

## Environment Variables

The following environment variables are required:

### MongoDB
- `MONGODB_USER_LIVE`
- `MONGODB_PASSWORD_LIVE`
- `MONGODB_HOST_LIVE`
- `MONGODB_PORT_LIVE`
- `MONGODB_DB_LIVE`

### JWT
- `JWT_SECRET_KEY`

### AWS SNS
- `SNS_ACCESS_KEY`
- `SNS_SECRET_ACCESS_KEY`
- `AWS_REGION`

### Gateway Services
- `GATEWAY_KYC_SERVICE`
- `GATEWAY_LPM_SERVICE`
- `GATEWAY_LEH_SERVICE`
- `GATEWAY_GAME_SERVICE`
- `GATEWAY_ADS_SERVICE`

---

## Rate Limiting

Currently, no rate limiting is implemented. Consider implementing rate limiting for production use.

---

## WebSocket Support

The API supports WebSocket connections via Flask-SocketIO. Socket.IO events can be used for real-time communication.

**Connection**: `ws://localhost:5001`

---

## Changelog

### Version 2.0
- Added v2 endpoint for user details retrieval
- Updated loan/FPL product logic

### Version 1.0
- Initial API release
- Authentication endpoints
- User management
- Loan management
- API Gateway

---

## Support

For issues or questions, please contact the development team.

---

**Last Updated**: 2024