Forest Configuration

Overview

The Forest Configuration API provides CRUD operations for forest management reference data:

Species (/api/forest/config/species)
Spacings (/api/forest/config/spacings)
Provenances (/api/forest/config/provenances)
Vegetal Materials (/api/forest/config/vegetal-materials)
Product Types (/api/forest/config/product-types)
Management Schemes (/api/forest/config/management-schemes)
IMA Classes (/api/forest/config/ima-classes)
Inventory Types (/api/forest/config/inventory-types)
Land Use Types (/api/forest/config/land-use-types)
Level 4 Costs (/api/forest/config/level4-costs)

All endpoints follow consistent patterns for list, create, update, and delete operations.

Configuration entities are organization-scoped. Users can only access and modify data for their assigned organization.

Species Management

GET `/api/forest/config/species`

List all species with pagination and search. Authentication: Required
Permissions: forest-config:READ (or any forest-config:CREATE/UPDATE/DELETE)

Query Parameters

page

number

default:"1"

Page number (1-indexed)

limit

number

default:"25"

Items per page (max: 100)

string

Search filter (matches code, scientificName, or commonName)

sortBy

string

default:"createdAt"

Sort field: code, scientificName, commonName, genus, family, taxonomicOrder, isActive, createdAt, updatedAt

sortOrder

string

default:"desc"

Sort order: asc or desc

Response

items

array

Array of species records

pagination

object

total: Total number of records
page: Current page
limit: Items per page
totalPages: Total number of pages

Example: List Species

cURL

curl -X GET "https://api.confor.com/api/forest/config/species?page=1&limit=25&search=Pinus" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "items": [
    {
      "id": "species_001",
      "organizationId": "org_123",
      "code": "PIN-CAR",
      "scientificName": "Pinus caribaea",
      "commonName": "Pino Caribe",
      "genus": "Pinus",
      "family": "Pinaceae",
      "taxonomicOrder": "Pinales",
      "isActive": true,
      "createdAt": "2026-01-15T08:00:00Z",
      "updatedAt": "2026-01-15T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "page": 1,
    "limit": 25,
    "totalPages": 2
  }
}

POST `/api/forest/config/species`

Create a new species. Authentication: Required
Permissions: forest-config:CREATE

Request Body

code

string

required

Unique species code (organization-scoped)

scientificName

string

required

Scientific name (binomial nomenclature)

commonName

string

required

Common name in local language

genus

string

required

Taxonomic genus

family

string

required

Taxonomic family

taxonomicOrder

string

required

Taxonomic order

isActive

boolean

default:"true"

Active status

Response

Returns the created species record.

Example: Create Species

cURL

curl -X POST https://api.confor.com/api/forest/config/species \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "EUC-GRA",
    "scientificName": "Eucalyptus grandis",
    "commonName": "Eucalipto Grande",
    "genus": "Eucalyptus",
    "family": "Myrtaceae",
    "taxonomicOrder": "Myrtales",
    "isActive": true
  }'

PATCH `/api/forest/config/species`

Update an existing species. Authentication: Required
Permissions: forest-config:UPDATE

Request Body

string

required

Species UUID to update

code

string

Updated code

scientificName

string

Updated scientific name

commonName

string

Updated common name

genus

string

Updated genus

family

string

Updated family

taxonomicOrder

string

Updated taxonomic order

isActive

boolean

Active status

Response

Returns the updated species record.

DELETE `/api/forest/config/species`

Delete a species. Authentication: Required
Permissions: forest-config:DELETE

Request Body

string

required

Species UUID to delete

Response

string

Deleted species UUID

Cannot delete a species that has related vegetal materials. Returns 409 Conflict with error: "No se puede eliminar la especie porque tiene materiales vegetales relacionados"

Spacings Management

GET `/api/forest/config/spacings`

List all planting spacings. Authentication: Required
Permissions: forest-config:READ

Query Parameters

Same as species endpoint: page, limit, search, sortBy, sortOrder Search fields: code, name
Sort fields: code, name, isActive, createdAt, updatedAt

Response

