Worksheets

Create a worksheet

Creates a new worksheet, owned by the authenticated user's company. Server-controlled fields (id, company_id, created_by, seq_number, status, all *_at timestamps, totals) are filled in automatically. Status always starts as draft.

customer_id is required. Line items are not accepted at creation time — a dedicated sub-resource will add/remove them in a later pass.

Foreign-key references in the body (customer_id, vehicle_id, 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.

post/v1/worksheets

Request

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

Request body

customer_idstring required
vehicle_idstring nullable
titlestring nullable
commentsstring nullable
internal_commentsstring nullable
assigned_tostring nullable
work_category_idstring nullable

Single-category form, accepted in every revision: the document's only category. To set several, send work_category_ids instead (not both).

work_category_idsstring[]

The document's work categories, in the order chosen (work_category_id in responses reports the first). Trimmed and de-duplicated (first occurrence wins); at most 10, each one of the company's categories (GET /v1/work-categories) — an unknown id is reported on /work_category_ids/{i}. Do not send together with work_category_id: both → 422 parameter_invalid. Available since revision 2026-10-03.

kmnumber nullable

Response

Worksheet created. Returns the fully-materialized resource.

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.