Invoice Management

Overview

The Invoice Management feature provides comprehensive functionality for registering and managing company invoices that will be used for factoring and bundled into investment opportunities. The system automatically generates unique invoice codes in the format F-001, F-002, etc., and tracks invoice lifecycle from creation through payment.

Key Capabilities

Auto-Generated Codes

Automatic invoice numbering with F-XXX format for easy identification and tracking

Company Association

Link each invoice to a specific company for organized management

Date Tracking

Track both emission and payment dates for complete lifecycle visibility

Status Management

Enable/disable invoices based on availability for investment opportunities

Data Model

The Factura entity contains the following key fields:

Field	Type	Description
`idFactura`	int	Unique identifier (auto-generated)
`codFactura`	String	Invoice code (F-001, F-002, etc.) - auto-generated
`monto`	double	Invoice amount
`fechaEmision`	Date	Date invoice was issued (auto-set to current date)
`fechaPago`	Date	Expected or actual payment date
`enable`	String	Status: “Activo” (available) or “No Activo” (used/disabled)
`descripcion`	String	Invoice description or notes
`empresa`	Empresa	Associated company entity

When an invoice is bundled into an investment opportunity, its enable status is automatically changed to “No Activo” to prevent reuse.

Workflow

Invoice Registration Process

The system follows this automated workflow when registering a new invoice:

Validate Company
- System verifies the company exists by idEmpresa
- Returns error if company not found
Generate Invoice Code
- Query database for the last invoice number
- Increment by 1
- Format as “F-XXX” (e.g., F-001, F-015, F-123)
Set Automatic Fields
- fechaEmision set to current date
- enable set to “Activo”
- codFactura assigned the generated code
Save Invoice
- Persist to database with all associations
- Return complete invoice object with generated ID

See Code Example: Invoice Registration

// From FacturaController.java:160-200
@PostMapping("/registrarFactura")
public ResponseEntity<?> registrarFactura(@RequestBody Factura factura) {
    // Automatic date assignment
    factura.setFechaEmision(new Date());
    factura.setEnable("Activo");
    
    // Verify company exists
    Optional<Empresa> empresaOptional = empresaService.buscarxId(factura.getEmpresa().getIdEmpresa());
    if (empresaOptional.isEmpty()) {
        return new ResponseEntity<>("Company not found", HttpStatus.NOT_FOUND);
    }
    
    // Generate automatic invoice code
    int ultimoNumeroFactura = facturaService.obtenerUltimoNumeroFactura();
    String nuevoNumeroFactura = "F-" + String.format("%03d", ultimoNumeroFactura + 1);
    factura.setCodFactura(nuevoNumeroFactura);
    
    // Set company and save
    Empresa empresa = empresaOptional.get();
    factura.setEmpresa(empresa);
    
    Factura facturaRegistrada = facturaService.insertarActualizarFactura(factura);
    return ResponseEntity.ok(facturaRegistrada);
}

See full implementation at FacturaController.java:160-200

Main API Endpoints

Invoice CRUD Operations

Create Invoice
Update Invoice
Delete Invoice

POST /api/registrarFactura

Registers a new invoice with automatic code generation.Request Body:

{
  "monto": 15000.0,
  "fechaPago": "2026-06-30",
  "descripcion": "Professional services rendered in Q1 2026",
  "empresa": {
    "idEmpresa": 5
  }
}

Success Response:

{
  "mensaje": "Factura registrada exitosamente",
  "factura": {
    "idFactura": 42,
    "codFactura": "F-042",
    "monto": 15000.0,
    "fechaEmision": "2026-03-05",
    "fechaPago": "2026-06-30",
    "enable": "Activo",
    "descripcion": "Professional services rendered in Q1 2026",
    "empresa": {
      "idEmpresa": 5,
      "nombre": "TechCorp Solutions"
    }
  }
}

fechaEmision, codFactura, and enable are automatically set by the system.

PUT /api/actualizarFactura

Updates invoice details. Preserves system-generated fields.Request Body:

{
  "idFactura": 42,
  "monto": 16500.0,
  "fechaPago": "2026-07-15",
  "descripcion": "Professional services - updated scope",
  "empresa": {
    "idEmpresa": 5
  }
}

Implementation Note: Only monto, fechaPago, and descripcion are updateable. System fields like fechaEmision, codFactura, and enable are preserved.See implementation at FacturaController.java:202-238

DELETE /api/eliminarFactura/{id}

Soft deletes by setting enable to “No Activo”.Path Parameters:

