Saltar al contenido principal

Create a new vehicle in the fleet

POST 
/company/vehicles/

Registers a new vehicle in the company's fleet with associated metadata and optional file uploads.

Objective​

Enable companies to add vehicles to their fleet with detailed specifications including cargo types, shipping capabilities, and documentation (images and ITV certificates).

Use Cases​

  • Register a newly acquired vehicle with all specifications
  • Upload vehicle documentation (image, ITV certificate)
  • Set a vehicle as the user's default for digital signature operations
  • Migrate fleet data from external systems

Validation Flow​

flowchart TD
  A[Receive Request] --> B{Payment Limit OK?}
  B -->|No| C[402 Payment Required]
  B -->|Yes| D{User Has Company?}
  D -->|No| E[401 CIA_NOT_FOUND]
  D -->|Yes| F{Required Fields Present?}
  F -->|No| G[400 Validation Error]
  F -->|Yes| H{shipping_type = fresh?}
  H -->|Yes| I{fresh_cargo_temp Valid?}
  I -->|No| J[400 Temp Required]
  I -->|Yes| K[Create Vehicle]
  H -->|No| K
  K --> L{default_vehicle = true?}
  L -->|Yes| M[Update User Default]
  L -->|No| N[Register Billing Usage]
  M --> N
  N --> O[Return Created Vehicle]

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.

Conditional Validation​

  • If shipping_type = 'fresh', the field fresh_cargo_temp is REQUIRED (range: -20 to 40)
  • If shipping_type = 'dry', the field fresh_cargo_temp MUST NOT be sent or must be null

cargo_type Format​

Accepts two formats:

  1. JSON Array: ["up", "lateral", "back"]
  2. Comma-separated string: "up, lateral, back"

Both formats are automatically converted to array internally.

File Uploads​

  • image: Vehicle photo (JPEG, PNG)
  • itv: ITV inspection certificate (PDF, JPEG, PNG)

Files are uploaded to S3/MinIO storage and referenced by key in the response.

Default Vehicle​

If default_vehicle='true', this vehicle is set as the user's default for digital signature operations. The user model is updated to reference this vehicle ID.

Billing Integration​

Creating a vehicle registers a usage event in the billing system for plan consumption tracking.

Request​

Responses​

Vehicle created successfully

Response Headers