Skip to main content
POST
/
vehiculo
/
crear-por-placa
Create Vehicle by Plate
curl --request POST \
  --url https://api.example.com/vehiculo/crear-por-placa \
  --header 'Content-Type: application/json' \
  --data '
{
  "placa": "<string>",
  "idTipoCombustible": 123,
  "idDepartamentoAsignado": 123,
  "observaciones": "<string>"
}
'
{
  "success": false,
  "message": "No se encontró información para la placa P503067 en la API externa",
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Endpoint

​
method
string
default:"POST"
POST
​
endpoint
string
/vehiculo/crear-por-placa

​
Description

Creates a vehicle by automatically retrieving vehicle data from an external license plate API. This endpoint simplifies vehicle creation by requiring only the license plate and optional fields, while the system automatically populates most vehicle information.

​
How It Works

1

Authentication

The system authenticates with the external license plate API
2

Data Retrieval

Queries vehicle data from the external API using the provided license plate
3

Owner Verification

Verifies that the vehicle owner belongs to the institution (configurable via PLACA_API_PROPIETARIO_FILTRO environment variable)
4

Class Mapping

Automatically searches for the vehicle class in the catalog based on the name returned by the API
5

Auto-Population

Auto-fills: brand, model, year, color, engine number, chassis number, VIN, circulation card date, and insurance policy
6

Vehicle Creation

Creates the vehicle with the retrieved data and optional IDs provided in the request

​
Request Body

​
placa
string
required
Vehicle license plate to query in the external API. Automatically converted to uppercase and spaces removed.Example: "P503067"
​
idTipoCombustible
integer
ID of the fuel type. Optional. Must exist if provided.Example: 1
​
idDepartamentoAsignado
integer
ID of the assigned department. Optional. Must exist if provided.Example: 2
​
observaciones
string
Additional observations.Example: "Vehículo ingresado desde API de placas"

​
Validations

Important Validations
  • placa: Required
  • Vehicle class: Returned by the API must exist in the system catalog (ClaseVehiculo)
  • Owner verification: Vehicle owner must belong to the institution (see PLACA_API_PROPIETARIO_FILTRO)

​
Auto-Populated Fields

The following fields are automatically populated from the external API:
  • marca - Vehicle brand
  • modelo - Vehicle model
  • anio - Year of manufacture
  • color - Vehicle color
  • numeroMotor - Engine number
  • numeroChasis - Chassis number
  • numeroVin - VIN number
  • fechaTarjetaCirculacion - Circulation card date
  • numeroPolizaSeguro - Insurance policy number
  • idClaseVehiculo - Vehicle class ID (mapped from API response)
  • idEstadoVehiculo - Set to default active state

​
Response

​
success
boolean
Indicates if the operation was successful
​
message
string
Success message: “Vehículo creado exitosamente desde API de placas”
​
data
object
The created vehicle object with all fields populated from the external API and resolved foreign key names
​
timestamp
string
Response timestamp

​
Example Request

{
  "placa": "P503067",
  "idTipoCombustible": 1,
  "idDepartamentoAsignado": 2,
  "observaciones": "Vehículo ingresado desde API de placas"
}

​
Example Response

{
  "success": true,
  "message": "Vehículo creado exitosamente desde API de placas",
  "data": {
    "Id": 1,
    "Placa": "P503067",
    "Marca": "TOYOTA",
    "Modelo": "HILUX 4X4",
    "Anio": 2020,
    "Color": "BLANCO",
    "NumeroMotor": "1GRFE123456",
    "NumeroChasis": "JT123456789012345",
    "NumeroVin": "JT123456789012345",
    "FechaTarjetaCirculacion": "2023-12-01",
    "NumeroPolizaSeguro": "POL123456789",
    "IdClaseVehiculo": 1,
    "NombreClaseVehiculo": "Pick-up",
    "IdEstadoVehiculo": 1,
    "NombreEstadoVehiculo": "Activo",
    "IdTipoCombustible": 1,
    "NombreTipoCombustible": "Diesel",
    "IdDepartamentoAsignado": 2,
    "NombreDepartamentoAsignado": "Logística",
    "Observaciones": "Vehículo ingresado desde API de placas",
    "Eliminado": false,
    "FechaHoraCreacion": "2024-01-15T10:30:00Z",
    "FechaHoraActualizacion": null
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Error Responses

{
  "success": false,
  "message": "No se encontró información para la placa P503067 en la API externa",
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Configuration

Environment Variable: PLACA_API_PROPIETARIO_FILTROThis variable configures which institution owners are allowed. Only vehicles belonging to the configured institution can be created through this endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us