Saltar al contenido principal

Create multiple vehicles from CSV file

POST 
/company/vehicles/bulk/

Enables bulk creation of multiple vehicles from a CSV file upload.

Objective​

Allow companies to efficiently import their entire fleet or large batches of vehicles from external systems or spreadsheets.

Use Cases​

  • Migrate existing fleet from another system
  • Import vehicles from fleet management spreadsheets
  • Bulk onboarding of new vehicles
  • Update multiple vehicles simultaneously

Validation Flow​

flowchart TD
  A[Receive CSV File] --> B{Payment Limit OK?}
  B -->|No| C[402 Payment Required]
  B -->|Yes| D{File Present?}
  D -->|No| E[404 FILE_NOT_FOUND]
  D -->|Yes| F{Parse CSV}
  F --> G{Headers Valid?}
  G -->|No| H[Return ko: MIN_HEADERS]
  G -->|Yes| I{Data Present?}
  I -->|No| J[400 INVALID_DATA]
  I -->|Yes| K[Process Each Line]
  K --> L{Line Valid?}
  L -->|Yes| M[Create Vehicle - Add to ok]
  L -->|No| N[Add to ko with reason]
  M --> O{More Lines?}
  N --> O
  O -->|Yes| K
  O -->|No| P[Update Company]
  P --> Q[Return ok and ko arrays]

Payment Limits​

This endpoint is subject to payment plan limits via the isPaymentUpdate middleware. If the company has reached its vehicle limit, the request will fail with error 402 before processing the CSV.

CSV Structure​

Required headers (minimum):

  • cargo_type
  • vehicle_type
  • plate
  • shipping_type

Optional headers:

  • fresh_cargo_temp

Example CSV:

cargo_type,fresh_cargo_temp,vehicle_type,plate,shipping_type
"up, lateral",-20,f2c,8796HSN,fresh
up,,rt,7628BCB,dry
back,,r3c,4052SMR,dry

Field Formats​

  • cargo_type: Comma-separated string (e.g., "up, lateral, back")
  • vehicle_type: Single type code (e.g., "tir", "van", "f2c")
  • plate: License plate string
  • shipping_type: "fresh" or "dry"
  • fresh_cargo_temp: Number between -20 and 40 (required if shipping_type='fresh')

Response Structure​

Returns object with two arrays:

  • ok: Array of successfully created vehicles
  • ko: Array of failed vehicles with error details

Each failed item includes:

  • line: CSV line number (1-based)
  • reason: Error code
  • data: Original CSV data for that line
  • details: Additional error information (if applicable)

Validation Per Line​

  1. MIN_HEADERS: CSV headers don't contain all required fields
  2. PLATE_INVALID: License plate is empty or invalid
  3. CARGO_TYPE_INVALID: Cargo type contains invalid values
  4. VEHICLE_TYPE_INVALID: Vehicle type is not recognized
  5. SHIPPING_TYPE_INVALID: Shipping type is not 'fresh' or 'dry'
  6. FRESH_CARGO_TEMP_INVALID: Temperature missing, invalid, or out of range for 'fresh'
  7. DRY_CARGO_TEMP_INVALID: Temperature present when shipping_type is 'dry'
  8. CANNOT_SAVE_VEHICLE: Database error saving the vehicle

Partial Success​

The endpoint processes all lines and returns both successful and failed vehicles. If some vehicles fail validation, they appear in the 'ko' array while valid vehicles are still created and appear in the 'ok' array.

Request​

Responses​

Bulk creation completed (may include partial failures). Check 'ok' and 'ko' arrays for results.

Response Headers