User Investments

List All User Investments (Admin)

GET /api/listarOportunidadUsuario

Retrieves all user investments in the system.

Admin authentication required

curl -X GET "https://api.investgo.com/api/listarOportunidadUsuario" \
  -H "Authorization: Bearer ADMIN_TOKEN"

[
  {
    "idOportunidadUsuario": 1,
    "idOportunidad": 5,
    "montoInvertido": 5000.00,
    "ganancia": 350.00,
    "estado": "A Tiempo",
    "fecha": "2024-03-15",
    "idEmpresa": 2,
    "usuarioId": 10,
    "oportunidadInversion": {
      "idOportunidad": 5,
      "titulo": "Factoring - Exportación Textil",
      "tasaInteres": 7.0,
      "monto": 50000.00,
      "montoRecaudado": 30000.00
    },
    "empresa": {
      "idEmpresa": 2,
      "razonSocial": "Textiles del Sur SAC",
      "ruc": "20123456789"
    },
    "usuario": {
      "id": 10,
      "nombre": "Juan",
      "apellidoPa": "Pérez",
      "correo": "[email protected]"
    }
  }
]

List Users Invested in an Opportunity

GET /api/listarOpoUsuXOpo/{idOportunidad}

Retrieves all users who have invested in a specific investment opportunity.

idOportunidad

integer

required

Investment opportunity ID

curl -X GET "https://api.investgo.com/api/listarOpoUsuXOpo/5" \
  -H "Authorization: Bearer YOUR_TOKEN"

[
  {
    "idOportunidadUsuario": 1,
    "idOportunidad": 5,
    "montoInvertido": 5000.00,
    "ganancia": 350.00,
    "estado": "A Tiempo",
    "fecha": "2024-03-15",
    "usuarioId": 10,
    "usuario": {
      "id": 10,
      "nombre": "Juan",
      "apellidoPa": "Pérez",
      "correo": "[email protected]"
    }
  },
  {
    "idOportunidadUsuario": 2,
    "idOportunidad": 5,
    "montoInvertido": 10000.00,
    "ganancia": 700.00,
    "estado": "A Tiempo",
    "fecha": "2024-03-16",
    "usuarioId": 15,
    "usuario": {
      "id": 15,
      "nombre": "María",
      "apellidoPa": "González",
      "correo": "[email protected]"
    }
  }
]

List Current User’s Investments

GET /api/listarOpoUsuXIdi

Retrieves all investments made by the authenticated user.

Requires authenticated session. Uses session to identify current user.

curl -X GET "https://api.investgo.com/api/listarOpoUsuXIdi" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Cookie: JSESSIONID=your_session_id"

[
  {
    "idOportunidadUsuario": 1,
    "idOportunidad": 5,
    "montoInvertido": 5000.00,
    "ganancia": 350.00,
    "estado": "A Tiempo",
    "fecha": "2024-03-15",
    "idEmpresa": 2,
    "usuarioId": 10,
    "oportunidadInversion": {
      "idOportunidad": 5,
      "titulo": "Factoring - Exportación Textil",
      "descripcion": "Financiamiento de facturas de exportación",
      "tasaInteres": 7.0,
      "monto": 50000.00,
      "montoRecaudado": 30000.00,
      "plazo": 90,
      "fechaInicio": "2024-03-01",
      "fechaFin": "2024-05-30"
    },
    "empresa": {
      "idEmpresa": 2,
      "razonSocial": "Textiles del Sur SAC",
      "ruc": "20123456789"
    }
  },
  {
    "idOportunidadUsuario": 3,
    "idOportunidad": 8,
    "montoInvertido": 8000.00,
    "ganancia": 480.00,
    "estado": "A Tiempo",
    "fecha": "2024-03-20",
    "idEmpresa": 5,
    "usuarioId": 10,
    "oportunidadInversion": {
      "idOportunidad": 8,
      "titulo": "Factoring - Construcción",
      "tasaInteres": 6.0,
      "monto": 100000.00,
      "montoRecaudado": 45000.00
    }
  }
]

List Current User’s Investments (Paginated)

GET /api/listarOpoUsuXIdi/{page}

Retrieves paginated investments made by the authenticated user.

Requires authenticated session. Returns 6 investments per page.

page

integer

required

Page number (0-based index)

curl -X GET "https://api.investgo.com/api/listarOpoUsuXIdi/0" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Cookie: JSESSIONID=your_session_id"

