Worksheets

Apply a status transition

Moves the worksheet between lifecycle states. Modeled as an RPC rather than a PATCH on status so the lifecycle is visible in the URL surface and the server retains exclusive control over which *_at columns get stamped.

Supported action values mirror the entity status constants: draft, waiting, started, completed, delivered, archived. Any other value is rejected with 422.

Frozen worksheets — transitions are blocked when the worksheet's linked invoice has been issued. A status flip on a frozen worksheet could trigger downstream side effects (e.g. moving back to draft would unwind the basis the invoice was minted from). Returns 409 conflict.

post/v1/worksheets/{id}/transitions

Request

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

Request body

action'draft' | 'waiting' | 'started' | 'completed' | 'delivered' | 'archived' required

Response

Transition applied. Returns the post-transition entity.

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.