Returns paginated list of spacing records:

{
  "id": "spacing_001",
  "organizationId": "org_123",
  "code": "3X2",
  "name": "3m x 2m",
  "description": "Espaciamiento estándar para pino",
  "betweenRowsM": 3.0,
  "betweenTreesM": 2.0,
  "treeDensityPerHa": 1666.67,
  "isActive": true,
  "createdAt": "2026-01-15T08:00:00Z",
  "updatedAt": "2026-01-15T08:00:00Z"
}

POST `/api/forest/config/spacings`

Create a new spacing configuration. Authentication: Required
Permissions: forest-config:CREATE

Request Body

code

string

required

Unique spacing code

name

string

required

Spacing name/label

description

string

Optional description

betweenRowsM

number

Distance between rows in meters

betweenTreesM

number

Distance between trees in meters

treeDensityPerHa

number

Tree density per hectare (calculated or manual)

isActive

boolean

default:"true"

Active status

PATCH `/api/forest/config/spacings`

Update a spacing configuration. Authentication: Required
Permissions: forest-config:UPDATE

Request Body

Same fields as POST, with id required.

DELETE `/api/forest/config/spacings`

Delete a spacing configuration. Authentication: Required
Permissions: forest-config:DELETE

Request Body

string

required

Spacing UUID to delete

Import/Export Operations

All configuration entities support bulk import/export operations.

Export Configuration Data

Endpoints:

GET /api/forest/config/species/export?format=csv|xlsx
GET /api/forest/config/spacings/export?format=csv|xlsx
GET /api/forest/config/provenances/export?format=csv|xlsx
etc.

Authentication: Required
Permissions: forest-config:READ

Query Parameters

format

string

default:"csv"

Export format: csv or xlsx

Response

Returns a downloadable file with all active records for the organization.

Example: Export Species to Excel

cURL

curl -X GET "https://api.confor.com/api/forest/config/species/export?format=xlsx" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o species_export.xlsx

Import Configuration Data

Endpoints:

POST /api/forest/config/species/import
POST /api/forest/config/spacings/import
POST /api/forest/config/provenances/import
etc.

Authentication: Required
Permissions: forest-config:CREATE

Request

file

required

CSV or Excel file with configuration data. Must include all required fields.

Response

imported

number

Number of successfully imported records

failed

number

Number of failed records

errors

array

Array of error messages for failed records

Example: Import Spacings

cURL

curl -X POST https://api.confor.com/api/forest/config/spacings/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

Response

{
  "imported": 12,
  "failed": 1,
  "errors": [
    "Fila 5: Ya existe un registro con el código '3X2'"
  ]
}

Download an export file as a template to ensure correct column structure for imports.

Other Configuration Entities

The following entities follow the same CRUD pattern:

Provenances

Endpoint: /api/forest/config/provenances
Fields: code, name, description, country, region, isActive

Vegetal Materials

Endpoint: /api/forest/config/vegetal-materials
Fields: code, name, description, speciesId, provenanceId, isActive
Relations: Requires valid speciesId and provenanceId

Product Types

Endpoint: /api/forest/config/product-types
Fields: code, name, description, unitOfMeasure, isActive

Management Schemes

Endpoint: /api/forest/config/management-schemes
Fields: code, name, description, rotationYears, isActive

IMA Classes

Endpoint: /api/forest/config/ima-classes
Fields: code, name, description, minValue, maxValue, isActive
Note: IMA = Incremento Medio Anual (Mean Annual Increment)

Inventory Types

Endpoint: /api/forest/config/inventory-types
Fields: code, name, description, isActive

Land Use Types

Endpoint: /api/forest/config/land-use-types
Fields: code, name, category, surfaceHa, isActive
Note: surfaceHa is automatically calculated from Level 4 geometries

Level 4 Costs

Endpoint: /api/forest/config/level4-costs
Fields: level4Id, costTypeCode, costTypeDescription, amountUsd, currencyCode, costDate
Note: Links cost data to specific Level 4 geometries

Validation Rules

Code Uniqueness

