Vehicle Integration

The Solicitud Transporte API provides flexible options for creating and managing vehicles: manual entry with complete data or automatic creation using an external plate information API.

Overview

Two approaches for vehicle creation:

Manual Creation - Provide all vehicle data directly
Plate API Integration - Query external plate registry and auto-populate data

Manual Vehicle Creation

Create a vehicle by providing complete information.

curl -X POST https://api.example.com/vehiculo \
  -H "Content-Type: application/json" \
  -d '{
    "placa": "P503067",
    "idClaseVehiculo": 1,
    "idEstadoVehiculo": 1,
    "idTipoCombustible": 1,
    "idMotoristaPorDefecto": 10,
    "idDepartamentoAsignado": 2,
    "marca": "TOYOTA",
    "modelo": "HILUX",
    "anio": 2020,
    "color": "BLANCO",
    "numeroMotor": "1GRFE123456",
    "numeroChasis": "JT123456789012345",
    "numeroVin": "JT123456789012345",
    "capacidadPasajeros": 5,
    "capacidadCombustibleGalones": 80.0,
    "kilometrajeActual": 15000,
    "fechaUltimaRevision": "2024-01-15",
    "fechaProximoMantenimiento": "2024-07-15",
    "fechaTarjetaCirculacion": "2023-12-01",
    "numeroPolizaSeguro": "POL123456789",
    "fechaVencimientoSeguro": "2025-12-01",
    "observaciones": "Vehículo en excelente estado"
  }'

Required Fields

placa - Unique license plate (auto-converted to uppercase, spaces removed)
idClaseVehiculo - Vehicle class ID (must exist and be active)
idEstadoVehiculo - Vehicle state ID (must exist and be active)

Optional Fields

All other fields are optional but recommended for complete vehicle records:

Fuel type, default driver, assigned department
Make, model, year, color
Motor, chassis, and VIN numbers
Passenger and fuel capacity
Maintenance dates and insurance information

Plate normalization: Plates are automatically converted to uppercase with spaces removed. “p 503067” becomes “P503067”.

Reactivation

If you try to create a vehicle with a plate that was previously soft-deleted, the system automatically reactivates the existing record instead of creating a new one.

Creating Vehicles from Plate API

The platform integrates with an external plate information API to automatically retrieve and populate vehicle data.

How It Works

API authentication

The system authenticates with the external plate registry API using credentials from environment variables.

Query vehicle data

Sends the plate number to retrieve complete vehicle information.

Ownership verification

Validates that the vehicle belongs to your institution (configured via PLACA_API_PROPIETARIO_FILTRO).

Class mapping

Automatically maps the vehicle class from the API to your local vehicle class catalog.

Create vehicle

Creates the vehicle record with auto-populated data plus any additional fields you provide.

Making the Request

curl -X POST https://api.example.com/vehiculo/crear-por-placa \
  -H "Content-Type: application/json" \
  -d '{
    "placa": "P503067",
    "idTipoCombustible": 1,
    "idDepartamentoAsignado": 2,
    "observaciones": "Vehículo ingresado desde API de placas"
  }'

Auto-Populated Fields

The plate API automatically provides:

Vehicle make (marca)
Model (modelo)
Year (anio)
Color (color)
Motor number (numeroMotor)
Chassis number (numeroChasis)
VIN number (numeroVin)
Registration card date (fechaTarjetaCirculacion)
Insurance policy number (numeroPolizaSeguro)
Vehicle class (mapped to your catalog)

Ownership Validation

The API only creates vehicles that belong to your institution. If the vehicle owner doesn’t match the configured filter (PLACA_API_PROPIETARIO_FILTRO), you’ll receive a 403 Forbidden error.

403 Response

{
  "success": false,
  "message": "El vehículo no pertenece a la institución",
  "statusCode": 403
}

Class Mapping

The vehicle class returned by the external API must exist in your local ClaseVehiculo catalog. If the class doesn’t exist, you’ll receive a 404 Not Found error asking you to create the class first.

Querying Plate Information

You can query the external plate API without creating a vehicle:

curl https://api.example.com/vehiculo/consulta-placa/P503067

Use this endpoint to preview vehicle data before creating the record, or to verify ownership.

Plate Format Validation

Plates must have:

At least one letter at the beginning
At least four digits after the letters

Examples:

✅ P503067 - Valid
✅ ABC1234 - Valid
❌ 123456 - Invalid (no letters)
❌ P123 - Invalid (less than 4 digits)

Updating Vehicles

Update any vehicle field after creation:

cURL

