Skip to main content

​
Overview

The Vehicles API provides endpoints for complete CRUD operations on vehicle records, including integration with an external license plate API for automated data retrieval.

​
Key Features

  • Complete CRUD Operations: Create, read, update, and delete vehicle records
  • External API Integration: Automatically populate vehicle data from external license plate API
  • Advanced Filtering: Filter vehicles by plate, brand, model, class, and state
  • Pagination Support: Efficient data retrieval with paginated responses
  • Soft Delete: Logical deletion preserves data integrity

​
Available Endpoints

Create Vehicle

Create a new vehicle with complete data

Create by Plate

Create vehicle using external plate API

Query Plate

Query external plate API for vehicle information

List Vehicles

List vehicles with pagination and filters

Get Vehicle

Get a specific vehicle by ID

Update Vehicle

Update an existing vehicle

Delete Vehicle

Delete a vehicle (soft delete)

​
Common Validations

  • Required field
  • Must be unique across all active vehicles
  • Automatically converted to uppercase
  • Spaces are removed
  • If a deleted vehicle with the same plate exists, it will be reactivated
  • Required field
  • Must exist in the system catalog
  • Must be active
  • Required field
  • Must exist in the system catalog
  • Must be active
  • Optional fields (Fuel Type, Default Driver, Assigned Department)
  • If provided, they must exist in their respective catalogs
  • Must be active

​
External API Integration

The system integrates with an external license plate API to automatically retrieve vehicle information:
  1. Authentication: The system authenticates with the external API
  2. Data Retrieval: Vehicle data is fetched by license plate
  3. Owner Verification: Verifies the owner belongs to the institution (configurable via PLACA_API_PROPIETARIO_FILTRO)
  4. Auto-mapping: Automatically finds vehicle class in the catalog
  5. Data Population: Auto-fills brand, model, year, color, engine, chassis, VIN, circulation card date, and insurance policy

​
Response Format

All endpoints return responses in the following format: 
{
  "success": true,
  "message": "Operation completed successfully",
  "data": { /* ... */ },
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Error Handling

Status CodeDescription
400Bad Request - Invalid input data
403Forbidden - Owner doesn’t belong to institution
404Not Found - Resource doesn’t exist
409Conflict - Duplicate plate or active missions
500Internal Server Error
502/503/504External API errors

Build docs developers (and LLMs) love

Get started for freeTalk to us