Skip to main content

​
Create Implement

Create a new agricultural implement in the system catalog. This endpoint requires administrator authentication.
Authentication Required: This endpoint requires a valid JWT Bearer token with administrator privileges (role_id: 1).

​
Endpoint

POST /api/implements

​
Authentication

Include your JWT token in the Authorization header: 
Authorization: Bearer <your_jwt_token>
See the Authentication Guide for details on obtaining and using tokens.

​
Request Body

​
implement_name
string
required
Name of the implementExample: “3-body disc plow”
​
brand
string
required
Manufacturer brand nameExample: “Baldan”, “Tatu”, “Semeato”
​
power_requirement_hp
number
required
Required horsepower (HP) to operate the implementValidation: Must be a positive numberExample: 50, 85, 120
​
working_width_m
number
required
Working width in metersValidation: Must be a positive numberExample: 0.9, 1.5, 2.4
​
implement_type
string
required
Type of implement. Must be one of:
  • plow - Disc or moldboard plows
  • harrow - Disc or tine harrows
  • seeder - Seed planting equipment
  • sprayer - Pesticide/fertilizer sprayers
  • harvester - Harvesting equipment
  • cultivator - Soil cultivation tools
  • mower - Mowing equipment
  • trailer - Agricultural trailers
  • other - Other agricultural implements
​
soil_type
string
Compatible soil type(s)Common Values: “Loam”, “Clay”, “Sandy”, “Silty”, “All”Example: “Loam”, “Heavy clay”, “All”
​
working_depth_cm
number
Working depth in centimeters (for plows, cultivators, etc.)Validation: Must be a positive number if providedExample: 25, 30, 15
​
weight_kg
number
Implement weight in kilogramsValidation: Must be a positive number if providedExample: 320, 450, 280
​
status
string
default:"available"
Current status of the implement. Must be one of:
  • available - Ready for use (default)
  • maintenance - Under maintenance
  • inactive - Not in service

​
Response

​
success
boolean
Indicates if the implement was created successfully
​
message
string
Success or error message
​
data
object
The newly created implement object with all fields including the generated implement_id and registration_date

​
Examples

​
Create a Plow

curl -X POST http://localhost:4000/api/implements \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "implement_name": "Arado de discos 3 cuerpos",
    "brand": "Baldan",
    "power_requirement_hp": 85,
    "working_width_m": 1.2,
    "soil_type": "clay",
    "working_depth_cm": 30,
    "weight_kg": 450,
    "implement_type": "plow",
    "status": "available"
  }'

​
Create a Seeder

curl -X POST http://localhost:4000/api/implements \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "implement_name": "Sembradora de precisión 8 hileras",
    "brand": "Semeato",
    "power_requirement_hp": 65,
    "working_width_m": 2.4,
    "soil_type": "All",
    "working_depth_cm": 8,
    "weight_kg": 580,
    "implement_type": "seeder"
  }'

​
Response Example (201 Created)

{
  "success": true,
  "message": "Implemento creado exitosamente",
  "data": {
    "implement_id": 15,
    "implement_name": "Arado de discos 3 cuerpos",
    "brand": "Baldan",
    "power_requirement_hp": 85,
    "working_width_m": 1.2,
    "soil_type": "clay",
    "working_depth_cm": 30,
    "weight_kg": 450,
    "implement_type": "plow",
    "status": "available",
    "registration_date": "2026-03-11T14:30:00.000Z"
  }
}

​
Error Responses

​
Validation Error (400)

{
  "success": false,
  "message": "Errores de validación",
  "errors": [
    "implement_name es requerido",
    "power_requirement_hp debe ser un número positivo",
    "implement_type debe ser uno de: plow, harrow, seeder, sprayer, harvester, cultivator, mower, trailer, other"
  ]
}

​
Unauthorized - No Token (401)

{
  "success": false,
  "message": "Token no proporcionado"
}

​
Unauthorized - Invalid Token (401)

{
  "success": false,
  "message": "Token inválido o expirado"
}

​
Forbidden - Not Admin (403)

{
  "success": false,
  "message": "Acceso denegado: se requiere rol de administrador"
}

​
Internal Server Error (500)

{
  "success": false,
  "message": "Error al crear implemento"
}

​
Validation Rules

​
Required Fields

The following fields are required when creating an implement:
  • implement_name (non-empty string)
  • brand (non-empty string)
  • power_requirement_hp (positive number)
  • working_width_m (positive number)
  • implement_type (valid enum value)

​
Implement Type Validation

The implement_type field must be one of: 
plow, harrow, seeder, sprayer, harvester, cultivator, mower, trailer, other

​
Status Validation

If provided, status must be one of: 
available, maintenance, inactive
Default: If not provided, status defaults to available.

​
Numeric Validation

All numeric fields must be positive numbers:
  • power_requirement_hp > 0
  • working_width_m > 0
  • working_depth_cm > 0 (if provided)
  • weight_kg > 0 (if provided)
The validation middleware (src/middleware/validation.middleware.js:65) automatically sanitizes inputs and validates all fields before processing.

​
Implementation Notes

  • Source: src/routes/implement.routes.js:349 - Route definition
  • Controller: src/controllers/implementController.js:159 - createImplement function
  • Model: src/models/Implement.js:19 - create(implementData) method
  • SQL: INSERT INTO implement (...) VALUES (...) RETURNING *
  • Middleware Chain:
    1. verifyTokenMiddleware - Validates JWT token
    2. isAdmin - Checks for admin role (role_id: 1)
    3. validateImplement - Validates request body fields
    4. createImplement - Creates the implement
  • Cache Invalidation: Automatically invalidates cache entries matching *implements* pattern

List Implements

View all created implements

Get Implement

Retrieve a specific implement by ID

Update Implement

Modify an existing implement (Admin only)

Delete Implement

Remove an implement (Admin only)

​
Best Practices

Accurate Power Requirements

Ensure power_requirement_hp reflects realistic tractor power needs based on implement size and soil conditions

Clear Naming

Use descriptive implement names that include key specifications (e.g., “3-body disc plow” vs just “plow”)

Soil Compatibility

Specify accurate soil type compatibility to help users make informed equipment selections

Complete Data

Provide all optional fields (weight, working depth) when available for better recommendations
Implements created via this endpoint are immediately available for use in power calculations and tractor-implement matching recommendations.

Build docs developers (and LLMs) love

Get started for freeTalk to us