id - Invoice ID to delete

Success Response:

{
  "mensaje": "Se eliminó exitosamente la factura"
}

See implementation at FacturaController.java:240-260

Search and Filter Endpoints

List All Invoices
List Active Invoices
Paginated List
Search by Code

GET /api/listaFacturas

Returns all invoices in the system.See implementation at FacturaController.java:145-150

GET /api/active/listaFactura

Returns only invoices with enable = “Activo” (available for investment opportunities).Response:

[
  {
    "idFactura": 42,
    "codFactura": "F-042",
    "monto": 15000.0,
    "fechaEmision": "2026-03-05",
    "fechaPago": "2026-06-30",
    "enable": "Activo"
  }
]

See implementation at FacturaController.java:137-142

GET /api/listaFacturas/page/{page}

Returns paginated invoices (8 per page).Path Parameters:

page - Page number (0-indexed)

Response:

{
  "content": [ /* 8 invoices */ ],
  "totalPages": 5,
  "totalElements": 38,
  "size": 8,
  "number": 0
}

See implementation at FacturaController.java:153-158

GET /api/buscarfac/{codFactura}

Finds invoice by its unique code.Path Parameters:

codFactura - Invoice code (e.g., “F-042”)

Success Response:

{
  "factura": {
    "idFactura": 42,
    "codFactura": "F-042",
    "monto": 15000.0,
    "enable": "Activo"
  }
}

See implementation at FacturaController.java:64-84

Company-Specific Endpoints

List Invoices by Company

GET /api/facturas/{idEmpresa}

Retrieves all invoices for a specific company.Path Parameters:

idEmpresa - Company ID

Response:

{
  "facturas": [
    {
      "idFactura": 42,
      "codFactura": "F-042",
      "monto": 15000.0,
      "empresa": {
        "idEmpresa": 5,
        "nombre": "TechCorp Solutions"
      }
    }
  ]
}

See implementation at FacturaController.java:87-109

List Active Invoices by Company

GET /api/facturas/activas/{idEmpresa}

Retrieves only active (available) invoices for a specific company.Path Parameters:

idEmpresa - Company ID

Response:

{
  "facturas": [
    {
      "idFactura": 42,
      "codFactura": "F-042",
      "monto": 15000.0,
      "enable": "Activo"
    }
  ]
}

Useful for selecting invoices to bundle into investment opportunities.See implementation at FacturaController.java:112-134

Date Range Search

Search by Date Range

GET /api/facturas/{fechaInicio}/{fechaFin}

Finds invoices within a date range based on fechaEmision.Path Parameters:

fechaInicio - Start date (yyyy-MM-dd)
fechaFin - End date (yyyy-MM-dd)

Example:

GET /api/facturas/2026-01-01/2026-03-31

Response:

{
  "facturas": [
    {
      "idFactura": 42,
      "codFactura": "F-042",
      "fechaEmision": "2026-02-15",
      "monto": 15000.0
    }
  ]
}

See implementation at FacturaController.java:45-60

Invoice Status Lifecycle

Invoices move through the following status transitions:

Created with Activo Status

New invoices are automatically set to “Activo” upon registration, making them available for use in investment opportunities.

Changed to No Activo

When an invoice is bundled into an investment opportunity, the system automatically changes its status to “No Activo” to prevent double-use.This happens in OportunidadInversionController.java:228-234

Manual Deletion

Administrators can soft-delete invoices by calling the delete endpoint, which sets enable to “No Activo”.

Use Cases

Use Case 1: Registering a New Invoice

Scenario: Company “TechCorp Solutions” completed a project and needs to register an invoice for factoring.

Admin verifies the company exists (idEmpresa = 5)
Admin calls POST /api/registrarFactura with:
- monto: 15000.0
- fechaPago: 2026-06-30
- descripcion: “Q1 2026 professional services”
- empresa.idEmpresa: 5
System:
- Queries last invoice number (41)
- Generates code “F-042”
- Sets fechaEmision to current date (2026-03-05)
- Sets enable to “Activo”
- Saves invoice
System returns complete invoice with ID 42 and code F-042

Use Case 2: Finding Available Invoices for an Opportunity

Scenario: Admin wants to create an investment opportunity using TechCorp’s invoices.

Admin calls GET /api/facturas/activas/5
System returns all invoices for company 5 with enable = “Activo”
Admin sees invoice F-042 for $15,000 is available
Admin uses /api/addFactura to add F-042 to the opportunity bundle
When opportunity is created, F-042’s status changes to “No Activo”