{
  "content": [
    {
      "idOportunidadUsuario": 1,
      "idOportunidad": 5,
      "montoInvertido": 5000.00,
      "ganancia": 350.00,
      "estado": "A Tiempo",
      "fecha": "2024-03-15",
      "idEmpresa": 2,
      "usuarioId": 10,
      "oportunidadInversion": {
        "idOportunidad": 5,
        "titulo": "Factoring - Exportación Textil",
        "tasaInteres": 7.0,
        "monto": 50000.00,
        "montoRecaudado": 30000.00
      }
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 6,
    "sort": {
      "sorted": false,
      "unsorted": true,
      "empty": true
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalPages": 3,
  "totalElements": 15,
  "last": false,
  "size": 6,
  "number": 0,
  "sort": {
    "sorted": false,
    "unsorted": true,
    "empty": true
  },
  "numberOfElements": 6,
  "first": true,
  "empty": false
}

Register New Investment

POST /api/registaInversionUsuario

Validates user has sufficient wallet balance
Deducts investment amount from user’s wallet
Updates the opportunity’s collected amount
Marks opportunity as “No Activo” if funding goal is reached
Creates the investment record

Requires authenticated session. The system automatically:

Assigns the user ID from the session
Sets the investment date to current date
Sets the investment status to “A Tiempo”

idOportunidad

integer

required

Investment opportunity ID to invest in

montoInvertido

double

required

Amount to invest (must not exceed wallet balance or remaining opportunity amount)

ganancia

double

required

Expected profit from the investment

idEmpresa

integer

required

Company ID associated with the investment opportunity

curl -X POST "https://api.investgo.com/api/registaInversionUsuario" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Cookie: JSESSIONID=your_session_id" \
  -d '{
    "idOportunidad": 5,
    "montoInvertido": 5000.00,
    "ganancia": 350.00,
    "idEmpresa": 2
  }'

{
  "mensaje": "La inversion se realizo con exito",
  "oportunidadInversion": {
    "idOportunidadUsuario": 1,
    "idOportunidad": 5,
    "montoInvertido": 5000.00,
    "ganancia": 350.00,
    "estado": "A Tiempo",
    "fecha": "2024-03-15",
    "idEmpresa": 2,
    "usuarioId": 10
  }
}

User Investment Schema

idOportunidadUsuario

integer

User investment unique identifier

idOportunidad

integer

Investment opportunity ID

oportunidadInversion

object

Investment opportunity details

Show properties

idOportunidad

integer

Opportunity ID

titulo

string

Opportunity title

descripcion

string

Opportunity description

tasaInteres

double

Interest rate percentage

monto

double

Total funding goal amount

montoRecaudado

double

Amount collected so far

plazo

integer

Investment term in days

fechaInicio

date

Opportunity start date

fechaFin

date

Opportunity end date

montoInvertido

double

Amount invested by the user

ganancia

double

Expected profit from the investment

estado

string

Investment status (e.g., “A Tiempo” for on-time)

fecha

date

Investment date (yyyy-MM-dd format)

idEmpresa

integer

Company ID associated with the opportunity

empresa

object

Company details

Show properties

idEmpresa

integer

Company ID

Company legal name

ruc

string

Company tax ID (RUC)

usuarioId

long

User ID who made the investment

usuario

object

User details

Show properties

long

User ID

nombre

string

User’s first name

apellidoPa

string

User’s paternal last name

correo

string

User’s email

Investment Validation Rules

The system enforces strict validation rules when registering investments:

Wallet Balance Validation

User must have sufficient balance in their wallet (cartera)
Investment amount is deducted from wallet immediately
If insufficient balance, transaction fails with status code 409

Example:

User wallet balance: 10,000
Investment amount: 12,000
Result: ❌ Error: “No cuenta con saldo suficiente en su cartera, ¿Desea depositar?.”

Opportunity Amount Validation

Investment cannot exceed the remaining amount needed for the opportunity
Remaining amount = Opportunity goal - Amount already collected
If exceeded, transaction fails with status code 400

Example:

Opportunity goal: 50,000
Already collected: 40,000
Remaining: 10,000
Investment attempt: 15,000
Result: ❌ Error: “La Inversion Excede El Monto Solicitado. Ingrese un inversion menor o igual a: 10000.00”

Funding Goal Completion

When an investment completes the funding goal:

The opportunity status is set to “No Activo”
No more investments can be made in this opportunity
A special success message is returned: “Felicidades!, con su inversion se alcanzo la meta.”

Example:

Opportunity goal: 50,000
Already collected: 45,000
New investment: 5,000
Total after investment: 50,000 (equals goal)
Result: ✓ Success + opportunity marked complete

Investment Flow

Complete Investment Process

User Views Opportunities
```
GET /api/listarOportunidad
```
User browses available investment opportunities
Check Wallet Balance
```
GET /api/detalleCartera
```
User verifies they have sufficient funds
Calculate Investment
- User determines investment amount
- System calculates expected profit based on interest rate
- Example: 5,000 investment × 7% interest = 350 profit

Submit Investment

POST /api/registaInversionUsuario
{
  "idOportunidad": 5,
  "montoInvertido": 5000.00,
  "ganancia": 350.00,
  "idEmpresa": 2
}

System Processing
- ✓ Validate wallet balance (5,000 ≤ wallet balance)
- ✓ Validate opportunity remaining amount
- ✓ Deduct from wallet: wallet balance - 5,000
- ✓ Update opportunity: montoRecaudado + 5,000
- ✓ Check if goal reached (montoRecaudado == monto)
- ✓ Create investment record
View Investment History
```
GET /api/listarOpoUsuXIdi
```
User can see all their investments

Investment Lifecycle

Atomic Transaction Handling

The investment registration process is designed to be atomic:

Transaction Flow:

Update wallet balance (deduct investment)
Update opportunity collected amount
Create investment record

All operations must succeed or all fail together. If any step fails, previous changes should be rolled back (though the current implementation may not fully guarantee this - consider adding proper transaction management).

Error Recovery

Error Scenario	System Response	User Action
Insufficient wallet balance	409 Conflict	Deposit funds to wallet
Investment exceeds remaining	400 Bad Request	Reduce investment amount
Wallet update failed	409 Conflict	Retry or contact support
Opportunity update failed	400 Bad Request	Retry or contact support
Investment record failed	400 Bad Request	Verify wallet & try again
Opportunity not found	400 Bad Request	Verify opportunity exists

Integration with Other Features

Wallet Integration

Investments directly impact user wallet balances: Before Investment:

Wallet balance: 25,000

After 5,000 Investment:

Wallet balance: 20,000
Investment record created
Opportunity collected amount increased by 5,000

Investment Opportunities Integration

Each investment updates the parent opportunity: Before Investment:

{
  "idOportunidad": 5,
  "monto": 50000.00,
  "montoRecaudado": 30000.00,
  "enable": "Activo"
}

After 5,000 Investment:

{
  "idOportunidad": 5,
  "monto": 50000.00,
  "montoRecaudado": 35000.00,  // Increased by 5,000
  "enable": "Activo"  // Still active (not fully funded)
}

After Final Investment Reaches Goal:

{
  "idOportunidad": 5,
  "monto": 50000.00,
  "montoRecaudado": 50000.00,  // Fully funded
  "enable": "No Activo"  // Now closed to new investments
}

Portfolio Management

Users can track their investment portfolio:

curl -X GET "https://api.investgo.com/api/listarOpoUsuXIdi" \
  -H "Authorization: Bearer YOUR_TOKEN"

Investment Status Tracking

The estado field tracks the investment status:

Status	Description
A Tiempo	Investment is on schedule, no delays

Currently, all new investments are automatically set to “A Tiempo”. Future enhancements may include additional statuses such as “Retrasado” (delayed), “Pagado” (paid), or “En Mora” (in default).

Pagination Details

The paginated endpoint (/api/listarOpoUsuXIdi/{page}) returns 6 investments per page:

page

integer

Page number (0-based index)

Page 0: Investments 1-6
Page 1: Investments 7-12
Page 2: Investments 13-18
etc.

Response includes:

content: Array of investments for the current page
totalPages: Total number of pages
totalElements: Total number of investments
first: Whether this is the first page
last: Whether this is the last page
numberOfElements: Number of items in current page

Best Practices

For Users

Check Balance First Always verify your wallet has sufficient funds before attempting to invest
Review Remaining Amount Check how much funding the opportunity still needs to avoid investment rejection
Calculate Expected Returns Use the opportunity’s interest rate to calculate your expected profit
Track Your Portfolio Regularly review your investments using the list endpoints

For Developers

Handle Errors Gracefully Provide clear user feedback for validation errors and insufficient balance
Show Real-Time Updates Update UI immediately after successful investment to show new wallet balance
Implement Retry Logic For transient failures (wallet/opportunity update), implement retry with exponential backoff
Use Pagination For users with many investments, use the paginated endpoint to improve performance
Validate Client-Side Check wallet balance and remaining amount before submitting to reduce failed requests

Authentication

Resources

List All User Investments (Admin)

List Users Invested in an Opportunity

List Current User’s Investments

List Current User’s Investments (Paginated)

Register New Investment

User Investment Schema

Investment Validation Rules

Wallet Balance Validation

Opportunity Amount Validation

Funding Goal Completion

Investment Flow

Complete Investment Process

Investment Lifecycle

Atomic Transaction Handling

Error Recovery

Integration with Other Features

Wallet Integration

Investment Opportunities Integration

Portfolio Management

Investment Status Tracking

Best Practices

For Users

For Developers

Build docs developers (and LLMs) love

Authentication

Resources

​List All User Investments (Admin)

​List Users Invested in an Opportunity

​List Current User’s Investments

​List Current User’s Investments (Paginated)

​Register New Investment

​User Investment Schema

​Investment Validation Rules

​Wallet Balance Validation

​Opportunity Amount Validation

​Funding Goal Completion

​Investment Flow

​Complete Investment Process

​Investment Lifecycle

​Atomic Transaction Handling

​Error Recovery

​Integration with Other Features

​Wallet Integration

​Investment Opportunities Integration

​Portfolio Management

​Investment Status Tracking

​Pagination Details

​Best Practices

​For Users

​For Developers

Build docs developers (and LLMs) love

List All User Investments (Admin)

List Users Invested in an Opportunity

List Current User’s Investments

List Current User’s Investments (Paginated)

Register New Investment

User Investment Schema

Investment Validation Rules

Wallet Balance Validation

Opportunity Amount Validation

Funding Goal Completion

Investment Flow

Complete Investment Process

Investment Lifecycle

Atomic Transaction Handling

Error Recovery

Integration with Other Features

Wallet Integration

Investment Opportunities Integration

Portfolio Management

Investment Status Tracking

Pagination Details

Best Practices

For Users

For Developers