Invoices

Update an invoice

Partial update following the design philosophy:

  • Omitted JSON keys leave the corresponding entity fields untouched.
  • Explicit JSON null clears the field (SQL NULL) where the column is nullable.
  • Concrete values overwrite the entity field.

Non-nullable columns (payment_method, payment_condition, payment_due_at, vat_exigibility) reject explicit null with 422 parameter_invalid.

Fields NOT patchable through this endpoint: id, seq_number, status, customer_id, vehicle_id, worksheet_id, all totals, all timestamps except payment_due_at. Line items are not mutable via PATCH. Use POST /v1/invoices/{id}/issue to transition a draft.

patch/v1/invoices/{id}

Request

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

Request body

payment_methodstring
payment_conditionstring
payment_due_atstring date-time

RFC 3339 timestamp supplied by the client. Must fall between 1900-01-01 and 2100-12-31. A year outside that window is a typo (2025 mistyped as 0025 is the common one), and the app's own date pickers refuse the same range — a record written with one would not be editable in the web UI afterwards. Out of range → 422 parameter_invalid with param pointing at the offending field.

vat_exigibilitystring
sezionale_idstring nullable
pa_document_typestring nullable
pa_document_numberstring nullable
pa_document_datestring date-time nullable

Nullable client-supplied RFC 3339 timestamp. Same 1900-01-01 … 2100-12-31 window as WritableTimestamp; null clears the field.

pa_cigstring nullable
pa_cupstring nullable

Response

Invoice updated.

object'invoice' required
idstring required
status'draft' | 'issued' required

Derived from issued_at. Soft-deleted invoices 404 before reaching the client — "deleted" is never emitted.

titlestring nullable
commentsstring nullable
internal_commentsstring nullable
payment_methodstring required
payment_conditionstring required
payment_due_atstring date-time required
vat_exigibilitystring required
sezionale_idstring nullable
pa_document_typestring nullable
pa_document_numberstring nullable
pa_document_datestring date-time nullable
pa_cigstring nullable
pa_cupstring nullable
customer_idstring required
vehicle_idstring nullable
worksheet_idstring nullable
seq_numberinteger required

Per-company monotonic invoice number. 0 on drafts; assigned atomically at issuance.

total_before_taxnumber double required

Money. Float64 — clients render via the workshop locale formatter; avoid arithmetic.

total_taxnumber double required
total_after_taxnumber double required
total_discountnumber double required
total_after_discountnumber double required
total_paymentsnumber double required
outstanding_paymentsnumber double required
customer_namestring required
vehicle_namestring nullable
vehicle_licensestring nullable
created_by_full_namestring required
sezionale_codestring nullable
work_category_namestring nullable
work_category_namesstring[] required

Names of the linked worksheet's work categories, in order. [] when the invoice has no worksheet or the worksheet has none. work_category_name is the first one. Available since revision 2026-10-03.

sdi_statusstring required

Italian SDI e-invoice lifecycle status. Empty string when no e-invoice exists for this invoice. Possible non-empty values: "sent", "rejected", "pending_normal", "pending_warning", "pending_late".

created_atstring date-time required
updated_atstring date-time required
issued_atstring date-time nullable

Populated once the invoice is issued.

deleted_atstring date-time nullable

Soft-deletion timestamp. Populated only on the response from DELETE /v1/invoices/{id}.

Example response

{
  "id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04"
}

Changes

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