Skip to main content

​
Prerequisites

Before you begin, ensure:
  • CONFOR is installed and running (see Installation)
  • You can access the application at http://localhost:3000 (or your configured URL)
  • PostgreSQL database is running and migrated

​
Getting Started

This guide will walk you through creating your first account, logging in, and setting up your initial forest patrimony structure.
1

Register Your Account

Navigate to the registration page and create your account:
http://localhost:3000/auth/register
Fill in the registration form:
{
  "email": "[email protected]",
  "firstName": "Juan",
  "lastName": "Pérez",
  "password": "SecurePass123!"
}
Upon registration, your account will be in PENDING_VERIFICATION status. A default organization “Por defecto” is automatically created and assigned to your user with a USER role.
The system will respond:
{
  "message": "Cuenta creada. Pendiente de aprobacion por un ADMIN."
}
2

Activate Your Account (Development)

For development environments, you can use the seeded admin account to activate your user:Seeded Admin Credentials:Login as admin and navigate to:
http://localhost:3000/dashboard/users
Find your user and update the status from PENDING_VERIFICATION to ACTIVE.
In production, implement a proper email verification workflow using the EmailVerificationToken model included in the system.
3

Login to Your Account

Once activated, login with your credentials:
http://localhost:3000/auth/login
The system uses NextAuth v5 with credentials provider. Successful login creates a session and redirects you to the dashboard.
// Login request
POST /api/auth/login-validation
{
  "email": "[email protected]",
  "password": "SecurePass123!"
}
After 5 failed login attempts, your account will be locked. The lockedUntil field tracks temporary locks.
4

Navigate to Forest Patrimony

From the dashboard, navigate to the Forest Patrimony module:
http://localhost:3000/dashboard/patrimonio-forestal
You’ll see a 5-tab interface:
  • Nivel 2 - Properties (Finca/Predio/Hato/ABRAE)
  • Nivel 3 - Compartments (Lote/Compartimiento/Block)
  • Nivel 4 - Stands (Rodal/Parcela/Enumeration)
  • Nivel 5 - Plots (Subunidad/Subparcela/Muestra)
  • Colindantes - Neighbors
5

Create Your First Finca (Level 2)

Create a top-level property:
  1. Click the Nivel 2 tab
  2. Fill in the creation form:
{
  code: "FINCA-001",           // Unique identifier
  name: "Finca San José",      // Property name
  type: "FINCA",               // FINCA | PREDIO | HATO | FUNDO | HACIENDA | ABRAE
  legalStatus: "ADQUISICION",  // ADQUISICION | ARRIENDO | USUFRUCTO | COMODATO | DECRETO
  totalAreaHa: "150.50"        // Total area in hectares
}
Click Crear to submit.
The system automatically associates the Finca with your current organization. Multi-organization isolation is enforced at the database level.
The API endpoint:
POST /api/forest/patrimony
{
  "level": "2",
  "data": {
    "code": "FINCA-001",
    "name": "Finca San José",
    "type": "FINCA",
    "legalStatus": "ADQUISICION",
    "totalAreaHa": 150.50
  }
}
6

Create a Lote (Level 3)

Now create a compartment within your Finca:
  1. Select your newly created Finca from the Nivel 2 list
  2. Click the Nivel 3 tab
  3. Fill in the form:
{
  code: "LOTE-A",              // Unique within parent Level 2
  name: "Lote Norte",
  type: "LOTE",                // COMPARTIMIENTO | BLOCK | SECCION | LOTE | ZONA | BLOQUE | ZONIFICACION
  totalAreaHa: "45.75"
}
Level 3 codes must be unique within their parent Level 2. The system enforces this with a compound unique index: [level2Id, code]
API call:
POST /api/forest/patrimony
{
  "level": "3",
  "data": {
    "level2Id": "<finca-uuid>",
    "code": "LOTE-A",
    "name": "Lote Norte",
    "type": "LOTE",
    "totalAreaHa": 45.75
  }
}
7

Create a Rodal (Level 4)

