Worksheets

Mutate worksheet line items in a batch

Adds, updates, removes, and reorders the worksheet's line items in a single atomic diff, then returns the full worksheet with recomputed totals and the updated line_items array. The top-level worksheet PATCH is metadata-only; all line-item mutation flows through this endpoint.

Operations (all arrays optional; empty body is a no-op): add creates new lines, update replaces an existing line's fields by id, remove deletes lines by id, reorder sets the position of existing untouched lines. An id may appear in at most one of remove/update/reorder.

Update is remove+add internally so article inventory stock reconciles through the normal path; an updated line therefore receives a NEW id in the response — re-read ids from the returned line_items rather than assuming stability.

tax_rate is server-resolved from each line's vat_code; clients never send rates or totals.

Frozen worksheets — blocked when the worksheet's linked invoice has been issued (mutating lines would desync invoice totals). Returns 409 conflict.

post/v1/worksheets/{id}/line-items/batch

Request

  • Base URL: https://api.officina.it
  • URL: https://api.officina.it/v1/worksheets/{id}/line-items/batch
  • Auth: HTTP bearer

Request body

removestring[]

Ids of line items to delete.

Response

Batch applied. Returns the updated worksheet (with line_items).

object'worksheet' required
idstring required
seq_numberinteger required

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

status'draft' | 'waiting' | 'started' | 'completed' | 'delivered' | 'archived' required
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.