All code fields must be unique within the organization
Duplicate codes return 409 Conflict with message: "Ya existe un registro con ese código"

Referential Integrity

Cannot delete entities with active relationships (e.g., species with vegetal materials)
Returns 409 Conflict with descriptive message

Organization Scoping

All queries are automatically filtered by organizationId from authenticated user
Super admins can access all organizations’ data

Audit Logging

All create, update, and delete operations are automatically logged to the AuditLog table:

Audit Log Entry

{
  "userId": "user_123",
  "action": "CREATE",
  "entityType": "Species",
  "entityId": "species_001",
  "oldValues": null,
  "newValues": {
    "code": "PIN-CAR",
    "scientificName": "Pinus caribaea",
    "commonName": "Pino Caribe"
  },
  "timestamp": "2026-03-09T10:15:30Z"
}

Audit logs are partitioned by month for efficient querying and archival.

Error Responses

Status Code	Error	Cause
`400`	`Parámetros inválidos`	Invalid query parameters or request body
`400`	`Datos inválidos`	Schema validation failure (missing required fields, invalid types)
`403`	`Forbidden`	Insufficient permissions
`404`	`Registro no encontrado`	Entity ID doesn’t exist
`409`	`Ya existe un registro con ese código`	Code uniqueness violation
`409`	`No se puede eliminar...`	Referential integrity violation
`500`	`No fue posible...`	Unexpected server error

Permissions Summary

Action	Required Permission
List/Read	`forest-config:READ` (or any write permission)
Create	`forest-config:CREATE`
Update	`forest-config:UPDATE`
Delete	`forest-config:DELETE`
Import	`forest-config:CREATE`
Export	`forest-config:READ`

Super admins bypass permission checks and have full access.

Geospatial Import - Uses land use types from configuration
Forest Patrimony - Links to species, spacings, and other configs

Authentication

Organizations

Forest Patrimony

Biological Assets

Geospatial

Configuration

​Overview

​Species Management

​GET /api/forest/config/species

​Query Parameters

​Response

​Example: List Species

​POST /api/forest/config/species

​Request Body

​Response

​Example: Create Species

​PATCH /api/forest/config/species

​Request Body

​Response

​DELETE /api/forest/config/species

​Request Body

​Response

​Spacings Management

​GET /api/forest/config/spacings

​Query Parameters

​Response

​POST /api/forest/config/spacings

​Request Body

​PATCH /api/forest/config/spacings

​Request Body

​DELETE /api/forest/config/spacings

​Request Body

​Import/Export Operations

​Export Configuration Data

​Query Parameters

​Response

​Example: Export Species to Excel

​Import Configuration Data

​Request

​Response

​Example: Import Spacings

​Other Configuration Entities

​Provenances

​Vegetal Materials

​Product Types

​Management Schemes

​IMA Classes

​Inventory Types

​Land Use Types

​Level 4 Costs

​Validation Rules

​Code Uniqueness

​Referential Integrity

​Organization Scoping

​Audit Logging

​Error Responses

​Permissions Summary

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Species Management

GET `/api/forest/config/species`

Query Parameters

Response

Example: List Species

POST `/api/forest/config/species`

Request Body

Response

Example: Create Species

PATCH `/api/forest/config/species`

Request Body

Response

DELETE `/api/forest/config/species`

Request Body

Response

Spacings Management

GET `/api/forest/config/spacings`

Query Parameters

Response

POST `/api/forest/config/spacings`

Request Body

PATCH `/api/forest/config/spacings`

Request Body

DELETE `/api/forest/config/spacings`

Request Body

Import/Export Operations

Export Configuration Data

Query Parameters

Response

Example: Export Species to Excel

Import Configuration Data

Request

Response

Example: Import Spacings

Other Configuration Entities

Provenances

Vegetal Materials

Product Types

Management Schemes

IMA Classes

Inventory Types

Land Use Types

Level 4 Costs

Validation Rules

Code Uniqueness

Referential Integrity

Organization Scoping

Audit Logging

Error Responses

Permissions Summary

Related Endpoints