Invoices

Create a draft invoice from a worksheet

Snapshots the referenced worksheet's totals and line items into a new draft invoice. The worksheet MUST belong to the authenticated user's company; cross-tenant requests return 404 (same as direct invoice access).

payment_due_at is optional. When omitted the server computes today + the company's default payment term (e.g. 30_days), matching the web flow.

The response includes the materialized line_items array.

post/v1/invoices

Request

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

Request body

worksheet_idstring required

Source worksheet UUID (must belong to caller's company).

payment_methodstring required

Free-form payment method label.

payment_due_atstring date-time nullable

Optional. RFC 3339 between 1900-01-01 and 2100-12-31 (see WritableTimestampNullable). Defaults to today + the company's configured payment term.

Response

Invoice created.

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.