curl -X PUT https://api.example.com/vehiculo/8 \
  -H "Content-Type: application/json" \
  -d '{
    "kilometrajeActual": 15500,
    "fechaProximoMantenimiento": "2024-08-15",
    "observaciones": "Mantenimiento preventivo realizado"
  }'

All fields in the update are optional. Only provide the fields you want to change.

Managing Vehicle States

Vehicles can have different states (Active, In Maintenance, Out of Service, etc.) managed through the idEstadoVehiculo field:

cURL

curl -X PUT https://api.example.com/vehiculo/8 \
  -H "Content-Type: application/json" \
  -d '{
    "idEstadoVehiculo": 2
  }'

Use the /estado-vehiculo endpoints to retrieve available vehicle states for your application.

Filtering and Searching

Find vehicles with powerful filters:

cURL

curl "https://api.example.com/vehiculo?placa=P5&idClaseVehiculo=1&idEstadoVehiculo=1&pagina=1&por_pagina=20"

Available filters:

placa - Partial plate search
marca - Partial make search
modelo - Partial model search
idClaseVehiculo - Filter by vehicle class
idEstadoVehiculo - Filter by vehicle state
busqueda - Search across plate, make, model, and color

Use /vehiculo/todos/lista for unpaginated results (useful for dropdowns).

Deleting Vehicles

Soft-delete vehicles that are no longer in use:

cURL

curl -X DELETE https://api.example.com/vehiculo/8

Vehicles cannot be deleted if they have active missions assigned. Complete or cancel all missions first.

Integration Configuration

To enable the plate API integration, configure these environment variables:

# Plate API credentials
PLACA_API_URL=https://external-api.gov/placa
PLACA_API_USERNAME=your_username
PLACA_API_PASSWORD=your_password

# Ownership filter (institution name to match)
PLACA_API_PROPIETARIO_FILTRO=MINISTERIO DE OBRAS PÚBLICAS

The PLACA_API_PROPIETARIO_FILTRO value should match exactly how your institution name appears in the external registry.

Error Handling

Common error scenarios:

409 Conflict - Duplicate plate

The plate already exists for an active vehicle. Use PUT to update the existing vehicle instead.

403 Forbidden - Not institution vehicle

The vehicle doesn’t belong to your institution according to the external registry. Cannot create.

404 Not Found - Vehicle class missing

The vehicle class from the external API doesn’t exist in your catalog. Create the class first through /clase-vehiculo endpoint.

404 Not Found - Plate not found

The plate doesn’t exist in the external registry. Use manual creation instead.

502/503/504 - External API error

The external plate API is unavailable or timing out. Try again later or use manual creation.

Best Practices

Prefer plate API when available

Use the plate API integration to ensure data accuracy and reduce manual entry errors.

Query before creating

Use /consulta-placa to preview data and verify ownership before creating a vehicle record.

Maintain vehicle classes catalog

Keep your ClaseVehiculo catalog synchronized with common vehicle types from the external API.

Track maintenance schedules

Use the maintenance date fields (fechaUltimaRevision, fechaProximoMantenimiento) to stay on top of vehicle servicing.

Keep insurance current

Regularly update insurance policy information (numeroPolizaSeguro, fechaVencimientoSeguro) to ensure compliance.

Update mileage after missions

While missions track mileage automatically, update kilometrajeActual if the vehicle is used outside the mission system.

Getting Started

Core Concepts

Guides

Vehicle Integration

Vehicle Integration

Overview

Manual Vehicle Creation

Required Fields

Optional Fields

Reactivation

Creating Vehicles from Plate API

How It Works

Making the Request

Auto-Populated Fields

Ownership Validation

Class Mapping

Querying Plate Information

Plate Format Validation

Updating Vehicles

Managing Vehicle States

Filtering and Searching

Deleting Vehicles

Integration Configuration

Error Handling

Best Practices

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

​Vehicle Integration

​Overview

​Manual Vehicle Creation

​Required Fields

​Optional Fields

​Reactivation

​Creating Vehicles from Plate API

​How It Works

​Making the Request

​Auto-Populated Fields

​Ownership Validation

​Class Mapping

​Querying Plate Information

​Plate Format Validation

​Updating Vehicles

​Managing Vehicle States

​Filtering and Searching

​Deleting Vehicles

​Integration Configuration

​Error Handling

​Best Practices

Build docs developers (and LLMs) love

Vehicle Integration

Overview

Manual Vehicle Creation

Required Fields

Optional Fields

Reactivation

Creating Vehicles from Plate API

How It Works

Making the Request

Auto-Populated Fields

Ownership Validation

Class Mapping

Querying Plate Information

Plate Format Validation

Updating Vehicles

Managing Vehicle States

Filtering and Searching

Deleting Vehicles

Integration Configuration

Error Handling

Best Practices