Worksheets

Update a worksheet

Partial update following the standard three-state PATCH semantics (omitted = unchanged, null = clear, value = set).

Only top-level editable fields are exposed here. Use POST /v1/worksheets/{id}/transitions to change status. Line-item mutation is out of scope for v1 — a dedicated sub-resource will land in a later pass.

Fields intentionally NOT patchable: id, company_id, created_by, seq_number, status, customer_id, vehicle_id, all totals, all *_at timestamps, line_items, documents.

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

Frozen worksheets — when the worksheet's linked invoice has been issued, the worksheet is frozen: its totals are now part of the invoice's accounting record and must not desync. PATCH returns 409 conflict. Cancel the invoice with a credit note before editing.

patch/v1/worksheets/{id}

Request

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

Request body

titlestring nullable

commentsstring nullable

internal_commentsstring nullable

assigned_tostring nullable

work_category_idstring nullable

Single-category form for clients that handle one category, accepted in every revision with the same meaning: a value replaces the first category of the list and keeps the others; null removes the first one. To set or clear the full list, send work_category_ids instead (not both).

work_category_idsstring[] nullable

Replaces the document's whole category list, in the order given. Omitted → untouched; [] or null → removes every category; a list → becomes the new list. Same validation as on create (max 10, de-duplicated, company's categories only). Do not send together with work_category_id: both → 422 parameter_invalid. Available since revision 2026-10-03.

kmnumber nullable

total_work_costnumber nullable

Sets the internal labour cost by hand (0 included); line changes no longer move it. null goes back to automatic (the lines' sum). Omitted → untouched. Negative → 422.

total_article_costnumber nullable

Same as total_work_cost, for the parts cost.

Response

Worksheet updated. Returns the full post-update entity.

object'worksheet' required

idstring required

seq_numberinteger required

Per-company human-friendly sequence number. Allocated server-side at creation; never reused.

titlestring nullable

commentsstring nullable

internal_commentsstring nullable

Workshop-internal notes; surfaced through the mobile app for the workshop's own users (no customer-facing channel exposes this field).

customer_idstring required

vehicle_idstring nullable

assigned_tostring nullable

work_category_idstring nullable

kmnumber nullable

Odometer reading captured when the worksheet was opened. Free-form decimal because some workshops record fuel mileage or hour-meter values in the same field.

created_bystring required

created_by_full_namestring

Display string of the user who created the worksheet — denormalized for list rendering without a join.

customer_namestring

vehicle_namestring nullable

vehicle_licensestring nullable

work_category_namestring nullable

work_category_idsstring[] required

Every work category ("categoria") of the document, in the order chosen. work_category_id (kept for clients that handle a single category) always equals the first. [] when the document has none, never null. Available since revision 2026-10-03.

total_before_taxnumber

total_taxnumber

total_after_taxnumber

total_after_discountnumber

total_discountnumber

total_pricenumber

total_paymentsnumber

outstanding_paymentsnumber

fiscal_document_typestring

Which fiscal document the worksheet produces: "fattura" (default) or "scontrino".

invoice_idstring nullable

Detail responses only — the first linked invoice, when one exists. Drives the Vedi Fattura action.

receipt_idstring nullable

Detail responses only — the linked scontrino for scontrino-type worksheets, when one exists.

frozenboolean

Detail responses only (since 2026-07-19) — true when a linked invoice has a non-draft electronic invoice; mutations are rejected with 409 and the app hides/blocks Modifica.

total_work_costnumber

Internal labour cost ex-VAT (Costi di lavorazione): the value typed by hand when work_cost_manual is true, otherwise the sum of the lines' unit_cost × quantity for unit types h, gg, lav, min. Correct on every revision and on list responses since 2026-10-15 (lists used to return 0).

total_article_costnumber

Internal parts cost ex-VAT: the value typed by hand when article_cost_manual is true, otherwise the sum of the other lines' unit_cost × quantity.

work_cost_manualboolean

True when total_work_cost was typed by hand; line changes no longer move it. Reset with PATCH total_work_cost: null.

article_cost_manualboolean

True when total_article_cost was typed by hand.

waiting_atstring date-time nullable

started_atstring date-time nullable

completed_atstring date-time nullable

delivered_atstring date-time nullable

archived_atstring date-time 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/worksheets/{id}. Worksheets with a non-null deleted_at are not returned by list/detail endpoints.

Example response

{
  "id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95"
}

Changes

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