Create a stand within your Lote:
  1. Select your Lote from the Nivel 3 list
  2. Click the Nivel 4 tab
  3. Complete the form:
{
  code: "RODAL-001",           // Unique within parent Level 3
  name: "Rodal Pinos 2020",
  type: "RODAL",               // RODAL | PARCELA | ENUMERATION | UNIDAD_DE_MANEJO | CONUCO | OTRO_USO
  fscCertificateStatus: "SI", // SI | NO
  totalAreaHa: "12.30",
  currentLandUseName: "Plantación Pinus caribaea",
  rotationPhase: "Fase 1 - Crecimiento"
}
Level 4 is where geospatial data is attached. You can upload shapefiles to automatically calculate areas and centroids for multiple stands at once.
8

Add Neighbors (Optional)

Document adjoining properties for your Finca:
  1. Select your Finca in Nivel 2
  2. Click the Colindantes tab
  3. Add neighbor information:
{
  code: "COLIND-NORTE",
  name: "Finca El Pinar",
  type: "Propiedad Privada"
}
API endpoint:
POST /api/forest/patrimony/neighbors
{
  "level2Id": "<finca-uuid>",
  "code": "COLIND-NORTE",
  "name": "Finca El Pinar",
  "type": "Propiedad Privada"
}
9

Import Bulk Data (Optional)

You can import multiple units at once using CSV or XLSX files:

​
CSV Format for Level 2:

code,name,type,legalStatus,totalAreaHa,ownerRepresentative
FINCA-002,Finca El Bosque,FINCA,ADQUISICION,200.00,María González
FINCA-003,Predio Forestal Sur,PREDIO,ARRIENDO,180.50,Pedro Martínez

​
Import via UI:

  1. Click the Importar button in any level tab
  2. Select your CSV or XLSX file
  3. The system processes and reports results:
{
  "created": 2,
  "updated": 0,
  "skipped": 0,
  "errors": []
}
Import validation is strict. Ensure all required fields are present and codes are unique within their scope.
10

View and Search

Use the built-in search and pagination:
  • Search bar - Filters by code or name across all fields
  • Pagination - Default 25 items per page (configurable)
  • Sorting - Click column headers to sort
  • Export - Download filtered results as CSV or XLSX
Example search query:
GET /api/forest/patrimony?level=2&search=bosque&page=1&limit=25&sortBy=name&sortOrder=asc

​
Next Steps

Now that you have your basic forest structure set up:

Upload Shapefiles

Import geospatial data for Level 4 stands with automatic area calculation

Biological Assets

Track tree inventory, volume, and growth metrics at Level 6

User Management

Add team members and configure role-based access control

API Reference

Integrate CONFOR with your existing systems via REST API

​
Common Operations

​
Editing Records

Click the edit icon on any row to modify: 
PATCH /api/forest/patrimony
{
  "level": "2",
  "id": "<uuid>",
  "data": {
    "name": "Finca San José - Actualizada",
    "totalAreaHa": 155.00,
    "isActive": true
  }
}

​
Deactivating vs Deleting

Prefer setting isActive: false over deletion to maintain historical records: 
// Recommended: Soft delete
{ "isActive": false }

// Use with caution: Hard delete
DELETE /api/forest/patrimony
{ "level": "2", "id": "<uuid>" }

​
Exporting Data

GET /api/forest/patrimony/export?level=2&format=xlsx&limit=1000&sortBy=code&sortOrder=asc
Supported formats: csv, xlsx
Export respects your current search filters and sort preferences. Use this to generate custom reports.

​
Troubleshooting

​
Can’t Create Level 3 Unit

Error: “Nivel 2 requerido” Solution: Ensure you have selected a parent Level 2 (Finca) from the list before attempting to create Level 3.

​
Duplicate Code Error

Error: “El código ya existe” Solution: Codes must be unique within their scope. Level 2 codes are globally unique per organization. Level 3-5 codes must be unique within their parent.

​
Import Fails with Geometry Errors

Error: “Geometrías inválidas” Solution: Ensure your shapefiles contain valid polygon geometries and include a .prj file with proper CRS definition. The system will attempt to transform to EPSG:4326.

​
Get Help

For additional assistance:
  • Check the complete Installation Guide for environment setup
  • Review the API Reference for programmatic access
  • Contact your system administrator for organization-specific configurations

Build docs developers (and LLMs) love

Get started for freeTalk to us