Vehicles

Create a vehicle

Creates a new vehicle in the authenticated user's company. company_id is always derived from the bearer token and created_by from the authenticated user — neither can be set from the body.

Required: model, manufacturer_id.

Rental fields (is_rental, rental_*) are not accepted on create; rental setup is a separate flow.

Creating a vehicle also schedules its deadline events in the agenda: the revisione (next_inspection_at) and every custom date field whose definition sets reminder_days_before (see GET /v1/vehicle-field-settings).

custom_fields is keyed by definition id and validated against the company's definitions — see VehicleCustomFieldValues for the accepted value per type.

Returns the fully materialized vehicle (including the joined manufacturer_name and customer_name).

Foreign-key references in the body (customer_id, etc.) must resolve to resources owned by the authenticated user's company. Unreachable refs return 422 parameter_invalid pointing at the offending field.

post/v1/vehicles

Request

Base URL: https://api.officina.it
URL: https://api.officina.it/v1/vehicles
Auth: HTTP bearer

Request body

manufacturer_idstring required

modelstring required

licensestring nullable

variantstring nullable

vinstring nullable

transmissionstring nullable

engine_power_kwinteger nullable

engine_displacement_ccminteger nullable

engine_codestring nullable

Codice motore. Stored trimmed and upper case (max 64 characters); an empty string or null clears it. When empty, officina.it may fill it from the vehicle's registration data. Shown in the app when field_visibility.engine_code is on.

vehicle_weight_kginteger nullable

engine_categorystring nullable

registered_atstring date-time nullable

Nullable client-supplied RFC 3339 timestamp. Same 1900-01-01 … 2100-12-31 window as WritableTimestamp; null clears the field.

commentsstring nullable

customer_idstring nullable

kmnumber nullable

km_registered_atstring date-time nullable

Nullable client-supplied RFC 3339 timestamp. Same 1900-01-01 … 2100-12-31 window as WritableTimestamp; null clears the field.

last_inspection_atstring date-time nullable

Nullable client-supplied RFC 3339 timestamp. Same 1900-01-01 … 2100-12-31 window as WritableTimestamp; null clears the field.

next_inspection_atstring date-time nullable

Nullable client-supplied RFC 3339 timestamp. Same 1900-01-01 … 2100-12-31 window as WritableTimestamp; null clears the field.

custom_fieldsVehicleCustomFieldValues nullable

The vehicle's custom field values, keyed by definition id from GET /v1/vehicle-field-settings (e.g. cf_3f9b1c). Every key is checked against the company's definitions and each value against its field's type:

string — a JSON string, trimmed.
integer — a JSON integer or a string holding one (90 or "90", so values echoed from custom_field_values are accepted); stored as a JSON integer.
datetime — a YYYY-MM-DD date or an RFC 3339 timestamp, stored as YYYY-MM-DD (the calendar day as written, in the timestamp's own offset). Years must fall between 1900 and 2100. A field whose definition sets reminder_days_before gets an agenda event on that date.

A null or empty value clears that field. An unknown key or a value that does not fit its type is a 422 parameter_invalid with param pointing at it (/custom_fields/<id>). A value sent back exactly as the vehicle stores it is never refused: it is kept as is even if it predates these rules or a change of its field's type, and a key of a deleted field sent back unchanged is dropped. The object replaces the stored one as a whole: a visible field left out is cleared. A hidden field (visible: false in the settings) keeps its stored value unless its key is sent — custom_field_values lists visible fields only, so a client rebuilding this object from it never erases data it could not see.

A stored value that no longer fits its field's type (text left under a field later turned into a date or number) is likewise kept unless its key is sent — clients cannot show it in a typed input, so leaving it out is not a request to clear it. Send the key with null to clear it.

Example request

{
  "custom_fields": {
    "cf_8a2d6f": "Rosso",
    "cf_3f9b1c": "2027-03-31"
  }
}

Response

Vehicle created.

object'vehicle' required

idstring required

licensestring nullable

License plate (regional format, free-form string).

manufacturer_idstring required

manufacturer_namestring required

Joined from the manufacturers table for display. Read-only; mutate via manufacturer_id.

modelstring required

variantstring nullable

vinstring nullable

Vehicle Identification Number.

transmissionstring nullable

engine_power_kwinteger nullable

engine_displacement_ccminteger nullable

engine_codestring nullable

vehicle_weight_kginteger nullable

engine_categorystring nullable

registered_atstring date-time nullable

commentsstring nullable

customer_idstring nullable

customer_namestring nullable

Joined from the owning customer's full_name for display. Read-only; mutate via customer_id.

kmnumber nullable

Most recently recorded odometer reading.

km_registered_atstring date-time nullable

last_inspection_atstring date-time nullable

next_inspection_atstring date-time nullable

next_appointmentstring date-time nullable

Earliest upcoming calendar appointment for this vehicle, computed at read time.

custom_fieldsobject nullable

Raw stored values keyed by custom field definition id (see VehicleCustomFieldValues for the stored shapes). Includes hidden fields, and on older records keys of deleted definitions (dropped on the next PATCH that sends custom_fields).

is_rentalboolean required

Whether this vehicle is part of the workshop's rental fleet. Read-only here — managed by the rental setup flow.

rental_daily_price_before_taxnumber nullable

rental_daily_price_taxnumber nullable

rental_daily_price_after_taxnumber nullable

rental_vat_codestring nullable

rental_daily_discount_ratenumber nullable

created_atstring date-time required

updated_atstring date-time required

deleted_atstring date-time nullable

Soft-deletion timestamp. Populated on the response from DELETE /v1/vehicles/{id}. Vehicles with a non-null deleted_at are not returned by list/detail endpoints — this field appears for the delete response only.

Example response

{
  "id": "2200ab13-7c48-4d52-b6e9-0a4f81c27d3e",
  "documents": [
    {
      "url": "/v1/vehicles/8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55/documents/3b91ee0c-19b4-4f0a-9c2e-7d51a0c88e14/download"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.