Use Case 3: Tracking Invoices by Date Range

Scenario: Admin needs to generate a Q1 2026 invoice report.

Admin calls GET /api/facturas/2026-01-01/2026-03-31
System returns all invoices with fechaEmision in Q1 2026
Admin can analyze:
- Total invoices registered: count
- Total amount: sum of monto
- Companies involved: unique idEmpresa values
- Active vs. used: count by enable status

Use Case 4: Updating Invoice Details

Scenario: Invoice F-042’s payment date needs to be extended.

Admin retrieves invoice: GET /api/buscarfac/F-042
Admin modifies the response, changing:
- fechaPago from 2026-06-30 to 2026-07-15
- monto from 15000.0 to 16500.0 (scope change)
Admin calls PUT /api/actualizarFactura with updated data
System updates only modifiable fields, preserving:
- codFactura (F-042)
- fechaEmision (2026-03-05)
- enable (current status)

Best Practices

Company Validation

Always verify the company exists before creating invoices to maintain data integrity.

Descriptive Notes

Use the descripcion field to provide context about the invoice for future reference.

Date Accuracy

Ensure fechaPago is realistic and allows sufficient time for investment opportunity funding.

Status Monitoring

Monitor invoice status transitions to understand which invoices are being used in active opportunities.

Integration Points

With Investment Opportunities

Invoices are the building blocks of investment opportunities:

Selection: Admin selects active invoices to bundle
Linking: System creates OportunidadFactura junction records
Status Update: Invoice status changes to “No Activo” when bundled
Tracking: Invoices can be queried by opportunity ID

See Investment Opportunities for the complete integration workflow.

With Company Management

Each invoice must be associated with a company:

Validation: Company existence verified during invoice creation
Association: Foreign key relationship via empresa field
Filtering: Invoices can be filtered by company for reporting

Error Handling

Common error scenarios and responses:

Scenario	HTTP Status	Response
Company not found	404 NOT_FOUND	`{"mensaje": "No se encontró la empresa con el id: X"}`
Invoice not found	404 NOT_FOUND	`{"mensaje": "No se encontró la factura con el código: F-XXX"}`
Update non-existent invoice	409 CONFLICT	`{"mensaje": "No existe factura con id: X"}`
Database error	500 INTERNAL_SERVER_ERROR	`{"mensaje": "Error...", "error": "details..."}`

Investment Opportunities - Bundle invoices into investment products
User Management - Control who can create and manage invoices

Get Started

Core Features

Guides

Overview

Key Capabilities

Auto-Generated Codes

Company Association

Date Tracking

Status Management

Data Model

Workflow

Invoice Registration Process

Main API Endpoints

Invoice CRUD Operations

Search and Filter Endpoints

Company-Specific Endpoints

Date Range Search

Invoice Status Lifecycle

Use Cases

Use Case 1: Registering a New Invoice

Use Case 2: Finding Available Invoices for an Opportunity

Use Case 3: Tracking Invoices by Date Range

Use Case 4: Updating Invoice Details

Best Practices

Company Validation

Descriptive Notes

Date Accuracy

Status Monitoring

Integration Points

With Investment Opportunities

With Company Management

Error Handling

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

​Overview

​Key Capabilities

Auto-Generated Codes

Company Association

Date Tracking

Status Management

​Data Model

​Workflow

​Invoice Registration Process

​Main API Endpoints

​Invoice CRUD Operations

​Search and Filter Endpoints

​Company-Specific Endpoints

​Date Range Search

​Invoice Status Lifecycle

​Use Cases

​Use Case 1: Registering a New Invoice

​Use Case 2: Finding Available Invoices for an Opportunity

​Use Case 3: Tracking Invoices by Date Range

​Use Case 4: Updating Invoice Details

​Best Practices

Company Validation

Descriptive Notes

Date Accuracy

Status Monitoring

​Integration Points

​With Investment Opportunities

​With Company Management

​Error Handling

​Related Features

Build docs developers (and LLMs) love

Overview

Key Capabilities

Data Model

Workflow

Invoice Registration Process

Main API Endpoints

Invoice CRUD Operations

Search and Filter Endpoints

Company-Specific Endpoints

Date Range Search

Invoice Status Lifecycle

Use Cases

Use Case 1: Registering a New Invoice

Use Case 2: Finding Available Invoices for an Opportunity

Use Case 3: Tracking Invoices by Date Range

Use Case 4: Updating Invoice Details

Best Practices

Integration Points

With Investment Opportunities

With Company Management

Error Handling

Related Features