Vehicles

Update a vehicle

Partial update following the design philosophy:

Omitted JSON keys leave the corresponding entity fields untouched.
Explicit JSON null clears the field (SQL NULL).
Concrete values overwrite the entity field.

model and manufacturer_id are NOT NULL in the schema; sending either as null is a 422 parameter_invalid error.

custom_fields is patched as a whole-object replacement (omit = unchanged, null = clear, object = overwrite). Per-key merging is intentionally not supported. Keys and values are validated against the company's definitions — see VehicleCustomFieldValues.

Deadline dates keep their agenda events in step: moving a date moves its event, clearing one removes it, and a request that does not change a date touches no event. This covers next_inspection_at and every custom date field whose definition sets reminder_days_before. Because custom_fields is replaced wholesale, omitting a visible field's key that held a date clears it — and removes that event. Hidden fields keep their values (and events) unless their key is sent; null for the whole object clears visible fields only.

Rental fields are read-only here — use the rental setup flow to change them.

Returns the fully materialized post-update vehicle.

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.

patch/v1/vehicles/{id}

Request

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

Request body

manufacturer_idstring

modelstring

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 updated. Returns the full post-update entity.

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.