Worksheets

Apply the waste-disposal charge

Appends the charge line — quantity 1 at the previewed amount, unit lav, the company's default VAT rate (its first enabled one), last position — recomputes the totals and returns the updated document (as the line-items batch does).

The rules are re-checked server-side and the line is written in one transaction holding the document's row lock, so concurrent calls run one after the other and add the line once. When the charge can't be applied the response is 409 waste_disposal_not_applicable with error.reason (disabled, already_applied, nothing_to_charge, and on worksheets fully_paid). A worksheet behind an issued fiscal document answers 409 conflict.

post/v1/worksheets/{id}/waste-disposal

Request

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

Response

Line added. Returns the updated document (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.